End-to-end Testing

To test the XAA flow, the Requesting App must obtain an Identity Assertion Authorization Grant (ID-JAG) from the enterprise IdP, then exchange it with Auth0 for an access token. This article walks through both steps: obtaining the ID-JAG (via SAML or OIDC) and sending it to Auth0’s /token endpoint to get an access token for your API. You can test the XAA flow manually or using our online sandbox environment. If you use Okta as your enterprise IdP, once you’ve tested the XAA flow, publish your Resource App to the Okta Integration Network (OIN) to increase app discoverability for your enterprise customers.

Test manually

Obtain the ID-JAG

There are two ways to obtain an ID-JAG, depending on whether the Requesting App authenticates with your enterprise IdP using SAML or OIDC.

SAML Requesting App

First, you need to log in to your Requesting App with your IdP tenant. When you successfully log in, the IdP redirects the browser back to your Requesting App with a SAML response. Your Requesting App then securely exchanges the SAML assertion contained within the SAML response for an OIDC refresh_token and then exchanges the refresh_token for an ID-JAG.

SAML Response => SAML Assertion => refresh_token => ID-JAG

Once you receive the SAML response from the IdP, extract the SAML assertion using a SAML library. The following is an example SAML response:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response Destination="http://localhost:3000/saml/callback" Version="2.0" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        ...
    </saml2:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        ...
    </ds:Signature>
    <saml2p:Status xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </saml2p:Status>
    <!-- Assertion begins here -->
    <saml2:Assertion Version="2.0" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        ...
    </saml2:Assertion>
    <!-- Assertion ends here -->
</saml2p:Response>

You can use the xmllint command line tool to extract the SAML assertion:

saml_xml=$(printf '%s' "${saml_response}" | base64 -d 2>/dev/null)
saml_assertion=$(printf '%s' "${saml_xml}" | xmllint --nsclean --xpath "//*[local-name()='Assertion']" - 2>/dev/null)
subject_token=$(printf '%s' "${saml_assertion}" | base64 | tr -d '\n')

To exchange the SAML assertion for an OIDC refresh token, the Requesting App makes a token exchange request to the /token endpoint of your IdP with the following parameters:

POST /oauth2/v1/token HTTP/1.1
Host: {{YOUR_IDP_DOMAIN}}
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token_type=urn:ietf:params:oauth:token-type:saml2
&requested_token_type=urn:ietf:params:oauth:token-type:refresh_token
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&scope=openid offline_access
&subject_token={{SAML_ASSERTION_BASE64}}
&client_id={{CLIENT_ID_IN_IDP}}
&client_secret={{CLIENT_SECRET_IN_IDP}}
&client_assertion={{PRIVATE_KEY_JWT_CLIENT_ASSERTION}}

Parameter	Description
`grant_type`	The grant type. Set to the token exchange grant type: `urn:ietf:params:oauth:grant-type:token-exchange`.
`subject_token_type`	The type of token provided in the `subject_token` parameter. Set to `urn:ietf:params:oauth:token-type:saml2` to indicate a SAML assertion is being presented.
`requested_token_type`	The type of token the client wants to receive back from the authorization server. Set to `urn:ietf:params:oauth:token-type:refresh_token`.
`scope`	Fixed value. Set to `openid offline_access`.
`subject_token`	The SAML assertion extracted from the SAML response, base64-encoded.
`client_id`	The client ID of the Requesting App within the enterprise IdP that is making the token exchange request.
`client_secret`	(Optional) The client secret the Requesting App uses to authenticate itself with the enterprise IdP.
`client_assertion`	(Optional) The client assertion, optionally used to authenticate the Requesting App via Private Key JWT.
`client_assertion_type`	(Optional) The type of the client assertion. For Private Key JWT, set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.

If the IdP client is confidential, either client_secret or client_assertion is sent in the form post or HTTP headers; as a result, they are mutually exclusive and marked as optional. When the call is successful, refresh_token is returned inside the access_token property of the JSON response:

{
  "token_type": "N_A",
  "expires_in": 2592000,
  "access_token": "4SsoXJDBgcq0xxxxxxYn2K-p5l_GCdo",
  "scope": "openid offline_access",
  "issued_token_type": "urn:ietf:params:oauth:token-type:refresh_token"
}

To exchange the refresh_token for an ID-JAG, make another token exchange request to the /token endpoint of your IdP with the following parameters:

