Refresh Token Exchange with Token Vault

Learn how an application can access the Token Vault to exchange an Auth0 refresh token for an access token to call external APIs.

Token Vault supports the refresh token exchange, which enables a client application to access the Token Vault to exchange an Auth0 refresh token (subject token) for an external provider’s access token (requested token).

Because refresh tokens are exchanged only on a secure backchannel between the client and the authorization server, they are never exposed to the end-user. As a result, clients can maintain a user’s session without requiring the user to re-authorize the connection.

Use cases

Common use cases for the refresh token exchange include:

• Web application: A web-based productivity app connects to a user’s Google Calendar and performs tasks on the user’s behalf, such as scheduling meetings, without requiring the user to re-authenticate.
• Mobile application: A mobile photo gallery app connects to a user’s Google Photos account and uploads photos as they’re taken, keeping the user logged in by refreshing the access token in the background.

How it works

The following sequence diagram describes end-to-end how to call external APIs using the refresh token exchange in Auth0:

Let’s walk through a real-world example: A user wants to schedule a meeting in their Google Calendar using a web application.

Prerequisites

Before getting started, you must configure the refresh token exchange with Token Vault.

Step 1: Connect and authorize access

To schedule the meeting, the web application needs to connect with Google via Auth0 and then receive the user’s permission to access the Google Calendar API.

The user logs into the application via Google with the Connected Accounts flow, which uses the My Account API. After the My Account API validates and completes the Connected Accounts request, it stores the Google access and refresh tokens with the requested calendar scopes in the Token Vault.

Step 2: Perform refresh token exchange

While Token Vault does not support refresh token rotation, you can use DPoP to bind Auth0-issued tokens to your client for additional security. To successfully perform the refresh token exchange with Token Vault, disable Allow Refresh Token Rotation for your application in the Auth0 Dashboard.

The application can use a valid Auth0 refresh token to request a Google access token from the Token Vault with the scopes granted in the Connected Accounts flow. This process allows the application to get a new access token without requiring the user to re-authorize the connection.

To perform the refresh token exchange, the application calls Auth0 SDKs to make a POST request to the /oauth/token endpoint with the following parameters:

curl --request POST 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "subject_token": "<YOUR_AUTH0_REFRESH_TOKEN>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
  "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "connection": "google-oauth2"
}'

Parameter	Description
grant_type	The grant type. For Token Vault, set to urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_id	Client application ID
client_secret	Client secret. Note: You can use any client authentication method to get an external provider’s access token.
subject_token_type	Type of subject token. For Token Vault, set to refresh token: urn:ietf:params:oauth:token-type:refresh_token
subject_token	The Auth0 refresh token that the Auth0 Authorization Server validates to identify the user.
requested_token_type	The requested token type. For Token Vault, set to the external provider’s access token or http://auth0.com/oauth/token-type/federated-connection-access-token
connection	The connection name, in this case, google-oauth2.
login_hint	(Optional) Only use login_hint if the user has several accounts from the same connection, such as a work Google account and personal Google account. When you pass in a value for the login_hint during the token exchange, you are explicitly identifying which of the user’s multiple linked accounts the request is for.

Step 3: Auth0 Authorization Server validates refresh token

The Auth0 Authorization Server validates and loads the user profile associated with the Auth0 refresh token:

1. Auth0 checks if the user profile’s connected_accounts array contains a user account with the connection name passed in the authorization request.
2. If the authorization request contains login_hint, Auth0 looks for an identity matching both the connection name and the login_hint.
3. If Auth0 can’t find the user, it returns a 401 status code with an error message.

Once the Auth0 Authorization Server validates the user, it locates the Google access token within the Token Vault. If it is still valid, Auth0 returns the Google access token with its scopes and expiry time:

{
  "access_token": "<YOUR_GOOGLE_ACCESS_TOKEN>",
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.addons.execute https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.events.readonly https://www.googleapis.com/auth/calendar.settings.readonly https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
  "expires_in": 1377,
  "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "token_type": "Bearer"
}

If the Google access token has expired, Auth0 uses the Google refresh token stored in the Token Vault to get a new Google access token with the same scopes.

Using the Google access token, the application calls the Google Calendar API on the user’s behalf.

External provider refresh token expiration policy

Auth0 deletes an external provider’s refresh tokens when they expire based on the expiration date set by the external provider. Tokens are also removed if they haven’t been used in a token exchange for over one year.