Okta as OIDC IdP

This guide assumes you use Okta as your enterprise identity provider (IdP) and have administrative access to an Okta tenant you can use for testing. If you don’t have one, read Create and configure your Okta tenant.

Configure Okta as the OIDC enterprise identity provider for the XAA Requesting App. You’ll set up an Okta tenant, register the Requesting App and Resource App in Okta, configure an AI Agent, and configure the Okta Workforce Enterprise connections in both the Requesting App and Resource App Auth0 tenants.

Create and configure your Okta tenant

To create and configure your Okta tenant for Cross App Access:

On the Okta Developer website, sign up for an Okta Integrator Free Plan. Once you sign up, you should be redirected to your new Okta tenant.
If Cross App Access is not enabled in your Okta tenant, email developers@okta.com to request XAA enablement for your Okta tenant.

Once you’ve enabled Cross App Access, make sure the following features are toggled on under Okta Admin > Settings > Features in the Okta Admin Console.

Register the Requesting App in Okta

Create the Requesting App in Okta

Your Requesting App is a standard OIDC application. In the Okta Admin Console:

Navigate to Applications and Resources > Applications > Create App Integration.
Select Classic experience > OIDC - OpenID Connect > Web Application and select Next.

Enter an application name.
Under Grant Type, select Authorization Code and Refresh Token.
Under Sign-in redirect URIs, add the callback URL of your Requesting App tenant: https://YOUR_REQUESTING_APP_DOMAIN/login/callback.
Configure Assignments if needed and select Save.

Once you’ve created the Requesting App, Okta assigns it an OIDC Client ID and Client Secret.

Assign the Requesting App to test users

Allow your test user to log in to the Requesting App in Okta. In the Okta Admin Console:

Navigate to Applications and select the Requesting App you created.
Under Assignments, select Assign > Assign to People and select your test user.
Select Save.

Register and configure the AI agent in Okta

In Okta, the AI agent represents the entity that acts on behalf of the user to access the Resource App. You associate the AI Agent with the Requesting App OIDC application you created. When you do, the AI Agent takes on the Requesting App’s OIDC credentials.

Create the AI agent

In the Okta Admin Console, navigate to Directory > AI Agents > Register AI Agent and select Register Manually.

Enter a name for your agent.
Select Allow users to access this agent.
Under Select an existing app, select the Requesting App you created.
(Optional) Assign an owner.
Select Save.

At this stage, your AI agent is STAGED.

Set client registration for the AI agent

Select the AI agent you created.
Select the Client registration tab.
Select Client Secret as the authentication method. Private Key JWT is also supported.
Note the Client ID and Client Secret of the AI agent, which should be the Client ID and Client Secret of the Requesting App OIDC Application you created in your Okta tenant. You’ll need these when configuring the Okta Workforce connection in your Requesting App tenant.

Activate the AI Agent

Under Actions, select Activate and verify that the Managed Status is Active.

Configure the Requesting App connection in Auth0

In your Requesting App Auth0 tenant, create an Okta Workforce Enterprise connection. This connection authenticates your users with Okta and enables the XAA Requesting App role.

Auth0 Dashboard
Management API

Navigate to Authentication > Enterprise > Okta Workforce and select Create Connection.

Enter the following:

Field	Value
Connection name	A unique name for the connection.
Domain	The domain of your Okta tenant, for example `your-okta-tenant.oktapreview.com`.
Client ID	The Client ID of the AI agent (the Requesting App OIDC application you created in your Okta tenant).
Client Secret	The Client Secret of the AI agent (the Requesting App OIDC application you created in your Okta tenant).

Under Cross App Access > Cross App Access Role, select Requesting Application.

The Requesting Application toggle is disabled while the connection uses the front channel. Make sure to set the communication channel to back channel for the connection.

Select Create.

Make a POST call to the Create a Connection endpoint:

curl --request POST 'https://{yourDomain}/api/v2/connections' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "name": "my-okta-workforce-connection",
    "strategy": "okta",
    "options": {
      "domain": "your-okta-tenant.oktapreview.com",
      "client_id": "<AI_AGENT_CLIENT_ID>",
      "client_secret": "<AI_AGENT_CLIENT_SECRET>",
      "scope": "openid profile email offline_access",
      "type": "back_channel",
      "attribute_map": {
        "mapping_mode": "use_map",
        "userinfo_scope": "openid email profile groups offline_access",
        "attributes": {
          "name": "${context.tokenset.name}",
          "email": "${context.tokenset.email}",
          "username": "${context.tokenset.preferred_username}",
          "federated_groups": "${context.userinfo.groups}",
          "federated_locale": "${context.userinfo.locale}",
          "federated_zoneinfo": "${context.userinfo.zoneinfo}"
        }
      }
    },
    "cross_app_access_requesting_app": { "active": true }
  }'

Add offline_access scope and update the user mapping

Auth0 Dashboard
Management API

After creating the connection, select it and navigate to Settings.

