Configure Access Token Exchange with Token Vault

Single-Page Applications (SPAs) can call backend services in a microservice architecture, passing along only an Auth0 access token. These backend services then use the access token exchange to exchange an Auth0 access token for an external provider’s access token to call external APIs on the user’s behalf.

To use the access token exchange with Token Vault, you need to:

Configure your SPA with the authorization_code grant type.
Create a backend API that the SPA can request an Auth0 access token for by specifying it as the audience.
Create a Custom API Client that is linked to the backend API with the Token Vault grant type enabled.

Configure your SPA

Configure your SPA with the authorization_code grant type. This enables the SPA to request an Auth0 access token scoped to the backend API from the Auth0 Authorization Server.

To configure your SPA with the authorization_code grant type:

Navigate to Applications > Applications.
Select the application you want to configure.
Under Advanced Settings > Grant Types, select the Authorization Code grant type.
Select Save Changes.

To configure your SPA, make a PATCH call to the Update a Client endpoint to add the authorization_code grant type to the client JSON object:

curl --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "grant_types": [
        "authorization_code"
    ]
}'

Was this helpful?

Create backend API

Create a backend API with a unique identifier and the desired scopes that will perform the access token exchange with the Auth0 Authorization Server:

To create a backend API in the Auth0 Dashboard:

Navigate to Applications > APIs, and click Create API.
To create your API, follow the instructions in Register APIs. Note: Once you set an identifier for your API, you cannot change it.
Click Create.
Once you’ve created your API, you need to add scopes for the API. Navigate to the Permissions tab. Under Add a Permission, add your scopes.

To create a backend API using the Management API, make a POST request to the /resource-servers endpoint:

curl --request POST 'https://{yourDomain}/api/v2/resource-servers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "My API Resource Server",
    "identifier": "https://my-api.example.com",
    "scopes": [
      {
        "value": "read:calendar",
        "description": "Read calendar events"
      },
      {
        "value": "write:calendar", 
        "description": "Write calendar events"
      }
    ]
  }'

Was this helpful?

Create Custom API Client

For the access token exchange, you need to create a Custom API Client linked to the backend API. The SPA will be able to request an access token to the backend API by specifying it as the audience in the authorization request to the Auth0 Authorization Server. The Custom API Client has the same identifier as your backend API and has the Token Vault grant type enabled.

When the backend API performs the access token exchange, it authenticates itself by passing the Custom API Client’s credentials to the Auth0 Authorization Server, proving that it is the same entity that was registered in the Auth0 Dashboard.

To create a Custom API Client in the Auth0 Dashboard:

Navigate to Applications > APIs and select your backend API.
Select Add Application and enter an application name.
Click Add. Once the application has been successfully created, click Configure Application and scroll to Application Properties. The Application Type is a Custom API Client.
Under Advanced Settings > Grant Types, the Token Vault grant type should already be enabled for the Custom API Client.

The following code sample creates a Custom API Client with the same identifier as your backend API and adds the Token Vault grant type:

curl --request POST 'https://{yourDomain}/api/v2/clients' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "Custom API Client",
    "app_type": "resource_server",
    "resource_server_identifier": "https://my-api.example.com",
    "grant_types": ["urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"]
  }'

Was this helpful?

Parameter	Description
`name`	Name of your Custom API Client.
`app_type`	The application type of your Custom API Client. To register the client as a resource server, set to `resource_server`.
`resource_server_identifier`	The unique identifier for your Custom API Client. Set to the audience of your backend API i.e. `https://my-api.example.com`.
`grant_types`	The grant types enabled for your Custom API Client. Set to the Token Vault grant type: `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token`.

Once you’ve successfully created the Custom API Client, the user will be redirected to it instead of the SPA after logging in.

Sécuriser

Configure Access Token Exchange with Token Vault

Configure your SPA

Create backend API

Create Custom API Client