Okta Cross App Access (XAA)

1. The agent exchanges the user’s Okta token for a short-lived ID-JAG (Identity Assertion JWT Authorization Grant) issued by your Okta org.
2. The agent sends the ID-JAG to Opal’s token endpoint and receives an Opal access token for the MCP servers.

​

Prerequisites

• Okta Cross App Access enabled for your organization in Opal. Contact Opal support.
• An Okta tenant with Cross App Access and AI agents available, and an Okta admin.
• An Opal admin.
• Each user the agent acts for exists in Opal, with the same primary email address as their Okta profile. Opal doesn’t create users through Cross App Access.

​

Step 1: Connect your Okta tenant in Opal

1. In Opal, go to Settings → Authentication → Okta Cross App Access and click Configure.
2. Set Okta Issuer URL to your Okta org’s issuer, for example https://your-org.okta.com. Use the org itself, not a custom authorization server such as https://your-org.okta.com/oauth2/default.
3. Make sure Connection enabled is on.
4. Copy the Okta Audience/tenant ID value. This is your Opal organization ID, and you’ll paste it into Okta in step 3.
5. Click Submit.

​

Step 2: Register the agent in Opal

1. Under Settings → Authentication → Okta Cross App Access requesting apps, click Add requesting client.
2. Enter a Label that identifies the agent, such as its Okta name.
3. Copy the Client ID and Client secret. The secret is shown only once.

​

Step 3: Add Opal as a resource app in Okta

1. In the Okta Admin Console, go to Applications → Applications → Create App Integration, choose OIDC - OpenID Connect and Web Application, and create the app with the Authorization Code grant. The sign-in redirect URI isn’t used by Cross App Access, so a placeholder is fine.
2. Assign the users the agent will act for to this app.
3. Open the app’s Resource Server tab, edit Cross-app access (XAA), and enable it with these values:

​

Step 4: Connect the AI agent to Opal in Okta

1. In the Okta Admin Console, go to Directory → AI Agents and open your agent. Under User access, link it to the app your users sign in to the agent with.
2. Under Resource connections, click Add resource connection, choose Application, and select the Opal resource app from step 3.
3. Set the client ID to the Client ID from step 2.
4. Choose the scopes the agent may use. See Scopes.
5. Make sure the agent’s status is Active.

​

Step 5: Redeem the ID-JAG for an Opal access token

curl -X POST https://app.opal.dev/token \
  -u "$OPAL_XAA_CLIENT_ID:$OPAL_XAA_CLIENT_SECRET" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion=$ID_JAG"

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp:readonly"
}

​

Scopes

​

Troubleshooting

​

Beta limitations

• Okta is the only supported identity provider. The issuer must be an Okta org on okta.com, oktapreview.com, or okta-emea.com; Okta custom domains and Okta for Government aren’t supported.
• Users are matched by primary email address. Opal system users and service users can’t be used.
• Each Opal organization connects one Okta issuer.