POST /oauth2/v1/token HTTP/1.1
Host: {{YOUR_IDP_DOMAIN}}
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&requested_token_type=urn:ietf:params:oauth:token-type:id-jag
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&subject_token_type=urn:ietf:params:oauth:token-type:refresh_token
&audience={{YOUR_AUTH0_TENANT_ISSUER_URL}}
&scope={{YOUR_AUTH0_API_SCOPE}}
&subject_token={{REFRESH_TOKEN}}
&client_id={{CLIENT_ID_IN_IDP}}
&client_secret={{CLIENT_SECRET_IN_IDP}}
&client_assertion={{PRIVATE_KEY_JWT_CLIENT_ASSERTION}}

Parameter	Description
`grant_type`	The grant type. Set to the token exchange grant type: `urn:ietf:params:oauth:grant-type:token-exchange`.
`requested_token_type`	The type of token the client wants to receive back from the authorization server. Set to the Identity Assertion Authorization Grant, or ID-JAG: `urn:ietf:params:oauth:token-type:id-jag`.
`subject_token_type`	The type of token provided in the `subject_token` parameter. Set to `urn:ietf:params:oauth:token-type:refresh_token`.
`audience`	The intended recipient of the final token. Set to your Auth0 tenant issuer URL, or your Resource App whose authorization server is located at that specific URL.
`scope`	Optional. The Resource App’s API scope(s) that the client wants to access. When the authorization server issues the final access token, it includes these scope(s).
`subject_token`	The `refresh_token` obtained by exchanging the SAML assertion.
`client_id`	The client ID of the Requesting App within the enterprise IdP that is making the token exchange request.
`client_secret`	(Optional) The client secret the Requesting App uses to authenticate itself with the enterprise IdP.
`client_assertion`	(Optional) The client assertion, optionally used to authenticate the Requesting App via Private Key JWT.
`client_assertion_type`	(Optional) The type of the client assertion. For Private Key JWT, set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.

If the IdP client is confidential, either client_secret or client_assertion is sent in the form post or HTTP headers; as a result, they are mutually exclusive and marked as optional. The response of this call contains the ID-JAG inside the access_token property:

{
  "token_type": "N_A",
  "expires_in": 300,
  "access_token": "eyJraWQiOiJFeEwySxxxx",
  "issued_token_type": "urn:ietf:params:oauth:token-type:id-jag"
}

The ID-JAG follows a JWT format, such as the following:

