Refresh Token Exchange with Token Vault

Token Vault supports the refresh token exchange, which implements the OAuth 2.0 Token Exchange Protocol. The refresh token exchange enables a client 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: Authenticate user and authorize access

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

1. When the user logs into the application via Google using the social login flow, the Auth0 SDK makes a GET request to the /authorize endpoint with the following additional parameters:

Parameter Description
connection The name of the external provider. In this case, google-oauth2.
connection_scope Requests additional scopes to be authorized for the connection. In this case, it includes the Google Calendar API scopes.

Note: At runtime, the list of connection scopes is merged with the scopes you statically configured for the connection. Whenever the user is redirected to authorize this connection, Auth0 will always request the scopes you selected. To learn more, read Configure Token Vault.
scope Requests Auth0 scopes to be authorized for the application. Include openid and profile. To get an Auth0 refresh token from the Auth0 Authorization Server, include offline_access.

2. The Auth0 Authorization Server redirects the user to the consent prompt for the Google connection. The user authenticates using one of the configured login options and authorizes the Google connection, giving the application permission to access the Google Calendar API. 

3. The Auth0 Authorization Server redirects the user back to the application with the single-use authorization code.

4. The Auth0 SDK makes a POST request to the /oauth/token endpoint with the authorization code, the application's client ID, and the application's credentials, such as the client secret or Private Key JWT. 

5. The Auth0 Authorization Server verifies the request and responds with an Auth0 access token, refresh token, and ID token. The application can use the ID token containing the user’s profile information to link user accounts. To learn more, read User account linking.

6. The Auth0 Authorization Server stores the Google access and refresh tokens in a secure tokenset within the user's Token Vault.

Step 2: Perform refresh token exchange

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 login 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:

// Install the Auth0 Next.js SDK
npm i @auth0/nextjs-auth0

// Get access token for Google social connection
const { token } = await auth0.getAccessTokenForConnection({ connection: 'google-oauth2' });

Was this helpful?

/

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 the refresh token exchange, set to the 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: 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 identities 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"
}

Was this helpful?

/

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. Auth0 then stores it in the corresponding tokenset and returns it to the application. To learn more about how Auth0 manages the refresh tokens of external providers, read Manage external provider's refresh tokens.

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

Step 4: Manage external provider's refresh tokens

Auth0 securely stores the refresh and access tokens of external providers in a tokenset within the Token Vault, with one tokenset per authorized user connection. Auth0 manages the refresh tokens of external providers on the server, so your application only has to handle storing and exchanging Auth0 refresh tokens for an external provider's access tokens. 

When you delete a tokenset, Auth0 removes the external provider’s access and refresh tokens from the Token Vault. This does not revoke the external provider’s tokens, and the refresh token could still be used to obtain new access tokens. You have to manually revoke the tokens for the external provider if they have been shared or copied elsewhere.

To learn more about how Auth0 manages Auth0 refresh tokens for different types of applications, read Refresh tokens.

External provider refresh token expiration policy 

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