diff --git a/main/docs.json b/main/docs.json index 086075837..85fcf6b8b 100644 --- a/main/docs.json +++ b/main/docs.json @@ -2036,7 +2036,9 @@ "group": "Token Vault", "pages": [ "docs/secure/tokens/token-vault", - "docs/secure/tokens/token-vault/call-apis-with-token-vault", + "docs/secure/tokens/token-vault/connected-accounts-for-token-vault", + "docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault", + "docs/secure/tokens/token-vault/access-token-exchange-with-token-vault", "docs/secure/tokens/token-vault/configure-token-vault" ] } @@ -24195,6 +24197,18 @@ { "source": "/docs/secure/security-guidance/measures-against-application-impersonation", "destination": "/docs/secure/security-guidance/measures-against-app-impersonation" + }, + { + "source": "/docs/secure/tokens/token-vault/configure-access-token-exchange-with-token-vault", + "destination": "/docs/secure/tokens/token-vault/configure-token-vault" + }, + { + "source": "/docs/secure/tokens/token-vault/configure-refresh-token-exchange-with-token-vault", + "destination": "/docs/secure/tokens/token-vault/configure-token-vault" + }, + { + "source": "/docs/secure/tokens/token-vault/call-apis-with-token-vault", + "destination": "/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault" } ] } diff --git a/main/docs/authenticate/identity-providers/enterprise-identity-providers.mdx b/main/docs/authenticate/identity-providers/enterprise-identity-providers.mdx index 11a5096d5..c2f8218be 100644 --- a/main/docs/authenticate/identity-providers/enterprise-identity-providers.mdx +++ b/main/docs/authenticate/identity-providers/enterprise-identity-providers.mdx @@ -8,6 +8,9 @@ title: Enterprise Identity Providers 'twitter:description': Learn about enterprise identity providers supported by Auth0. 'twitter:title': Enterprise Identity Providers --- + +Auth0 supports enterprise login for both web-based and native applications. Enterprise login is a method of authentication that allows users to log in to an application using existing credentials from an enterprise identity provider, such as Google Workspace or Microsoft Azure Active Directory (Entra ID). This is separate from connecting and authorizing applications for an external provider so they can access external APIs on the user’s behalf. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts). + Auth0 supports the following enterprise providers out of the box: * [Active Directory/LDAP](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap) diff --git a/main/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2.mdx b/main/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2.mdx index c56a81b04..15b52b717 100644 --- a/main/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2.mdx +++ b/main/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2.mdx @@ -189,13 +189,16 @@ Create and configure an Azure AD Enterprise Connection in Auth0. Make sure you h Email Verification Choose how Auth0 sets the email_verified field in the user profile. To learn more, read Email Verification for Azure AD and ADFS. + +Purpose +Enable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts). + - ![Create new Azure AD connection](/docs/images/cdy7uua7fh8z/1r6WTgLJUlbiV9jligIwER/55904e9d3c1eec62c2e8421b71cff94b/Enterprise_Connection_-_MSFT_-_English.png) 3. In the **Provisioning** view, you can configure how user profiles get created and updated in Auth0. - +
diff --git a/main/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps.mdx b/main/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps.mdx index b02d67a1a..acbc4c1ae 100644 --- a/main/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps.mdx +++ b/main/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps.mdx @@ -164,14 +164,17 @@ Next, you will need to create and configure a Google Workspace Enterprise Connec + + + +
Field DescriptionSync user profile attributes at each login When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.
PurposeEnable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts).
- ![Create Google Workspace Connection](/docs/images/cdy7uua7fh8z/5s3W98sar77mRxZ3F3s0Ol/2743ece52e85d378412b770344f7d3d5/Enterprise_Connection_-_Google_Work_-_English.png) 3. If you have appropriate administrative permissions to configure your Google Workspace settings so you can use Google's Admin APIs, then click **Continue**. Otherwise, provide the given URL to your administrator so that they can adjust the required settings. 4. On the **Login Experience** tab, you can configure how users log in with this connection. - +
diff --git a/main/docs/authenticate/identity-providers/enterprise-identity-providers/oidc.mdx b/main/docs/authenticate/identity-providers/enterprise-identity-providers/oidc.mdx index 3540f8312..d2860b6d4 100644 --- a/main/docs/authenticate/identity-providers/enterprise-identity-providers/oidc.mdx +++ b/main/docs/authenticate/identity-providers/enterprise-identity-providers/oidc.mdx @@ -171,6 +171,10 @@ To be configurable through the Auth0 Dashboard, the OpenID Connect (OIDC) Identi + + + +
Field DescriptionSync user profiles using SCIM When enabled, Auth0 allows user profile data to be synced using SCIM. For more information, see Configure Inbound SCIM.
PurposeEnable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts).
5. In the **Login Experience** view, configure how users log in with this connection. diff --git a/main/docs/authenticate/identity-providers/social-identity-providers.mdx b/main/docs/authenticate/identity-providers/social-identity-providers.mdx index 67697bb80..6e33aaed6 100644 --- a/main/docs/authenticate/identity-providers/social-identity-providers.mdx +++ b/main/docs/authenticate/identity-providers/social-identity-providers.mdx @@ -9,7 +9,7 @@ title: Social Identity Providers 'twitter:description': Learn about the social identity providers supported by Auth0. 'twitter:title': Social Identity Providers --- -Auth0 supports social login for both web-based and native applications. Social login is a method of authentication that allows users to log in to an application using existing credentials from a social identity provider, such as Google or Facebook. +Auth0 supports social login for both web-based and native applications. Social login is a method of authentication that allows users to log in to an application using existing credentials from a social identity provider, such as Google or Facebook. This is separate from connecting and authorizing applications for an external provider, allowing them to access external APIs on the user’s behalf. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts). As users frequently have their social credentials stored in their browser or device, social login provides a frictionless user experience that requires minimal manual interaction with an application. diff --git a/main/docs/authenticate/identity-providers/social-identity-providers/google-native.mdx b/main/docs/authenticate/identity-providers/social-identity-providers/google-native.mdx index f9df6f99b..b183094c4 100644 --- a/main/docs/authenticate/identity-providers/social-identity-providers/google-native.mdx +++ b/main/docs/authenticate/identity-providers/social-identity-providers/google-native.mdx @@ -34,6 +34,7 @@ This feature uses Android's Credential Manager to facilitate Sign in with Google Before you begin configuring Sign in with Google, ensure the following are true: * A [Google social connection](https://marketplace.auth0.com/integrations/google-social-connection) has been set up within your Auth0 tenant. + * For the **Purpose** setting, enable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts). * Sign in with Google has been added to your Android application using [Android's Credential Manager](https://developer.android.com/identity/sign-in/credential-manager-siwg). ## Configuring Sign in with Google for Android applications diff --git a/main/docs/authenticate/identity-providers/social-identity-providers/oauth2.mdx b/main/docs/authenticate/identity-providers/social-identity-providers/oauth2.mdx index ac5be0b0c..850bc3a3f 100644 --- a/main/docs/authenticate/identity-providers/social-identity-providers/oauth2.mdx +++ b/main/docs/authenticate/identity-providers/social-identity-providers/oauth2.mdx @@ -34,6 +34,7 @@ The form that appears contains several fields that you must use to configure the * **Client ID**: Client ID for Auth0 as an application used to request authorization and exchange the authorization code. To get a Client ID, you will need to register with the identity provider. * **Client Secret**: Client Secret for Auth0 as an application used to exchange the authorization code. To get a Client Secret, you will need to register with the identity provider. * **Fetch User Profile Script**: Node.js script used to call a userinfo URL with the provided access token. To learn more about this script, see [Fetch User Profile Script](#fetch-user-profile-script). +* **Purpose**: Enables the social connection for Authentication, Cconnected Aaccounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts). diff --git a/main/docs/authenticate/identity-providers/social-identity-providers/tiktok.mdx b/main/docs/authenticate/identity-providers/social-identity-providers/tiktok.mdx index ee53ba8eb..7f8127d48 100644 --- a/main/docs/authenticate/identity-providers/social-identity-providers/tiktok.mdx +++ b/main/docs/authenticate/identity-providers/social-identity-providers/tiktok.mdx @@ -53,6 +53,7 @@ You must create a custom connection to associate your TikTok instance with Auth0 4. Scope: `user.info.basic` 5. Client ID: Client key assigned to you by TikTok 6. Client Secret: Client secret assigned to you by TikTok + 7. Purpose: Enable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts). 5. Configure the [Fetch User Profile Script](/docs/authenticate/identity-providers/social-identity-providers/oauth2#fetch-user-profile-script) to fetch profile information from [TikTok's user_info endpoint](https://developers.tiktok.com/doc/tiktok-api-v2-get-user-info/). Map attributes to Auth0’s normalized user profile. diff --git a/main/docs/images/token-vault/access_token_exchange_flow_diagram.png b/main/docs/images/token-vault/access_token_exchange_flow_diagram.png new file mode 100644 index 000000000..fe4ac576c Binary files /dev/null and b/main/docs/images/token-vault/access_token_exchange_flow_diagram.png differ diff --git a/main/docs/images/token-vault/configure_token_vault_grant_type.png b/main/docs/images/token-vault/configure_token_vault_grant_type.png new file mode 100644 index 000000000..ec2ecdd0d Binary files /dev/null and b/main/docs/images/token-vault/configure_token_vault_grant_type.png differ diff --git a/main/docs/images/token-vault/connected_accounts_flow_diagram.png b/main/docs/images/token-vault/connected_accounts_flow_diagram.png new file mode 100644 index 000000000..96dff0052 Binary files /dev/null and b/main/docs/images/token-vault/connected_accounts_flow_diagram.png differ diff --git a/main/docs/images/token-vault/create_custom_api_client.png b/main/docs/images/token-vault/create_custom_api_client.png new file mode 100644 index 000000000..a5d603240 Binary files /dev/null and b/main/docs/images/token-vault/create_custom_api_client.png differ diff --git a/main/docs/images/token-vault/refresh_token_exchange_flow_diagram.png b/main/docs/images/token-vault/refresh_token_exchange_flow_diagram.png new file mode 100644 index 000000000..88c877266 Binary files /dev/null and b/main/docs/images/token-vault/refresh_token_exchange_flow_diagram.png differ diff --git a/main/docs/manage-users/my-account-api.mdx b/main/docs/manage-users/my-account-api.mdx index f5fbb62e8..b1ab1d0a3 100644 --- a/main/docs/manage-users/my-account-api.mdx +++ b/main/docs/manage-users/my-account-api.mdx @@ -87,6 +87,46 @@ The My Account API supports the following scopes: create:me:authentication-methods Allows the user to enroll a new authentication method. + +read:me:authentication-methods +Allows the user to view existing authentication methods. + + +update:me:authentication-methods +Allows the user to modify existing authentication methods. + + +delete:me:authentication-methods +Allows the user to modify existing authentication methods. + + +read:me:factors +Allows the user to view the factors they can enroll. + + + + +For [Connected Accounts with Token Vault](/docs/secure/tokens/connected-accounts-for-token-vault), the My Account API supports the following scopes: + + + + + + + + + + + + + + + + + + + +
ScopeDescription
create:me:connected_accountsAllows the user to connect a new account to their user profile.
read:me:connected_accountsAllows the user to view the existing connected accounts linked to their user profile.
delete:me:connected_accountsAllows the user to delete a connected account from their user profile.
diff --git a/main/docs/manage-users/user-accounts/user-account-linking.mdx b/main/docs/manage-users/user-accounts/user-account-linking.mdx index 489894240..8e310d4ff 100644 --- a/main/docs/manage-users/user-accounts/user-account-linking.mdx +++ b/main/docs/manage-users/user-accounts/user-account-linking.mdx @@ -14,6 +14,10 @@ title: User Account Linking import {AuthCodeGroup} from "/snippets/AuthCodeGroup.jsx"; + +Connected Accounts enables a single Auth0 user profile to be linked to multiple external accounts. When you enable Connected Accounts for a supported external provider, Auth0 automatically adds the account for that provider to the user profile after the user successfully logs in. To learn more, read [Connected Accounts for Token Vault](/docs/secure/tokens/connected-accounts-for-token-vault). + + Auth0 supports the linking of user accounts from various identity providers. This allows a user to authenticate from any of their accounts and still be recognized by your app and associated with the same user profile. @@ -199,4 +203,4 @@ Previously, in some cases, you could use ID Tokens to link and unlink user accou * [Link User Accounts](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts) * [Unlink User Accounts](/docs/manage-users/user-accounts/user-account-linking/unlink-user-accounts) * [User-Initiated Account Linking: Client-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation) -* [User Account Linking: Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation) \ No newline at end of file +* [User Account Linking: Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation) diff --git a/main/docs/secure/tokens/token-vault.mdx b/main/docs/secure/tokens/token-vault.mdx index 1d1ecc23c..73bc95750 100644 --- a/main/docs/secure/tokens/token-vault.mdx +++ b/main/docs/secure/tokens/token-vault.mdx @@ -1,55 +1,86 @@ --- -description: Learn how Token Vault securely stores federated access and refresh - tokens. +description: Learn how Token Vault securely stores the access and refresh + tokens of supported external providers. 'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png 'og:title': Token Vault 'og:url': https://auth0.com/docs/ permalink: token-vault sidebarTitle: Overview title: Token Vault -'twitter:description': Learn how Token Vault securely stores federated access and - refresh tokens. +'twitter:description': Learn how Token Vault securely stores the access and + refresh tokens of external providers. 'twitter:title': Token Vault --- - -Token Vault is currently available in Early Access for public cloud tenants. To enable Token Vault, contact your Auth0 representative. +Token Vault simplifies how your applications access external APIs on a user's behalf. When you integrate with Token Vault, you gain a secure way to manage application access to a wide range of external services and their APIs, such as Google, GitHub, and Microsoft. - +When a user connects with a [supported external provider](#supported-external-providers) and authorizes access using OAuth scopes, Auth0 automatically adds that connected account to the user profile. A connected account enables applications to access external APIs using a unified Auth0 user profile. To learn more, read [Connected Accounts for Token Vault](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault). -Token Vault enables your applications to securely access third-party APIs on the user's behalf. There is no need to manage refresh tokens or build custom integrations per provider—Auth0 handles it all for you. You gain access to a wide range of external providers’ APIs and services, all through a single Auth0 integration. +Auth0 stores the access and refresh tokens for each connected account in the Token Vault. To retrieve these stored credentials from Token Vault, your application performs a [secure token exchange](#supported-token-exchanges). This token exchange enables your application to get the necessary tokens to call an external API, removing the need for you to build and maintain custom integrations with each provider. -When a user authenticates with a supported external provider and uses OAuth scopes to authorize access, Auth0 stores the access and refresh tokens for that connection in the Token Vault. Token Vault organizes the federated tokens issued by external providers into tokensets, with one tokenset per authorized connection. +## Supported external providers -You can then call the external provider's APIs using these stored credentials via Auth0 to get a user’s Google Calendar events, access GitHub repos, create a Microsoft Word document, and more. +Token Vault supports the following external providers: -For Early Access, Auth0 supports Token Vault for the following social and enterprise identity providers: +### Social * Google * Microsoft * Box * Slack * GitHub -* OpenID Connect * Custom social connection +### Enterprise + +* Google Workspace +* Microsoft Azure AD (Entra ID) +* OpenID Connect + +To see the full list of supported external providers, read [Auth0 Integrations](https://auth0.com/ai/docs/integrations/overview). + +## Common use cases + +Common Token Vault use cases include: + +* An AI agent running as a web application calls external APIs to perform tasks on the user’s behalf, such as scheduling a meeting in Google Calendar. +* An internal or backend service can access Token Vault to exchange an Auth0 access token for an external provider’s access token to call external APIs. + ## How it works -When a user authenticates with a supported external provider and authorizes the federated connection: +When a user connects with a supported external provider and authorizes the connection: -1. Auth0 obtains access tokens using OAuth 2.0 scopes to control access. Users explicitly approve requested permissions. -2. Auth0 securely stores federated access and refresh tokens in the Token Vault. -3. The application [links user accounts](/docs/manage-users/user-accounts/user-account-linking) with the user's consent. As a result, the user won’t have to create separate accounts for each external provider. -4. Your application calls Auth0 to exchange a valid Auth0 refresh token with an access token for a federated connection. Your application can perform this exchange multiple times while Auth0 manages refreshing the federated access tokens stored in the Token Vault. Using a federated access token, your application can call third-party APIs on the user’s behalf. +* Auth0 obtains access and refresh tokens using OAuth 2.0 scopes, with the user explicitly approving the requested permissions. +* Auth0 securely stores the tokens for each connected account in the Token Vault. Because each connected account is linked to the user profile, the application can access external APIs and services without requiring the user to re-authorize the connection. +* The application calls Auth0 to exchange a user’s valid Auth0 token for an external provider’s access token, issued to that user. To learn more, read [Supported token exchanges](#supported-token-exchanges). +* Using the external provider’s access token, your application can then call external APIs on the user's behalf. -Token Vault allows for seamless federated identity and simplifies integration across multiple external providers via a single Auth0 interface. +## Supported token exchanges -## Common use cases +To call an external provider’s APIs, your application must exchange a valid Auth0 token for an external provider’s access token from Token Vault. The type of Auth0 token used for the exchange depends on your client application type and use case. -Learn about some common Token Vault use cases: +Applications can access Token Vault using the following token exchanges: -* A user downloads a productivity app that integrates with Auth0 and connects their Google and Microsoft user accounts. With user account linking, they can log into the productivity app using a single set of credentials managed by Auth0. -* An AI agent integrated into an application calls third-party APIs to perform tasks on the user’s behalf, such as scheduling a meeting in Google Calendar. + + + + + + + + + + + + + + + + + + + +
Token exchangeDescriptionClient application type
Refresh token exchangeExchanges an Auth0 refresh token for an external provider’s access token.Applications that need to maintain a user's session and access external APIs when the user isn't actively using the application, such as web, mobile, and native applications.
Access token exchangeExchanges an Auth0 access token for an external provider’s access token.APIs or microservices that need to exchange access tokens they’ve received from other services or applications, such as a Single-Page Application (SPA).
## Get started @@ -63,12 +94,20 @@ To get started with Token Vault, read the following: -Configure Token Vault -How to configure the Token Vault. +Connected Accounts for Token Vault +How to configure and use Connected Accounts for Token Vault. + + +Refresh Token Exchange with Token Vault +How an application uses the refresh token exchange with Token Vault to call external APIs. -Call APIs with Token Vault -How an application accesses the Token Vault to get an access token to call third-party APIs. +Access Token Exchange with Token Vault +How an application uses the access token exchange with Token Vault to call external APIs. + + +Configure Token Vault +How to configure the Token Vault, including the token exchange. \ No newline at end of file diff --git a/main/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault.mdx b/main/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault.mdx new file mode 100644 index 000000000..58c58a6b6 --- /dev/null +++ b/main/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault.mdx @@ -0,0 +1,151 @@ +--- +description: Learn how an application can access the Token Vault to exchange an Auth0 access token for an access + token to call external APIs. +'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png +'og:title': Access Token Exchange with Token Vault +'og:url': https://auth0.com/docs/ +permalink: access-token-exchange-with-token-vault +title: Access Token Exchange with Token Vault +'twitter:description': Learn how an application can access the Token Vault to exchange an Auth0 access token for an access + token to call external APIs. +'twitter:title': Access Token Exchange with Token Vault +--- + +Token Vault supports the access token exchange, which enables a client application to exchange an Auth0 access token (subject token) for an external provider’s access token (requested token). + +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. + +Instead, the backend API can exchange the Auth0 access token received from the SPA for an external provider’s access token, otherwise known as the access token exchange. This process keeps the sensitive external credentials secure on the backend. + +In Auth0’s access token exchange, the backend API acts as both a client and a resource server: +* 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. +* Resource server: Serves the backend API to the SPA and validates the Auth0 access token. + +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. + +## Use cases + +Common use cases for the access token exchange include: +* 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. +* 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. + +## How it works + +The following sequence diagram describes end-to-end how to call external APIs using the access token exchange in Auth0: + +![](/docs/images/token-vault/access_token_exchange_flow_diagram.png) + +Let’s walk through a real-world example: A user wants to schedule a meeting in their Google Calendar using an SPA. + +## Prerequisites + +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). + +## Step 1: Connect and authorize access + +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. +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. + +## Step 2: SPA calls backend API with Auth0 access token + +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: + +* Signature: Verify the token's signature using Auth0's public key. This confirms that Auth0 issued the access token. +* Issuer: Checks the `iss` claim in the token's payload to confirm that the token was issued by your Auth0 tenant. +* 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. +* Expiration: Validates the `exp` claim to ensure the token is still valid and has not expired. +* Scopes: Checks the `scope` claim to determine what permissions the user has been granted. + +After successfully completing these checks, the backend API can trust the Auth0 access token and proceed with the token exchange. + +## Step 3: Backend API performs access token exchange + +For the access token exchange, you need to [create a Custom API Client](/docs/secure/tokens/token-vault/configure-token-vault#create-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. + +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 perform the access token exchange, the backend API calls Auth0 SDKs to make a `POST` request to the `/oauth/token` endpoint. + +In the token request, the backend API: +* Passes the backend API’s (the Custom API Client’s) client credentials to the Auth0 Authorization Server to authenticate itself. +* Exchange an Auth0 access token for a Google access token. + +```bash lines +curl --request POST 'https://{yourDomain}/oauth/token' \ + --header 'Content-Type: application/json' \ + --data '{ + "client_id": "", + "client_secret": "", + "subject_token": "", + "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token", + "subject_token_type": "urn:ietf:params:oauth:token-type:access_token", + "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token", + "connection": "google-oauth2" + }' +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
grant_typeThe grant type. For Token Vault, set to urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_idClient application ID
client_secretClient secret. Note: You can use any client authentication method to get an external provider's access token.
subject_token_typeType of subject token. For the access token exchange, set to the access token: urn:ietf:params:oauth:token-type:access_token.
subject_tokenThe Auth0 access token that the Auth0 Authorization Server validates to identify the user.
requested_token_typeThe 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
connectionThe 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 4: Auth0 Authorization Server validates access token + +The Auth0 Authorization Server validates and loads the user profile associated with the Auth0 access token: +* 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. +* Auth0 checks if the user profile’s `connected_accounts` array contains a user account with the connection name passed in the authorization request. +* If the authorization request contains `login_hint`, Auth0 looks for an identity matching both the connection name and the `login_hint`. +* 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: + +```json lines +{ + "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" +} +``` + +Using the Google access token, the backend API calls the Google Calendar API on the user’s behalf to schedule the meeting. \ No newline at end of file diff --git a/main/docs/secure/tokens/token-vault/call-apis-with-token-vault.mdx b/main/docs/secure/tokens/token-vault/call-apis-with-token-vault.mdx deleted file mode 100644 index e3996600d..000000000 --- a/main/docs/secure/tokens/token-vault/call-apis-with-token-vault.mdx +++ /dev/null @@ -1,191 +0,0 @@ ---- -description: Learn how an application can access the Token Vault to get an access - token to call third-party APIs. -'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png -'og:title': Call APIs with Token Vault -'og:url': https://auth0.com/docs/ -permalink: call-apis-with-token-vault -title: Call APIs with Token Vault -'twitter:description': Learn how an application can access the Token Vault to get - an access token to call third-party APIs. -'twitter:title': Call APIs with Token Vault ---- - - -Token Vault is currently available in Early Access for public cloud tenants. To enable Token Vault, contact your Auth0 representative. - - - -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. - -## Prerequisites - -Before getting started, you must [configure Token Vault](/docs/secure/tokens/token-vault/configure-token-vault). - -## Get access to third-party API - -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](https://auth0.com/docs/api/authentication/login), the Auth0 SDK makes a `GET` request to the `/authorize` endpoint with the following additional parameters: - - - - - - - - - - - - - - - - - - - - - -
ParameterDescription
connectionThe name of a social identity provider. In this case, google-oauth2.
connection_scopeRequests 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.

scopeRequests Auth0 scopes to be authorized for the application. Include offline_access to get an Auth0 refresh token from the Auth0 Authorization Server.
- -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](/docs/manage-users/user-accounts/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. - -## Call third-party API - -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](#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: - - - -```javascript lines -// 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' }); -``` - - - - - - - - -```json lines -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" -} -``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterDescription
grant_typeThe grant type. For Token Vault, set to urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_idClient application ID
client_secretClient secret. Note: You can use any client authentication method to get a federated access token.
subject_token_typeType of subject token. For Token Vault, set to refresh token: urn:ietf:params:oauth:token-type:refresh_token
subject_tokenThe Auth0 refresh token that the Auth0 Authorization Server validates to identify the user.
requested_token_typeThe requested token type. For Token Vault, set to federated access token or http://auth0.com/oauth/token-type/federated-connection-access-token
connectionThe connection name, in this case, google-oauth2.
login_hint(Optional) The user ID for the identity provider. Only use login_hint if the user has several accounts from the same connection. For instance, a user may connect their work and personal Google account.
- -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 federated access token within the Token Vault. If it is still valid, Auth0 returns the federated access token with its scopes and expiry time: - -```json lines -{ -  "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](#manage-federated-refresh-tokens). - -Using the federated access token, the application calls the Google Calendar API on the user’s behalf. - -## Manage federated refresh tokens - -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](/docs/secure/tokens/refresh-tokens). - -### Federated refresh token expiration policy - -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. \ No newline at end of file diff --git a/main/docs/secure/tokens/token-vault/configure-token-vault.mdx b/main/docs/secure/tokens/token-vault/configure-token-vault.mdx index e45887e48..8bcf72d01 100644 --- a/main/docs/secure/tokens/token-vault/configure-token-vault.mdx +++ b/main/docs/secure/tokens/token-vault/configure-token-vault.mdx @@ -8,29 +8,16 @@ title: Configure Token Vault 'twitter:description': Learn how to configure Token Vault. 'twitter:title': Configure Token Vault --- - - -Token Vault is currently available in Early Access for public cloud tenants. To enable Token Vault, contact your Auth0 representative. - - -Auth0 supports Token Vault for the following social and enterprise identity providers: - -* Google -* Microsoft -* Box -* Slack -* GitHub -* OpenID Connect -* Custom social connection - -Once a user authenticates with a supported external provider and authorizes the federated connection, you can get an access token to call third-party APIs on the user’s behalf. To learn more, read [Call APIs with Token Vault](/docs/secure/tokens/token-vault/call-apis-with-token-vault). +Once a user authenticates with a [supported external provider](/docs/secure/tokens/token-vault#supported-external-providers) and authorizes the connection, your application can access Token Vault to exchange an Auth0 token for an extenal provider's access token. To configure Token Vault, you need to: -1. Configure your application with the Token Exchange (Federated Connection) grant type. -2. Enable Token Vault for a federated connection. -3. Manage tokensets within the Token Vault for your federated connection. +1. [Configure Connected Accounts for Token Vault](/docs/secure/tokens/token-vault/configure-token-vault#configure-connected-accounts-for-token-vault) for a supported social or enterprise connection. +2. [Configure your application](#configure-application) with the Token Vault grant type. +3. Configure the token exchange for your application: + * [Refresh token exchange](#configure-refresh-token-exchange) + * [Access token exchange](#configure-access-token-exchange) @@ -40,11 +27,17 @@ If you need to trigger MFA challenges for interactive flows, enable **Customize +## Configure Connected Accounts for Token Vault + +Connected Accounts for Token Vault manages a unified Auth0 user profile linked to multiple external accounts. Your application then fetches the stored credentials in Token Vault to interact with external APIs on the user’s behalf. + +You can configure Connected Accounts for supported social and enterprise connections. To learn more, read [Configure Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#configure-connected-accounts). + ## Configure application -Configure your application with the Token Exchange (Federated Connection) grant type using the Auth0 Dashboard or Management API. +Configure your application with the Token Vault grant type using the Auth0 Dashboard or Management API. -Only certain types of clients can use the Token Exchange (Federated Connection) grant type: +Only certain types of clients can use the Token Vault grant type: 1. The client must be a first-party client, i.e. the `is_first_party` property is `true`. 2. The client must be a confidential client with a valid authentication mechanism, i.e. the `token_endpoint_auth_method` property must not be set to `none`. @@ -54,19 +47,19 @@ Only certain types of clients can use the Token Exchange (Federated Connection) 1. Navigate to **Applications > Applications**. 2. Select the application you want to configure. -3. Under **Advanced Settings > Grant Types**, select the **Token Exchange (Federated Connection)** grant type. +3. Under **Advanced Settings > Grant Types**, select the **Token Vault** grant type. 4. Select **Save Changes**. -![](/docs/images/cdy7uua7fh8z/4pDrKjLpUISfhhGAfc0EaU/28517676a42ec418c75a7034a0cad343/configure_federated_connection_token_exchange.png) +![](/docs/images/token-vault/configure_token_vault_grant_type.png) To enable Token Vault for an application, make a `PATCH` call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to add the `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token` grant type to the client JSON object: ```bash lines -curl --location --request PATCH 'https://{tenantDomain}/api/v2/clients/{clientId}' \ +curl --location --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \ --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer {your_management_api_access_token}' \ + --header 'Authorization: Bearer ' \ --data '{ "grant_types": [ "authorization_code", @@ -83,138 +76,177 @@ curl --location --request PATCH 'https://{tenantDomain}/api/v2/clients/{clientId -## Configure federated connection - -Use the Auth0 Dashboard or Management API to configure a federated connection to retrieve and store access tokens for third-party APIs in the Token Vault. +## Configure token exchange -Once you enable Token Vault for your connection, access and refresh tokens will no longer be stored in the user’s `identities` array. Instead, they will be stored in a secure tokenset within the Token Vault. To learn more, read [Manage tokensets](#manage-tokensets). +To call an external provider’s APIs, your application must exchange a valid Auth0 token for an external provider’s access token from Token Vault. The type of Auth0 token used for the exchange depends on your client type and use case. To learn more, read [Supported token exchanges](/docs/secure/tokens/token-vault#supported-token-exchanges). - +### Configure refresh token exchange -To enable Token Vault for a supported social and enterprise/custom connection: +To use the [refresh token exchange with Token Vault](/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault), you need to configure your application with the following grant types: +* Authorization Code: Enables your application to perform the initial user login, where your application exchanges a temporary authorization code for an Auth0 access token, refresh token, and ID token. +* Refresh token: Enables your application to use a long-lived Auth0 refresh token to request a new Auth0 access token without requiring the user to log in again. +* Token Vault: Enables your application to exchange an Auth0 refresh token for an external provider’s access token stored in the Token Vault. -1. Navigate to **Authentication > Social Connections** or **Enterprise Connections**. -2. Select **Create Connection** or select an existing connection. -3. In **Permissions**, select the desired scopes for your connection. You can filter by scope name or keywords. Whenever the user is redirected to authorize this connection, Auth0 always requests the scopes you selected. At runtime, this list is automatically completed with any additional scopes included in the `connection_scope` parameter of the authorization request. -4. In **Advanced**, toggle **Enable Token Vault**. -5. Select **Save Changes**. + -![](/docs/images/cdy7uua7fh8z/69jDhgpWbFY1npKDNY9wOT/360db4a0140ff3a3a68f169f3b99c98c/Screenshot_2025-04-03_at_07.49.56.png) +To configure your application for the refresh token exchange: +* Navigate to **Applications > Applications**. +* Select the application you want to configure. +* Under **Advanced Settings > Grant Types**, select the **Refresh Token**, **Authorization Code**, and **Token Vault** grant types. +* Select **Save Changes**. -To enable Token Vault for a supported social and enterprise connection, make a `PATCH` call to the [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint and set `federated_connections_access_tokens` to `true` in the `options` object: - - - -When you use the `options` parameter when making a `PATCH` call to the [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint, you override the existing `options` object with the `options` object in your request body. As a result, make sure you include your entire `options` object in your request body. - - +To configure your application for the refresh token exchange, make a `PATCH` call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to add the `refresh_token`, `authorization_code,` and `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token` grant types to the client JSON object: ```bash lines -curl --location --request PATCH 'https://{tenantDomain}/api/v2/connections/{connectionId}' \ +curl --location --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \ --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer {your_management_api_access_token}' \ - --header 'Accept: application/json' \ + --header 'Authorization: Bearer ' \ --data '{ - "options": { - "federated_connections_access_tokens": { - "active": true - }, - ... - } + "grant_types": [ + "authorization_code", + "refresh_token", + "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token" + ] }' ``` - - - - - -## Manage tokensets - -The Auth0 Authorization Server securely stores the user's access and refresh token in the Token Vault, which maintains one tokenset per authorized connection. - -To manage tokensets for a user, use the Management API: - -* [Get user's tokensets](#get-user-s-tokensets) -* [Delete a tokenset](#delete-a-tokenset) - -### Get user’s tokensets - -To get a user's tokensets, you need a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `read:federated_connections_tokensets` scope. +### Configure access token exchange -Make a `GET` request to the `/federated-connections-tokensets` endpoint: +To use the [access token exchange with Token Vault](/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault), you need to: +* [Configure your SPA](#configure-your-spa) with the `authorization_code` grant type. +* [Create a backend API](#create-backend-api) that the SPA can request an Auth0 access token for by specifying it as the audience. +* [Create a Custom API Client](#create-custom-api-client) that is linked to the backend API with the Token Vault grant type enabled. -```bash lines -curl --request GET \ - --url 'https://{tenantDomain}/api/v2/users/{user_id}/federated-connections-tokensets' \ - --header 'Authorization: Bearer {your_management_api_access_token}' -``` +#### 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](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to add the `authorization_code` grant type to the client JSON object: -If successful, you should receive a list of tokensets for the user: - -```json lines -Status Code: 200 -[{ -  "connection": "google-oauth2", -  "id": "some-unique-tokenset-id1", -  "issued_at": 1733455897, -  "expires_at": 1733455897, -  "last_used_at": 1733453897, -  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events", -},{ -  "id": "some-unique-tokenset-id2", -  "connection": "google-oauth2", -  "issued_at": 1733455897, -  "expires_at": 1733455897, -  "last_used_at": 1733453897, -  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events", -},{ -  "connection": "google-oauth2", -  "issued_at": 1733455897, -  "id": "some-unique-tokenset-id3", -  "expires_at": 1733455897, - "last_used_at": 1733453897, -  "scope": "Calendar.Read Calendar.Write", -}] +```bash lines +curl --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "grant_types": [ + "authorization_code" + ] + }' ``` + +#### 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](/docs/get-started/auth0-overview/set-up-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. -**Note:** The value for `last_used_at` is updated max once per day. + -### Delete a tokenset +To create a backend API using the Management API, make a `POST` request to the `/resource-servers` endpoint: -To delete a tokenset, you need a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `update:federated_connections_tokensets` scope. +```bash lines +curl --request POST 'https://{yourDomain}/api/v2/resource-servers' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --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" + } + ] + }' +``` + -Make a `DELETE` request to the `/tokensets` endpoint: +#### Create Custom API Client -```bash lines -curl --request DELETE \ - --url 'https://{tenantDomain}/api/v2/users/{user_id}/federated-connections-tokensets/{tokenset_id}' \ - --header 'Authorization: Bearer {your_management_api_access_token}' -``` +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. +![](/docs/images/token-vault/create_custom_api_client.png) + -If successful, you should receive the following response: +The following code sample creates a Custom API Client with the same identifier as your backend API and adds the Token Vault grant type: -```json lines -Response: 204 No-Content +```bash lines +curl --request POST 'https://{yourDomain}/api/v2/clients' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --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" + ] + }' ``` - + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
nameName of your Custom API Client.
app_typeThe application type of your Custom API Client. To register the client as a resource server, set to resource_server.
resource_server_identifierThe unique identifier for your Custom API Client. Set to the audience of your backend API i.e. `https://my-api.example.com.`
grant_typesThe 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. diff --git a/main/docs/secure/tokens/token-vault/connected-accounts-for-token-vault.mdx b/main/docs/secure/tokens/token-vault/connected-accounts-for-token-vault.mdx new file mode 100644 index 000000000..43804573e --- /dev/null +++ b/main/docs/secure/tokens/token-vault/connected-accounts-for-token-vault.mdx @@ -0,0 +1,625 @@ +--- +description: Learn how to configure and use Connected Accounts for Token Vault. +'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png +'og:title': Connected Accounts for Token Vault +'og:url': https://auth0.com/docs/ +permalink: connected-accounts-for-token-vault +sidebarTitle: Connected Accounts for Token Vault +title: Connected Accounts for Token Vault +'twitter:description': Learn how to configure and use Connected Accounts for Token Vault. +'twitter:title': Connected Accounts for Token Vault +--- + +Connected Accounts for Token Vault enables applications to securely access external APIs on the user’s behalf through [Token Vault](/docs/secure/tokens/token-vault). While standard user authentication handles user login through a social or enterprise identity provider, Connected Accounts links a user profile to external services like Google, GitHub, Slack, and more, facilitating delegated access to external APIs on the user’s behalf. + +Once a user successfully connects and authorizes access to a [supported external provider](/docs/secure/tokens/token-vault#supported-external-providers), Auth0 securely stores the following: +* The account on the user profile as a connected account. +* The external provider’s access and refresh tokens for that connected account in the Token Vault. + +Connected Accounts for Token Vault creates and manages a unified Auth0 user profile linked to multiple external accounts, enabling seamless authorization. Your application then fetches the stored credentials in Token Vault to interact with external APIs on the user’s behalf. + +## User authentication vs Connected Accounts + +When you [configure Connected Accounts](#configure-connected-accounts) for a supported social or enterprise connection, Auth0 uses the Connected Accounts flow (`/me/v1/connected-accounts` endpoint) to retrieve and store access and refresh tokens in the Token Vault instead of using the social or enterprise login flow (`/authorize` endpoint). After successfully completing the Connected Accounts flow, Auth0 adds the user account to the `connected_accounts` array on the user profile. In contrast, for the social or enterprise login flow, Auth0 adds the user account to the `identities` array on the user profile. + +The following table explains the differences between the user authentication and Connected Accounts flows: + + + + + + + + + + + + + + + + + + + + + + + + + +
User AuthenticationConnected Accounts
FlowLogin flow using the `/authorize` endpointConnected Accounts flow using the My Account API’s `/me/v1/connected-accounts` endpoint
User profileAdds user account to `identities` arrayAdds user account to `connected_accounts` array
PurposeAuthenticates users with a social or enterprise identity providerStores the access and refresh tokens for the connected account in Token Vault when a user logs in via a supported external provider, connects, and authorizes the connection
+ +You can enable user authentication, Connected Accounts, or both for supported social or enterprise connections. The following table explains the behavior for the different Purpose settings, including how to pass scopes to the connection: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AuthenticationConnected AccountsBehaviorScopes
EnabledDisabledThe connection uses the `/authorize` login flow to authenticate users as a valid identity provider.Use the Auth0 Dashboard or Management API to pass the desired scopes for your connection. At runtime, this list is automatically completed with any additional scopes included in the `connection_scope` parameter of the authorization request.
DisabledEnabledThe connection uses the Connected Accounts flow to retrieve and store the tokens for the connection in the Token Vault. The connection does not use the `/authorize` login flow to authenticate users, and is excluded from the list of valid identity providers.Use the Auth0 Dashboard or Management API to pass the desired scopes to your connection. At runtime, any scopes included in the `scopes` parameter in the authorization request take precedence over the scopes selected in the Auth0 Dashboard except for `offline_access`, if required by the connection and enabled in the Auth0 Dashboard.

Note: If required by the connection, Auth0 will prompt you to enable `offline_access`, allowing the client application to fetch a refresh token from Auth0. You must enable `offline_access` for the connection in the Auth0 Dashboard.
EnabledEnabledThe connection uses the `/authorize` login flow to authenticate users as a valid identity provider. It also uses the Connected Accounts flow to retrieve and store access tokens for the connection in the Token Vault.Use the Auth0 Dashboard and Management API to pass the desired scopes to the connection. At runtime, any scopes included in the `scopes` parameter take precedence over the scopes selected in the Auth0 Dashboard except for `offline_access`, if required by the connection and enabled in the Auth0 Dashboard.

Note: If required by the connection, Auth0 will prompt you to enable `offline_access`, allowing the client application to fetch a refresh token from Auth0. You must enable `offline_access` for the connection in the Auth0 Dashboard.
+ +## How it works + +The Connected Accounts flow uses the [My Account API](/docs/manage-users/my-account-api) to create and manage connected accounts for a user across supported external providers. + +Before the user can initiate a Connected Accounts request from the client application, the client application needs to [get an access token](/docs/manage-users/my-account-api#get-an-access-token) with the Connected Accounts scopes to access the My Account API. + +The following sequence diagram illustrates the end-to-end Connected Accounts flow: + +![](/docs/images/token-vault/connected_accounts_flow_diagram.png) + +When a user logs in via a supported external provider through Auth0, they initiate a Connected Accounts request from the client application: + +1. The client application makes a `POST` request to the My Account API’s `/me/v1/connected-accounts` endpoint, passing scopes and other parameters to send to the external provider. To learn more, read [Initiate Connected Accounts request](#initiate-connected-accounts-request). +2. The My Account API creates a unique `auth_session` and `connect_uri` containing a `ticket` that redirects the user to a web browser. The client application saves the `auth_session` for later verification. If [DPoP](/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop) is configured, the My Account API validates the DPoP Proof JWT. +3. The client application redirects the user to the `connect_uri` with the `ticket` as a query parameter for user authentication and authorization in the browser. The client application may also pass a `code_challenge` or `code_challenge_method` to the URL, as in the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). +4. The user connects and authorizes the permissions for the connection in the consent screen. +5. After the user successfully authorizes the connection, the external provider redirects the user to the My Account API, which redirects the user to the client application using the `redirect_uri` with a single-use `connect_code`. +6. The client application presents the `connect_code`, `code_verifier` (if applicable), and the original `auth_session` to the My Account API by making a `POST` request to the `/me/v1/connected-accounts/complete` endpoint. To learn more, read [Complete Connected Accounts request](#complete-connected-accounts-request). +7. The My Account API validates the request by confirming: + * The `auth_session` matches the ID originally issued for the user + * The request is coming from the same device that initiated the Connected Accounts flow + * The DPoP Proof JWT (if configured) + * The single-use `connect_code` + * The `code_verifier` (if using the PKCE flow) +8. After successful validation, the Auth0 Authorization Server adds the account to the `connected_accounts` array on the user profile and stores the access and refresh tokens for the connected account in the Token Vault. +9. My Account API completes the flow by sending a `200` status code back to the client application, indicating that the account was successfully connected. + +## Prerequisites + +Before configuring Connected Accounts, make sure you: +- [Configure Token Vault](/docs/secure/tokens/token-vault/configure-token-vault) for your client application to securely store the access and refresh tokens associated with each connected account in the Token Vault. +- [Configure the My Account API](#configure-my-account-api), which is used by authenticated users to connect and manage accounts. +- [Configure Multi-Resource Refresh Token (MRRT)](#configure-multi-resource-refresh-token) to get an access token for the My Account API. +- (Optional) [Configure DPoP](/docs/secure/sender-constraining/configure-sender-constraining) for the My Account API and your client application to sender constrain access tokens, preventing token theft. By default, the My Account API can accept DPoP-bound access tokens. + +### Configure My Account API + +To use Connected Accounts, configure the My Account API in the Auth0 Dashboard: +1. Navigate to **Applications > APIs** and [activate the My Account API](/docs/manage-users/my-account-api#activate-the-my-account-api). +2. Once activated, select **Auth0 My Account API** and then the **Applications** tab. +3. Toggle your client application to authorize it to access the My Account API. +4. In the dropdown menu, select the [Connected Accounts scopes](/docs/manage-users/my-account-api#scope) for the application in the dropdown. +5. Select **Update**. This creates a [client grant](/docs/get-started/applications/application-access-to-apis-client-grants) that allows your client application to access the My Account API with the Connected Accounts scopes on the user’s behalf. +6. If you’re using [Multi-Resource Refresh Token](/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token#multi-resource-refresh-token), navigate to the **Settings** tab. Under **Access Settings**, select **Allow Skipping User Consent**. + +### Configure Multi-Resource Refresh Token + +Configure Multi-Resource Refresh Token (MRRT) to get a single long-lived refresh token that can be exchanged for new My Account API access tokens and other APIs without requiring the user to re-authenticate. + +While you can use any [authentication and authorization flow](/docs/get-started/authentication-and-authorization-flow) that uses the `/authorize` endpoint to get an access token for the My Account API, Auth0 recommends using MRRT for native applications with the Authorization Code Flow with PKCE. By default, the [AI Framework SDKs](https://auth0.com/ai/docs/sdks/overview) use MRRT to get an access token for the My Account API. + +You can configure MRRT with the [Auth0 Dashboard](https://manage.auth0.com) or the [Management API](https://auth0.com/docs/api/management/v2). + + + +To configure MRRT with the Auth0 Dashboard: +1. Navigate to **Applications > Applications** and select your application. +2. Under **Multi-Resource Refresh Token**, select **Edit Configuration**. +3. To enable MRRT with the My Account API, toggle on the **My Account API**. + + + +To configure MRRT for a client application, make a `PATCH` request to the `/api/v2/clients/{clientId}` endpoint and add the My Account API identifier and Connected Accounts scopes to the refresh token policies: + +```bash lines +curl -X PATCH --location "https://${account.namespace}/api/v2/clients/{clientId}" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "is_first_party": true, + "refresh_token": { + "expiration_type": "non-expiring", + "leeway": 0, + "infinite_token_lifetime": true, + "infinite_idle_token_lifetime": true, + "token_lifetime": 31557600, + "idle_token_lifetime": 2592000, + "rotation_type": "non-rotating", + "policies": [ + { + "audience": "https://'"$DOMAIN"'/me/", + "scope": [ + "create:me:connected_accounts", + "read:me:connected_accounts", + "delete:me:connected_accounts" + ] + } + ] + } + }' +``` + + + +## Configure Connected Accounts + +Before configuring Connected Accounts for a connection, make sure you’ve authorized the connection for your client application. + +In the Auth0 Dashboard: +1. Navigate to **Authentication > Social Connections** or **Enterprise Connections** and select the connection. +2. Select **Applications** and then toggle on the connection for your client application. + +You can configure Connected Accounts with the [Auth0 Dashboard](https://manage.auth0.com) or the [Management API](https://auth0.com/docs/api/management/v2). + + + +To configure Connected Accounts with the Auth0 Dashboard: +1. Navigate to **Authentication > Social Connections** or **Enterprise Connections**. +2. Select **Create Connection** or select an existing connection. +3. In **Purpose**, toggle on **Use for Connected Accounts for Token Vault**. Depending on your **Purpose** setting, you may need to enable `offline_access` in the Auth0 Dashboard, allowing the client application to obtain an Auth0 refresh token. To learn more, read [User authentication vs Connected Accounts](#user-authentication-vs-connected-accounts). +5. Click **Save**. + + + +To configure Connected Accounts with the Management API, make a `PATCH` request to the `/connections/{connectionId}` endpoint to set `connected_accounts` to `true`: + +```bash lines +curl -L -X PATCH "https://{yourDomain}/api/v2/connections/{connectionId}" \ +-H 'Content-Type: application/json' \ +-H 'Accept: application/json' \ +-H "Authorization: Bearer " \ +-d '{"connected_accounts":{"active":true}}' +``` + + + +## Get access token for Connected Accounts + +Before initiating a Connected Accounts request, [get an access token](/docs/manage-users/my-account-api#scope) for the My Account API with the Connected Accounts scopes. + +The following sections explain how to use [Multi-Resource Refresh Token (MRRT)](/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token) to get an access token for the My Account API. + +### Fetch a refresh token + +After [configuring MRRT](#configure-multi-resource-refresh-token) for the client application, initiate the authorization code flow and exchange the resulting authorization code for a refresh token. + +The following is an authorization code flow request for a confidential client that includes the `offline_scope` to return a refresh token and a single-use authorization code for the `https://my-example-api.com`: + +```bash lines +open "https://{yourDomain}/authorize?client_id=&response_type=code&prompt=login&scope=openid%20profile%20offline_access&redirect_uri=&state=&audience=https://my-example-api.com" +``` + +Exchange the single-use authorization code for a refresh token at the `/token` endpoint: + +```bash lines +curl -s --request POST \ + --url "https://{yourDomain}/oauth/token" \ + --header 'Content-Type: application/json' \ + --data-binary @- <", + "scope": "openid profile offline_access", + "client_id": "", + "client_secret": "", + "audience": "https://my-example-api.com", + "redirect_uri": "" +} +EOF +``` + +### Exchange refresh token for My Account API access token + +Once you’ve obtained a refresh token, exchange it for an access token with a different audience (the My Account API) and the Connected Accounts scopes using the refresh token grant type: + +```bash lines +curl -s -X POST "https://{yourDomain}/oauth/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + --data-urlencode "grant_type=refresh_token" \ + --data-urlencode "client_id=" \ + --data-urlencode "client_secret=" \ + --data-urlencode "refresh_token=" \ + --data-urlencode "audience=https://{yourDomain}/me/" \ + --data-urlencode "scope=openid profile offline_access create:me:connected_accounts read:me:connected_accounts delete:me:connected_accounts" +``` + +## Initiate Connected Accounts request + +To initiate a Connected Accounts request, make a `POST` request to the My Account API’s `/me/v1/connected-accounts/connect` endpoint with the following parameters: + + +For a Google social connection, make sure you select `offline_access` in the Auth0 Dashboard when configuring your connection. This is required for your client application to fetch a refresh token from the Auth0 Authorization Server. + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
connectionName of connection. For a Google social connection, set to google-oauth2.
redirect_uriThe callback URL of your client application.
stateA unique, random string associated with the request to prevent attacks.
scopes(Optional) The scopes passed to the external provider as an array of strings.

If used to pass scopes for a Google social connection, include `openid` and `profile` at a minimum. At runtime, any scopes included in the `scopes` parameter take precedence over the scopes selected in the Auth0 Dashboard except for `offline_access`, if required by the connection and enabled in the Auth0 Dashboard.
+ +```bash lines +curl --request POST "https://{yourDomain}/me/v1/connected-accounts/connect" \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer " \ +--data '{ + "connection": "google-oauth2", + "redirect_uri": "", + "state": "", + "scopes": ["openid","profile"] // any scopes passed overwrite the scopes you selected in the Auth0 Dashboard + } +}' +``` + + +If successful, the My Account API returns a response like the following: + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
auth_sessionSession ID that represents the current, authenticated session of the primary user. The client application saves the session ID for later verification.
connect_uriURL that the client application redirects the user to, which opens up a web browser to handle authorization with the external provider.
connect_paramsAdditional parameters necessary for the connect URI. Includes a temporary ticket that the My Account API uses to verify the request.
expires_inExpiry time for the session in seconds.
+ +```json +{ + "auth_session": "PKM-CYkdx2FyLb4Oob4ED91cSE7i_XJ4SVJByik0xKQxz9CgUZ5JlYr-aMPty0Xr", + "connect_uri": "https://{yourDomain}.us.auth0.com/connect", + "connect_params": { + "ticket": "9375f326-5846-4b57-ae8b-8042573f7c1f" + }, + "expires_in": 300 +} +``` + +In the web browser, navigate to the `connect_uri` with the `ticket` as a query parameter. Authorize the list of scopes in the consent screen, then extract and save the `connect_code` in the URL fragment. + +## Complete Connected Accounts request + +To complete a Connected Accounts request, make a `POST` request to the `/me/v1/connected-accounts/complete` endpoint with the following parameters: + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
auth_sessionSession ID that represents the current, authenticated session of the primary user. The client application saves the session ID for later verification.
connect_codeA single-use, short-lived code received from the authorization process of the external provider. This code is securely exchanged on the server-side to retrieve the final access tokens for the external API.
redirect_uriThe exact callback URL of your application where the user was sent after successfully authorizing the connection with the external provider. This value must match the `redirect_uri` used to initiate the flow.
+ +```bash lines +curl --location "https://{yourDomain}/me/v1/connected-accounts/complete" \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer " \ +--data '{ + "auth_session": "", + "connect_code": "", + "redirect_uri": "" +}' +``` + +If successful, the My Account API returns a response like the following: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
idUnique identifier for the connected account.
connectionName of the connection.
created_atTimestamp of when the connected account was created and linked to the user profile.
scopesThe specific OAuth scopes (permissions) that the user granted your application access to when connecting to the external provider. These scopes determine what external API actions your application can perform.
access_typeIndicates the type of access granted. A common value is `offline`, which signifies that a refresh token was successfully obtained and stored, allowing your application to maintain access even when the user is offline.
+ +```json +{ + "id": "cac_6ZqSK7Kj1R8LDZJvSb1tAn", + "connection": "google-oauth2", + "created_at": "2025-10-13T21:09:04.126Z", + "scopes": [ + "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.profile", + "openid" + ], + "access_type": "offline" +} +``` + +## Manage Connected Accounts + +To manage a user’s connected accounts, use the `/me/v1/connected-accounts` collection. + +Before using the `/connected-accounts` collection, [get an access token for Connected Accounts](#get-access-token-for-connected-accounts). + +### Query connected accounts connections + +Make a `GET` request to the `/me/v1/connected-accounts/connections` endpoint to return a list of connections that are linked to the user profile: + +```bash lines +curl -X GET --location "https://{yourDomain}/me/v1/connected-accounts/connections" \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer " +``` + +If successful, the My Accounts API returns a response like the following: + +```json +{ + "connections": [ + { + "name": "google-oauth2", + "strategy": "google-oauth2", + "scopes": [ + "email", + "profile", + "https://www.googleapis.com/auth/calendar", + "https://www.googleapis.com/auth/calendar.events", + "https://www.googleapis.com/auth/calendar.addons.execute", + "https://www.googleapis.com/auth/calendar.events.readonly", + "https://www.googleapis.com/auth/calendar.settings.readonly", + "openid" + ] + }, + { + "name": "custom", + "strategy": "oauth2", + "scopes": [ + "openid" + ] + } + ] +} +``` + +### Query connected accounts + +Make a `GET` request to the `/me/v1/connected-accounts/accounts` endpoint to return a list of connected accounts linked to the user profile: + +```bash lines +curl -X GET --location "https://{yourDomain}/me/v1/connected-accounts/accounts" \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer " +``` + +If successful, the My Accounts API returns a response like the following: + +```json +{ + "accounts": [ + { + "id": "cac_6ZqSK7Kj1R8LDZJvSb1tAn", + "connection": "google-oauth2", + "access_type": "offline", + "scopes": [ + "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.profile", + "openid" + ], + "created_at": "2025-10-13T21:09:04.126Z" + }, + { + "id": "cac_fH32E6CWN7HcWZN5w9Vieq", + "connection": "custom", + "access_type": "offline", + "scopes": [ + "offline_access", + "openid", + "profile" + ], + "created_at": "2025-10-13T18:06:47.216Z" + } + ] +} +``` + +You can also use the Management API to return a list of connected accounts for a user profile by making a `GET` request to the `/users/{userId}/connected-accounts` endpoint: + +```bash lines +curl -X GET --location "https://{yourDomain}/api/v2/users/{userId}/connected-accounts" \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer " +``` + +If successful, the Management API returns a response like the following: + +```json +{ + "connected_accounts": [ + { + "id": "cac_6ZqSK7Kj1R8LDZJvSb1tAn", + "connection": "google-oauth2", + "connection_id": "con_uBbSbbSpqGqOTvRu", + "strategy": "google-oauth2", + "access_type": "offline", + "scopes": [ + "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.profile", + "openid" + ], + "created_at": "2025-10-13T21:09:04.126Z" + } + ] +} +``` + +### Query connected accounts for a given connection + +Make a `GET` request to the `/me/v1/connected-accounts/accounts` endpoint and pass the connection name as a query parameter to return a list of connected accounts filtered by a given connection linked to a user profile: + +```bash lines +curl -X GET --location "https://{yourDomain}/me/v1/connected-accounts/accounts?connection={connectionName}" \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer " +``` + +If successful, the My Accounts API returns a response like the following, filtered for `google-oauth2` connections: + +```json +{ + "accounts": [ + { + "id": "cac_6ZqSK7Kj1R8LDZJvSb1tAn", + "connection": "google-oauth2", + "access_type": "offline", + "scopes": [ + "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.profile", + "openid" + ], + "created_at": "2025-10-13T21:09:04.126Z" + } + ] +} +``` + +### Delete connected account + +Make a `DELETE` request to the `/me/v1/connected-accounts/accounts/{connectedAccountId}` endpoint to delete a connected account for a given ID: + +```bash lines +curl -X DELETE --location "https://{yourDomain}/me/v1/connected-accounts/accounts/{connectedAccountId}" \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer " +``` + +When you delete a connected account, Auth0 removes the external provider’s access and refresh tokens from the Token Vault. This does not automatically 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. + +If successful, the My Accounts API returns a response like the following: + +``` +HTTP/1.1 204 No Content +``` + + + + + + + + + + + + + diff --git a/main/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault.mdx b/main/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault.mdx new file mode 100644 index 000000000..9ecbd05e4 --- /dev/null +++ b/main/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault.mdx @@ -0,0 +1,134 @@ +--- +description: Learn how an application can access the Token Vault to exchange an Auth0 refresh token for an access + token to call external APIs. +'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png +'og:title': Refresh Token Exchange with Token Vault +'og:url': https://auth0.com/docs/ +permalink: refresh-token-exchange-with-token-vault +title: Refresh Token Exchange with Token Vault +'twitter:description': Learn how an application can access the Token Vault to exchange an Auth0 refresh token for an access + token to call external APIs. +'twitter:title': Refresh Token Exchange with Token Vault +--- + +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: + +![](/docs/images/token-vault/refresh_token_exchange_flow_diagram.png) + +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](/docs/secure/tokens/token-vault/configure-token-vault#configure-refresh-token-exchange). + +## 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](/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. + +## Step 2: Perform refresh token exchange + + +While Token Vault does not support refresh token rotation, you can use [DPoP](/docs/secure/sender-constraining/demonstrating-proof-of-possession-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: + +```bash lines +curl --request POST 'https://{yourDomain}/oauth/token' \ +--header 'Content-Type: application/json' \ +--data '{ + "client_id": "", + "client_secret": "", + "subject_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" +}' +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
grant_typeThe grant type. For Token Vault, set to urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_idClient application ID
client_secretClient secret. Note: You can use any client authentication method to get an external provider's access token.
subject_token_typeType of subject token. For Token Vault, set to refresh token: urn:ietf:params:oauth:token-type:refresh_token
subject_tokenThe Auth0 refresh token that the Auth0 Authorization Server validates to identify the user.
requested_token_typeThe 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
connectionThe 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: + +```json lines +{ + "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. \ No newline at end of file