Under Scopes, add offline_access to the list of scopes. This enables your application to obtain a refresh token, which is required to perform the refresh token exchange with Token Vault.
Under Mappings, select Okta Basic and add offline_access to the userinfo_scope list in the JSON mapping.

Select Save.

Make a PATCH call to the Update a Connection endpoint:

curl --request PATCH 'https://{yourDomain}/api/v2/connections/{connectionId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "options": {
      "scope": "openid profile email offline_access",
      "attribute_map": {
        "mapping_mode": "use_map",
        "userinfo_scope": "openid email profile groups offline_access",
        "attributes": {
          "name": "${context.tokenset.name}",
          "email": "${context.tokenset.email}",
          "username": "${context.tokenset.preferred_username}",
          "federated_groups": "${context.userinfo.groups}",
          "federated_locale": "${context.userinfo.locale}",
          "federated_zoneinfo": "${context.userinfo.zoneinfo}"
        }
      }
    }
  }'

Enable connection for an application

Auth0 Dashboard
Management API

Before testing the connection, navigate to the Applications tab and enable the connection for at least one application.

Make a PATCH call to the Update a Connection endpoint to add the application’s client_id to the enabled_clients array:

curl --request PATCH 'https://{yourDomain}/api/v2/connections/{connectionId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "enabled_clients": ["{yourApplicationClientId}"]
  }'

Test the connection

Select the Okta Workforce connection you created, then select the three dots and select Try.
Log in with your test user in Okta to verify the connection works.

Once the user successfully logs in, their user profile is created in your Requesting App tenant.

Users must log in with a XAA-enabled enterprise connection at least once so that the user profile exists in Auth0. Auth0 does not support JIT user creation with ID-JAG at the moment.

Register the Resource App in Okta

Create the Resource App in Okta

Your Resource App is also an OIDC web application registered in Okta. In the Okta Admin Console:

Navigate to Applications and Resources > Applications > Create App Integration.
Select Classic experience > OIDC - OpenID Connect > Web Application and select Next.
Enter an application name.
Under Grant Type, select Authorization Code and Refresh Token.
Under Sign-in redirect URIs, add the callback URLs of both the Requesting App tenant and the Resource App tenant:
- https://YOUR_REQUESTING_APP_DOMAIN/login/callback
- https://YOUR_RESOURCE_APP_DOMAIN/login/callback
Configure Assignments if needed.
Select Save.

Assign Resource App to Test Users

Allow your test user to log in to the Resource App in Okta. In the Okta Admin Console:

Navigate to Applications and select the Resource App you created.
Select Assign > Assign to People and select your test user.
Select Save.

Enable Cross App Access for the Resource App

Select the Resource Server tab for the Resource App.
Enable Cross App Access (XAA).
Enter the Issuer URL of the Resource App tenant: https://YOUR_RESOURCE_APP_DOMAIN/.

Auth0 issues and accepts tokens with an issuer URL that must end with a trailing forward slash /.

Leave the Audience/Tenant ID field blank. Auth0 does not support the aud_tenant claim.
Select Save.

Assign the Resource App to the AI agent

In the Okta Admin Console:

Navigate to Directory > AI Agents and select the AI agent you created.
Under Resource Connections, select Add resource connection.
Select Application and then App configured for AI Agent access as the Resource type.
Under Application, select the Resource App you created.
Leave the Resource indicator blank. When left blank, Okta will auto-generate a value.
For AI agent’s client ID registered in this app, enter the Client ID of the Resource App application registered in your Resource App Auth0 tenant.
Optionally, configure scope restrictions.
Select Add.

Configure the Resource App connection in Auth0

In the Resource App Auth0 tenant, create an Okta Workforce Enterprise connection that federates it with Okta and enables the XAA Resource App role.

Auth0 Dashboard
Management API

Navigate to Authentication > Enterprise > Okta Workforce and select Create Connection.

Enter the following:

Field	Value
Connection name	A unique name for the connection.
Domain	The domain of your Okta tenant, for example `your-okta-tenant.oktapreview.com`.
Client ID	The Client ID of the Resource App as registered in Okta.
Client Secret	The Client Secret of the Resource App as registered in Okta.

Under Cross App Access > Cross App Access Role, select Resource Application.

Select Create.

Make a POST call to the Create a Connection endpoint:

curl --request POST 'https://{yourResourceAppDomain}/api/v2/connections' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "name": "my-okta-workforce-connection-resource-app",
    "strategy": "okta",
    "options": {
      "domain": "your-okta-tenant.oktapreview.com",
      "client_id": "<RESOURCE_APP_OKTA_CLIENT_ID>",
      "client_secret": "<RESOURCE_APP_OKTA_CLIENT_SECRET>",
      "scope": "openid profile email offline_access",
      "attribute_map": {
        "mapping_mode": "use_map",
        "userinfo_scope": "openid email profile groups offline_access",
        "attributes": {
          "name": "${context.tokenset.name}",
          "email": "${context.tokenset.email}",
          "username": "${context.tokenset.preferred_username}",
          "federated_groups": "${context.userinfo.groups}",
          "federated_locale": "${context.userinfo.locale}",
          "federated_zoneinfo": "${context.userinfo.zoneinfo}"
        }
      }
    },
    "cross_app_access_resource_app": { "active": true }
  }'

