Échange de jeton d’accès avec Token Vault

Découvrez comment une application peut accéder à Token Vault pour échanger un jeton d’accès Auth0 contre un jeton d’accès permettant d’appeler des API externes.

Token Vault prend en charge l’échange de jeton d’accès, qui permet à une application cliente d’échanger un jeton d’accès Auth0 (jeton du sujet) contre le jeton d’accès d’un fournisseur externe (jeton demandé).

Lorsqu’une application monopage (SPA) envoie une requête à une API backend, elle transmet uniquement un jeton d’accès Auth0 dans l’en-tête Authorization. Comme l’API backend ne reçoit aucun jeton d’actualisation émis à la SPA, elle ne peut pas utiliser l’échange de jeton d’actualisation pour accéder à Token Vault et appeler des API externes.

L’API backend peut plutôt échanger le jeton d’accès Auth0 reçu de la SPA contre le jeton d’accès d’un fournisseur externe, ce qu’on appelle aussi l’échange de jeton d’accès. Ce processus permet de protéger les informations d’authentification externes sensibles dans le backend.

Dans l’échange de jeton d’accès d’Auth0, l’API backend agit à la fois comme client et comme serveur de ressources :

• Client : Utilise ses propres informations d’authentification pour effectuer de façon sécurisée l’échange de jeton d’accès avec le serveur d’autorisation Auth0. Dans Auth0, vous créez un Custom API Client ayant le même identifiant que l’API backend. L’API backend transmet les informations d’authentification du Custom API Client pour effectuer de façon sécurisée l’échange de jeton d’accès avec le serveur d’autorisation Auth0.
• Serveur de ressources : Expose l’API backend à la SPA et valide le jeton d’accès Auth0.

En agissant comme intermédiaire entre la SPA et le serveur d’autorisation Auth0, l’API backend empêche les clients non autorisés de voler le jeton Auth0 et de l’utiliser pour accéder au fournisseur externe au nom de l’utilisateur.

​

Cas d’utilisation

Les cas d’utilisation courants de l’échange de jeton d’accès comprennent :

• Une API backend : un utilisateur interagit avec une SPA, qui envoie ensuite une requête à une API backend pour échanger, auprès du serveur d’autorisation Auth0, un jeton d’accès Auth0 contre le jeton d’accès d’un fournisseur externe.
• Architecture en microservices : des services backend, comme des serveurs MCP ou d’autres serveurs de ressources OAuth 2.0, qui doivent échanger des jetons d’accès pour accéder à des API externes.

​

Fonctionnement

Le diagramme de séquence suivant décrit de bout en bout comment effectuer des requêtes vers des API externes à l’aide de l’échange de jeton d’accès dans Auth0 :

Prenons un exemple concret : un utilisateur souhaite planifier une réunion dans Google Calendar à l’aide d’une SPA.

​

Prérequis

Avant de commencer, vous devez configurer l’échange de jeton d’accès avec Token Vault.

​

Étape 1 : Se connecter et autoriser l’accès

Pour planifier la réunion, la SPA doit se connecter à Google par l’entremise d’Auth0, puis obtenir la permission de l’utilisateur d’accéder à la Google Calendar API. L’utilisateur se connecte à l’application avec Google à l’aide du Connected Accounts flow, qui utilise la My Account API. Si l’application utilise Organizations, l’utilisateur se connecte à l’organisation cible avant de continuer.

Une fois que la My Account API a validé et mené à terme la requête Connected Accounts, elle stocke les jetons d’accès et d’actualisation Google avec les scopes de calendrier demandés dans le Token Vault.

​

Étape 2 : le SPA appelle l’API backend avec le jeton d’accès Auth0

Lorsque le SPA appelle l’API backend, il transmet le jeton d’accès Auth0 à l’API backend dans l’en-tête Authorization. L’API backend valide le jeton d’accès Auth0 en vérifiant les éléments suivants :

