End-to-end Testing

Learn how to test the end-to-end XAA flow.

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.

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": "[e-mail]",
  "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": "[e-mail]",
    "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}}
&scope=scope1%20scope2
&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.
resource	The resource identifier of the resource server (API) in your Auth0 tenant.
scope	The set of permissions the Requesting App is requesting for the access token.
assertion	The ID-JAG or JSON Web Token (JWT) that acts as the bearer of the identity assertion.
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.

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.