Add offline_access scope and update mappings

Auth0 Dashboard
Management API

After creating the connection, select it and navigate to Settings.

Under Scopes, add offline_access to the list of scopes.
Under Mappings, select Okta Basic and add offline_access to the userinfo_scope list in the JSON mapping.
Select Save.

Make a PATCH call to the Update a Connection endpoint:

curl --request PATCH 'https://{yourResourceAppDomain}/api/v2/connections/{connectionId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "options": {
      "scope": "openid profile email offline_access",
      "attribute_map": {
        "mapping_mode": "use_map",
        "userinfo_scope": "openid email profile groups offline_access",
        "attributes": {
          "name": "${context.tokenset.name}",
          "email": "${context.tokenset.email}",
          "username": "${context.tokenset.preferred_username}",
          "federated_groups": "${context.userinfo.groups}",
          "federated_locale": "${context.userinfo.locale}",
          "federated_zoneinfo": "${context.userinfo.zoneinfo}"
        }
      }
    }
  }'

Enable the connection for the Resource App

Auth0 Dashboard
Management API

Under Applications, enable the Okta Workforce connection for the Resource App application registered in the Resource App tenant.

Make a PATCH call to the Update a Connection endpoint to add the Resource App’s client_id to the enabled_clients array:

curl --request PATCH 'https://{yourResourceAppDomain}/api/v2/connections/{connectionId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "enabled_clients": ["{resourceAppClientId}"]
  }'

Test the connection

Select the Okta Workforce connection you created, then select the three dots and select Try. Log in with your test user to verify the connection works. Once the user successfully logs in, their user profile is created in your Resource App tenant.

Users must log in with a XAA-enabled enterprise connection at least once so that the user profile exists in Auth0. Auth0 does not support JIT user creation with ID-JAG at the moment.

Configure Cross App Access with Token Vault

Once you’ve configured both connections, proceed to Cross App Access with Token Vault to set up the Token Vault integration and test the end-to-end flow.

Publish your Requesting App in OIN

After you’ve configured and tested the end-to-end flow, B2B and SaaS providers can amplify their reach to enterprise customers by publishing their Resource App to the Okta Integration Network (OIN). To learn how, follow the instructions in How to Build and List Secure Cross App Access Connections on OIN.

Set up Auth0 as Resource App

Set up Auth0 as Requesting App

Create and configure your Okta tenant

Register the Requesting App in Okta

Create the Requesting App in Okta

Assign the Requesting App to test users

Register and configure the AI agent in Okta

Create the AI agent

Set client registration for the AI agent

Activate the AI Agent

Configure the Requesting App connection in Auth0

Add offline_access scope and update the user mapping

Enable connection for an application

Test the connection

Register the Resource App in Okta

Create the Resource App in Okta

Assign Resource App to Test Users

Enable Cross App Access for the Resource App

Assign the Resource App to the AI agent

Configure the Resource App connection in Auth0

Add offline_access scope and update mappings

Enable the connection for the Resource App

Test the connection

Configure Cross App Access with Token Vault

Publish your Requesting App in OIN

​Create and configure your Okta tenant

​Register the Requesting App in Okta

​Create the Requesting App in Okta

​Assign the Requesting App to test users

​Register and configure the AI agent in Okta

​Create the AI agent

​Set client registration for the AI agent

​Activate the AI Agent

​Configure the Requesting App connection in Auth0

​Add offline_access scope and update the user mapping

​Enable connection for an application

​Test the connection

​Register the Resource App in Okta

​Create the Resource App in Okta

​Assign Resource App to Test Users

​Enable Cross App Access for the Resource App

​Assign the Resource App to the AI agent

​Configure the Resource App connection in Auth0

​Add offline_access scope and update mappings

​Enable the connection for the Resource App

​Test the connection

​Configure Cross App Access with Token Vault

​Publish your Requesting App in OIN

Create and configure your Okta tenant

Register the Requesting App in Okta

Create the Requesting App in Okta

Assign the Requesting App to test users

Register and configure the AI agent in Okta

Create the AI agent

Set client registration for the AI agent

Activate the AI Agent

Configure the Requesting App connection in Auth0

Add offline_access scope and update the user mapping

Enable connection for an application

Test the connection

Register the Resource App in Okta

Create the Resource App in Okta

Assign Resource App to Test Users

Enable Cross App Access for the Resource App

Assign the Resource App to the AI agent

Configure the Resource App connection in Auth0

Add offline_access scope and update mappings

Enable the connection for the Resource App

Test the connection

Configure Cross App Access with Token Vault

Publish your Requesting App in OIN