• Signature : Vérifiez la signature du jeton à l’aide de la clé publique d’Auth0. Cela confirme qu’Auth0 a émis le jeton d’accès.
• Émetteur : Vérifie la claim iss dans le payload du jeton pour confirmer que le jeton a été émis par votre tenant Auth0.
• Audience : Vérifie la claim aud pour s’assurer qu’elle correspond à l’identifiant unique de l’API backend elle-même. Cela confirme que le jeton a été émis spécifiquement pour ce serveur de ressources.
• Expiration : Valide la claim exp pour s’assurer que le jeton est toujours valide et n’a pas expiré.
• Scopes : Vérifie la claim scope pour déterminer quelles permissions ont été accordées à l’utilisateur.

Une fois ces vérifications réussies, l’API backend peut se fier au jeton d’accès Auth0 et procéder à l’échange de jetons.

​

Étape 3 : L’API backend effectue l’échange de jeton d’accès

Pour l’échange de jeton d’accès, vous devez créer un Custom API Client lié à l’API backend. Le Custom API Client a le même identifiant que votre API backend, et le type d’octroi Token Vault y est activé.

Lorsque l’API backend effectue l’échange de jeton d’accès, elle s’authentifie en transmettant les identifiants du Custom API Client au serveur d’autorisation Auth0, ce qui prouve qu’il s’agit bien de la même entité enregistrée dans l’Auth0 Dashboard.

Pour effectuer l’échange de jeton d’accès, l’API backend utilise les Auth0 SDKs pour envoyer une requête POST au point de terminaison /oauth/token.

Dans la requête de jeton, l’API backend :

• Transmet les identifiants client de l’API backend (ceux du Custom API Client) au serveur d’autorisation Auth0 pour s’authentifier.
• Échange un jeton d’accès Auth0 contre un jeton d’accès Google.

curl --request POST 'https://{yourDomain}/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YOUR_CUSTOM_API_CLIENT_ID>",
    "client_secret": "<YOUR_CUSTOM_API_CLIENT_SECRET>",
    "subject_token": "<YOUR_AUTH0_ACCESS_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"
  }'

Paramètre	Description
grant_type	Le type d’octroi. Pour Token Vault, définissez-le sur urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_id	ID de l’application cliente
client_secret	Secret du client. Remarque : Vous pouvez utiliser n’importe quelle méthode d’authentification du client pour obtenir le jeton d’accès d’un fournisseur externe.
subject_token_type	Type du jeton du sujet. Pour l’échange de jeton d’accès, définissez-le sur le jeton d’accès : urn:ietf:params:oauth:token-type:access_token.
subject_token	Le jeton d’accès Auth0 que le serveur d’autorisation Auth0 valide pour identifier l’utilisateur.
requested_token_type	Le type de jeton demandé. Pour Token Vault, définissez-le sur le jeton d’accès du fournisseur externe ou http://auth0.com/oauth/token-type/federated-connection-access-token
connection	Le nom de la connexion, dans ce cas-ci, google-oauth2.
login_hint	(Facultatif) Utilisez login_hint seulement si l’utilisateur a plusieurs comptes de la même connexion, comme un compte Google professionnel et un compte Google personnel. Lorsque vous transmettez une valeur pour login_hint pendant l’échange de jetons, vous indiquez explicitement lequel des multiples comptes liés de l’utilisateur est visé par la requête.

​

Étape 4 : Le serveur d’autorisation Auth0 valide le jeton d’accès

Le serveur d’autorisation Auth0 valide et charge le profil utilisateur associé au jeton d’accès Auth0 :

• Auth0 vérifie que le client qui effectue la demande d’échange de jeton d’accès est lié à l’API backend identifiée par l’audience du jeton d’accès.
• Auth0 vérifie si le tableau connected_accounts du profil utilisateur contient un compte d’utilisateur avec le nom de la connexion transmis dans la demande d’autorisation.
• Si la demande d’autorisation contient login_hint, Auth0 recherche une identity correspondant à la fois au nom de la connexion et au login_hint.
• Si Auth0 ne trouve pas l’utilisateur, il renvoie un code d’état 401 avec un message d’erreur.

Une fois que le serveur d’autorisation Auth0 a validé l’utilisateur, il repère le jeton d’accès Google dans le Token Vault. S’il est toujours valide, Auth0 renvoie le jeton d’accès Google avec ses scopes et son heure d’expiration :

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

À l’aide du jeton d’accès Google, l’API backend appelle la Google Calendar API au nom de l’utilisateur pour planifier la réunion.