Access Token Vault Flow

Token Vault organizes federated access and refresh tokens issued by external providers into tokensets, with one tokenset per authorized connection. Applications can access the Token Vault when they exchange a valid Auth0 refresh token for a federated access token stored in the tokenset. This enables applications to request federated access tokens without the user having to re-authorize the connection. Using the federated access token, the application can call third-party APIs on the user’s behalf. 

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

To schedule the meeting, the productivity app needs the user’s permission to access the Google Calendar API.

When the user logs into a new Google social connection:

1. Similar to a regular social login flow, the Auth0 SDK makes a GET request to the /authorize endpoint with the following additional parameters:

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, application's client ID, and application's credentials, such as 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.

To schedule the meeting, the application needs to call the Google Calendar API. The application can use a valid Auth0 refresh token to request a Google access token with the scopes granted in the login flow without the user having to re-authorize the connection. To learn more, read Manage federated refresh tokens.

To call the Google Calendar API:

1. The application calls Auth0 SDKs to make a request to the /oauth/token endpoint with the following parameters:

POST https://YOUR_AUTH0_TENANT.auth0.com/oauth/token
Request:
{
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "client_id": "AUTH0_CLIENT_ID",
  "client_secret": "AUTH0_CLIENT_SECRET",
  "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
  "subject_token": "AUTH0_REFRESH_TOKEN",
  "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token"
  "connection": "google-oauth2",
  "login_hint": "idp_user_id"
}

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 federated access token within the Token Vault. If it is still valid, Auth0 returns the federated access token with its scopes and expiry time:

{
   "access_token": "GOOGLE_ACCESS_TOKEN",
   "scope": "https://www.googleapis.com/auth/calendar       https://www.googleapis.com/auth/calendar.events"
   "expires_in": 3600,
   "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
   "token_type": "Bearer"
}

If the federated access token has expired, Auth0 uses the federated refresh token stored in the Token Vault to get a new federated 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 federated refresh tokens, read Manage federated refresh tokens.

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

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

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

Auth0 deletes federated refresh tokens from tokensets when they expire based on the expiration date set by the external provider or if they have not been exchanged for a federated access token for 1+ years.