|
| 1 | +--- |
| 2 | +description: Learn how an application can access the Token Vault to exchange an Auth0 access token for an access |
| 3 | + token to call external APIs. |
| 4 | +'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png |
| 5 | +'og:title': Access Token Exchange with Token Vault |
| 6 | +'og:url': https://auth0.com/docs/ |
| 7 | +permalink: access-token-exchange-with-token-vault |
| 8 | +title: Access Token Exchange with Token Vault |
| 9 | +'twitter:description': Learn how an application can access the Token Vault to exchange an Auth0 access token for an access |
| 10 | + token to call external APIs. |
| 11 | +'twitter:title': Access Token Exchange with Token Vault |
| 12 | +--- |
| 13 | + |
| 14 | +Token Vault supports the access token exchange, which enables a client to exchange an Auth0 access token (subject token) for an external provider’s access token (requested token). |
| 15 | + |
| 16 | +When a Single-Page Application (SPA) calls a backend API, it only passes an Auth0 access token in the `Authorization` header. Because the backend API does not receive any refresh tokens issued to the SPA, it cannot use the [refresh token exchange](/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault) to access the Token Vault to call external APIs. |
| 17 | + |
| 18 | +Instead, the backend API can exchange the Auth0 access token received from the SPA (subject token) for an external provider’s access token (requested token), otherwise known as the access token exchange. This process keeps the sensitive external credentials secure on the backend. |
| 19 | + |
| 20 | +In Auth0’s access token exchange, the backend API acts as both a client and a resource server: |
| 21 | +* Client: Uses its own credentials to securely perform the access token exchange with the Auth0 Authorization Server. In Auth0, you create a Custom API Client with the same identifier as the backend API. The backend API passes the Custom API Client’s credentials to securely perform the access token exchange with the Auth0 Authorization Server. |
| 22 | +* Resource server: Serves the backend API to the SPA and validates the Auth0 access token. |
| 23 | + |
| 24 | +By acting as the intermediary between the SPA and Auth0 Authorization Server, the backend API prevents unauthorized clients from stealing the Auth0 token and using it to access the external provider on the user's behalf. |
| 25 | + |
| 26 | +## Use cases |
| 27 | + |
| 28 | +Common use cases for the access token exchange include: |
| 29 | +* A backend API: A user interacts with an SPA, which then calls a backend API to exchange an Auth0 access token for an external provider’s access token with the Auth0 Authorization Server. |
| 30 | +* Microservice architecture: Backend services, such as MCP servers or other OAuth 2.0 resource servers, that need to exchange access tokens to access external APIs. |
| 31 | + |
| 32 | +## How it works |
| 33 | + |
| 34 | +The following sequence diagram describes end-to-end how to call external APIs using the access token exchange in Auth0: |
| 35 | + |
| 36 | +Let’s walk through a real-world example: A user wants to schedule a meeting in their Google Calendar using an SPA. |
| 37 | + |
| 38 | +<Frame></Frame> |
| 39 | + |
| 40 | +## Prerequisites |
| 41 | + |
| 42 | +Before getting started, you must [configure the access token exchange with Token Vault](/docs/secure/tokens/token-vault/configure-token-vault#configure-access-token-exchange). |
| 43 | + |
| 44 | +## Step 1: Connect and authorize access |
| 45 | + |
| 46 | +To schedule the meeting, the SPA needs to connect with Google via Auth0 and then receive the user’s permission to access the Google Calendar API. |
| 47 | +The user logs into the application via Google with the [Connected Accounts flow](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#how-it-works), which uses the [My Account API](/docs/manage-users/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. |
| 48 | + |
| 49 | +## Step 2: SPA calls backend API with Auth0 access token |
| 50 | + |
| 51 | +When the SPA calls the backend API, it passes the Auth0 access token in the `Authorization` header to the backend API. The backend API validates the Auth0 access token by checking the following: |
| 52 | + |
| 53 | +* Signature: Verify the token's signature using Auth0's public key. This confirms that Auth0 issued the access token. |
| 54 | +* Issuer: Checks the `iss` claim in the token's payload to confirm that the token was issued by your Auth0 tenant. |
| 55 | +* Audience: Checks the `aud` claim to ensure it matches the unique identifier of the backend API itself. This confirms that the token was specifically issued for this resource server. |
| 56 | +* Expiration: Validates the `exp` claim to ensure the token is still valid and has not expired. |
| 57 | +* Scopes: Checks the `scope` claim to determine what permissions the user has been granted. |
| 58 | + |
| 59 | +After successfully completing these checks, the backend API can trust the Auth0 access token and proceed with the token exchange. |
| 60 | + |
| 61 | +## Step 3: Backend API performs access token exchange |
| 62 | + |
| 63 | +For the access token exchange, you need to create a Custom API Client linked to the backend API. The Custom API Client has the same identifier as your backend API and has the Token Vault grant type enabled. |
| 64 | + |
| 65 | +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. |
| 66 | + |
| 67 | +To perform the access token exchange, the backend API calls Auth0 SDKs to make a POST request to the `/oauth/token` endpoint. |
| 68 | + |
| 69 | +In the token request, the backend API: |
| 70 | +* Passes the backend API’s (the Custom API Client’s) client credentials to the Auth0 Authorization Server to authenticate itself. |
| 71 | +* Exchange an Auth0 access token for a Google access token. |
| 72 | + |
| 73 | +```bash lines |
| 74 | +curl --request POST 'https://{yourDomain}/oauth/token' \ |
| 75 | + --header 'Content-Type: application/json' \ |
| 76 | + --data '{ |
| 77 | + "client_id": "YOUR_CUSTOM_API_CLIENT_ID", |
| 78 | + "client_secret": "YOUR_CUSTOM_API_CLIENT_SECRET", |
| 79 | + "subject_token": "YOUR_AUTH0_ACCESS_TOKEN", |
| 80 | + "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token", |
| 81 | + "subject_token_type": "urn:ietf:params:oauth:token-type:access_token", |
| 82 | + "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token", |
| 83 | + "connection": "google-oauth2" |
| 84 | + }' |
| 85 | +``` |
| 86 | + |
| 87 | +<table class="table"><thead> |
| 88 | +<tr> |
| 89 | +<th><strong>Parameter</strong></th> |
| 90 | +<th><strong>Description</strong></th> |
| 91 | +</tr> |
| 92 | +</thead> |
| 93 | +<tbody> |
| 94 | +<tr> |
| 95 | +<td><code>grant_type</code></td> |
| 96 | +<td>The grant type. For Token Vault, set to <code>urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token</code></td> |
| 97 | +</tr> |
| 98 | +<tr> |
| 99 | +<td><code>client_id</code></td> |
| 100 | +<td>Client application ID</td> |
| 101 | +</tr> |
| 102 | +<tr> |
| 103 | +<td><code>client_secret</code></td> |
| 104 | +<td>Client secret. <strong>Note:</strong> You can use any client authentication method to get an external provider's access token.</td> |
| 105 | +</tr> |
| 106 | +<tr> |
| 107 | +<td><code>subject_token_type</code></td> |
| 108 | +<td>Type of subject token. For the access token exchange, set to the access token: <code>urn:ietf:params:oauth:token-type:access_token</code>.</td> |
| 109 | +</tr> |
| 110 | +<tr> |
| 111 | +<td><code>subject_token</code></td> |
| 112 | +<td>The Auth0 access token that the Auth0 Authorization Server validates to identify the user.</td> |
| 113 | +</tr> |
| 114 | +<tr> |
| 115 | +<td><code>requested_token_type</code></td> |
| 116 | +<td>The requested token type. For Token Vault, set to the external provider's access token or <code>http://auth0.com/oauth/token-type/federated-connection-access-token</code></td> |
| 117 | +</tr> |
| 118 | +<tr> |
| 119 | +<td><code>connection</code></td> |
| 120 | +<td>The connection name, in this case, <code>google-oauth2</code>.</td> |
| 121 | +</tr> |
| 122 | +<tr> |
| 123 | +<td><code>login_hint</code></td> |
| 124 | +<td>(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.</td> |
| 125 | +</tr> |
| 126 | +</tbody> |
| 127 | +</table> |
| 128 | + |
| 129 | +## Step 4: Auth0 Authorization Server validates access token |
| 130 | + |
| 131 | +The Auth0 Authorization Server validates and loads the user profile associated with the Auth0 access token: |
| 132 | +* Auth0 verifies that the client making the access token exchange request is linked to the backend API identified by the `audience` of the access token. |
| 133 | +* Auth0 checks if the user profile’s `connected_accounts` array contains a user account with the connection name passed in the authorization request. |
| 134 | +* If the authorization request contains `login_hint`, Auth0 looks for an identity matching both the connection name and the `login_hint`. |
| 135 | +* If Auth0 can’t find the user, it returns a `401` status code with an error message. |
| 136 | + |
| 137 | +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: |
| 138 | + |
| 139 | +```json lines |
| 140 | +{ |
| 141 | + "access_token": "YOUR_GOOGLE_ACCESS_TOKEN", |
| 142 | + "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", |
| 143 | + "expires_in": 1377, |
| 144 | + "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token", |
| 145 | + "token_type": "Bearer" |
| 146 | +} |
| 147 | +``` |
| 148 | + |
| 149 | +Using the Google access token, the backend API calls the Google Calendar API on the user’s behalf to schedule the meeting. |
0 commit comments