{
  "jti": "IDAAG.jrdCpdgazbi52j3UxXT_MqgAUMW2n57EZq8RG0ucRnU",
  "iss": "https://integrator-4598441.okta.com",
  "aud": "https://amin.jp.auth0.com/",
  "iat": 1784620622,
  "exp": 1784620922,
  "sub": "00u14j584jskYLAVs698",
  "email": "test-xaa@example.com",
  "client_id": "Josz8cBBCWKA6Q7CkhyhYjbKY4hqjXMG",
  "sub_profile": "user",
  "scope": "read",
  "act": {
    "sub": "wlp15fk3702lJwVLG698",
    "sub_profile": "ai_agent"
  },
  "sub_id": {
    "format": "saml-nameid",
    "issuer": "http://www.okta.com/exk15fjrhugHeRpO1698",
    "nameid": "test-xaa@example.com",
    "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  }
}

When the Resource App is a SAML application, the ID-JAG also includes a sub_id claim containing the SAML NameID details (format, issuer, nameid, and nameid_format) of the authenticated user, alongside the standard sub claim.

OIDC Requesting App

First, you need to log in to your Requesting App with your IdP tenant. When you successfully log in, the IdP redirects the browser back to your Requesting App with an authorization code. Your Requesting App then securely exchanges the authorization code for an access token and ID token.

ID Token => ID-JAG

To exchange the ID token for an ID-JAG, the Requesting App makes a token exchange request to the /token endpoint of your IdP with the following parameters:

POST /oauth2/v1/token HTTP/1.1
Host: {{YOUR_IDP_DOMAIN}}
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&requested_token_type=urn:ietf:params:oauth:token-type:id-jag
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&subject_token_type=urn:ietf:params:oauth:token-type:id_token
&audience={{YOUR_AUTH0_TENANT_ISSUER_URL}}
&scope={{YOUR_AUTH0_API_SCOPE}}
&subject_token={{IDP_ID_TOKEN}}
&client_id={{CLIENT_ID_IN_IDP}}
&client_secret={{CLIENT_SECRET_IN_IDP}}
&client_assertion={{PRIVATE_KEY_JWT_CLIENT_ASSERTION}}

Parameter	Description
`grant_type`	The grant type. Set to the token exchange grant type: `urn:ietf:params:oauth:grant-type:token-exchange`.
`requested_token_type`	The type of token the client wants to receive back from the authorization server. Set to the Identity Assertion Authorization Grant, or ID-JAG: `urn:ietf:params:oauth:token-type:id-jag`.
`client_assertion_type`	(Optional) The type of the client assertion. For Private Key JWT, set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
`subject_token_type`	The type of token provided in the `subject_token` parameter. For XAA, it specifies that an ID token is being presented to the authorization server.
`audience`	The intended recipient of the final token. Set to your Auth0 tenant issuer URL, or your Resource App whose authorization server is located at that specific URL.
`scope`	Optional. The Resource App’s API scope(s) that the client wants to access. When the authorization server issues the final access token, it includes these scope(s).
`subject_token`	The token the client is exchanging. For XAA, the subject token is the “proof” or “assertion” of the user’s identity. Set to the IdP ID token that the IdP will use to verify the user’s identity.
`client_id`	The client ID of the Requesting App within the enterprise IdP that is making the token exchange request.
`client_secret`	(Optional) The client secret the Requesting App uses to authenticate itself with the enterprise IdP.
`client_assertion`	(Optional) The client assertion, optionally used to authenticate the Requesting App via Private Key JWT.

If the IdP client is confidential, either client_secret or client_assertion is sent in the form post or HTTP headers; as a result, they are mutually exclusive and marked as optional.

Send ID-JAG to Auth0’s `/token` endpoint

Once the Requesting App gets an ID-JAG, it sends an access token request to the /token endpoint of your Auth0 tenant:

POST https://{{YOUR_AUTH0_TENANT_DOMAIN}}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id={{REQUESTING_APP_CLIENT_ID_IN_AUTH0}}
&client_secret={{REQUESTING_APP_CLIENT_SECRET_IN_AUTH0}}
&resource={{AUTH0_API_IDENTIFIER}}
&assertion={{ID_JAG}}

Parameter	Description
`grant_type`	The grant type. It tells the Authorization Server to expect a JSON Web Token (JWT) as the primary credential in the request.
`client_id`	The client ID of the Requesting App within the Resource App Authorization Server making the API call.
`assertion`	The ID-JAG or JSON Web Token (JWT) that acts as the bearer of the identity assertion.
`resource`	(Optional) The resource identifier of the resource server (API) in your Auth0 tenant. If the ID-JAG assertion includes a `resource` claim, that value takes precedence over this parameter. If no resource is specified in the ID-JAG or in the request body, your tenant’s default audience is used.
`client_secret`	(Optional) The client secret of the Requesting App within the Resource App Authorization Server making the API call.
`client_assertion`	(Optional) The client assertion, optionally used to authenticate the Requesting App via Private Key JWT.
`client_assertion_type`	(Optional) The type of the client assertion. For Private Key JWT, set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.

If the Requesting App is a confidential client, either client_secret or client_assertion is sent in the form post or HTTP headers; as a result, they are mutually exclusive and marked as optional. After the Auth0 Authorization Server validates the ID-JAG to verify the user’s identity, it issues an access token for the API in your Auth0 tenant. The access token also includes the scopes you requested that are allowed by RBAC and other policies set in your Auth0 tenant. The Auth0 Authorization Server does not issue refresh tokens in response to ID-JAG token exchanges. As a result, the Requesting App needs to get a new ID-JAG from the enterprise IdP, and undergo the applicable access controls, to get a new access token via XAA.

Test using our online sandbox environment

If you use Okta as your enterprise identity provider, XAA.dev is our online sandbox environment for testing Cross App Access in your browser. Follow the instructions to test your Resource App against a hosted Requesting App that mints an ID-JAG via OIDC or SAML, depending on your IdP connection, and calls your Resource App API.

Publish your Resource App in OIN

If you use Okta as your enterprise identity provider, after you’ve 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 and Express Configuration with Okta. For a list of fields needed to publish your Resource App to the OIN, review your Auth0 logs for idjag-exchange-succeeded.

Learn more

To help you test the XAA flow, use the following resources:

Auth0 Cross App Access Inspector: A simple Node.js application for testing the XAA flow between Okta and Auth0.
XAA.dev: An online sandbox for testing Cross App Access in your browser.

Set up Auth0 as Resource App

Set up Auth0 as Requesting App

Test manually

Obtain the ID-JAG

SAML Requesting App

OIDC Requesting App

Send ID-JAG to Auth0’s `/token` endpoint

Test using our online sandbox environment

Publish your Resource App in OIN

Learn more

​Test manually

​Obtain the ID-JAG

​SAML Requesting App

​OIDC Requesting App

​Send ID-JAG to Auth0’s /token endpoint

​Test using our online sandbox environment

​Publish your Resource App in OIN

​Learn more

Test manually

Obtain the ID-JAG

SAML Requesting App

OIDC Requesting App

Send ID-JAG to Auth0’s `/token` endpoint

Test using our online sandbox environment

Publish your Resource App in OIN

Learn more