Passer au contenu principal
Token Vault prend en charge l’échange de jetons d’accès, ce qui permet à une application cliente d’échanger un jeton d’accès Auth0 (jeton sujet) contre un jeton d’accès d’un fournisseur externe (jeton requis). Lorsqu’une application monopage (SPA) appelle 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 pour la SPA, elle ne peut pas utiliser l’échange de jeton d’actualisation pour accéder à Token Vault afin d’appeler des API externes. À la place, l’API backend peut échanger le jeton d’accès Auth0 reçu de la SPA contre un jeton d’accès d’un fournisseur externe, ce que l’on appelle l’échange de jetons d’accès. Ce processus permet de conserver les informations d’identification externes sensibles en sécurité dans le backend. Dans l’échange de jetons d’accès d’Auth0, l’API backend agit à la fois comme client et comme serveur de ressources :
  • Client : utilise ses propres informations d’identification pour effectuer de façon sécurisée l’échange de jetons d’accès avec le Serveur d’autorisation Auth0. Dans Auth0, vous créez un Custom API Client avec le même identifiant que l’API backend. L’API backend transmet les informations d’identification du Custom API Client pour effectuer de façon sécurisée l’échange de jetons 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 des clients non autorisés de dérober 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 pour l’échange de jetons d’accès incluent :
  • Une API backend : un utilisateur interagit avec une SPA, qui appelle ensuite une API backend pour échanger un jeton d’accès Auth0 contre le jeton d’accès d’un fournisseur externe avec le Serveur d’autorisation Auth0.
  • Architecture de 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 afin d’accéder à des API externes.

​
Fonctionnement

Le diagramme de séquence suivant décrit, de bout en bout, comment appeler des API externes au moyen de l’échange de jetons d’accès dans Auth0 :
Voyons un exemple concret : un utilisateur veut planifier une réunion dans son Google Agenda à l’aide d’une SPA.

​
Prérequis

Avant de commencer, vous devez configurer l’échange du 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 via Auth0, puis obtenir l’autorisation de l’utilisateur d’accéder à l’API Google Calendar. L’utilisateur se connecte à l’application via Google avec le flux Comptes connectés, qui utilise la My Account API. Une fois que la My Account API a validé et traité la requête Comptes connectés, 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 back-end avec le jeton d’accès Auth0

Lorsque le SPA appelle l’API back-end, il transmet le jeton d’accès Auth0 dans l’en-tête Authorization à l’API back-end. L’API back-end valide le jeton d’accès Auth0 en vérifiant les éléments suivants :
  • Signature : Vérifie 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 revendication iss dans la charge utile du jeton pour confirmer que le jeton a été émis par votre tenant Auth0.
  • Audience : Vérifie la revendication aud pour s’assurer qu’elle correspond à l’identifiant unique de l’API back-end elle-même. Cela confirme que le jeton a été émis spécifiquement pour ce serveur de ressources.
  • Expiration : Valide la revendication exp pour s’assurer que le jeton est toujours valide et qu’il n’a pas expiré.
  • Scopes : Vérifie la revendication scope pour déterminer quelles autorisations ont été accordées à l’utilisateur.
Après avoir terminé ces vérifications avec succès, l’API back-end peut faire confiance au jeton d’accès Auth0 et poursuivre l’échange de jetons.

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

Pour l’échange de jetons d’accès, vous devez créer un Client d’API personnalisé lié à l’API backend. Le Client d’API personnalisé a le même identifiant que votre API backend et a le type d’octroi Token Vault activé. Lorsque l’API backend effectue l’échange de jetons d’accès, elle s’authentifie en transmettant les informations d’identification du Client d’API personnalisé au Serveur d’autorisation Auth0, ce qui prouve qu’il s’agit de la même entité que celle qui a été enregistrée dans l’Auth0 Dashboard. Pour effectuer l’échange de jetons d’accès, l’API backend utilise les SDK Auth0 pour envoyer une requête POST au point de terminaison /oauth/token. Dans la requête de jeton d’accès, l’API backend :
  • Transmet les informations d’identification client de l’API backend (celles du Client d’API personnalisé) 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ètreDescription
grant_typeLe type de grant. Pour Token Vault, définissez-le sur urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_idID de l’application cliente
client_secretSecret client. Remarque : vous pouvez utiliser n’importe quelle méthode d’authentification de client pour obtenir le jeton d’accès du fournisseur externe.
subject_token_typeType du jeton de 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_tokenLe jeton d’accès Auth0 que le Serveur d’autorisation Auth0 valide pour identifier l’utilisateur.
requested_token_typeLe 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
connectionLe nom de la connexion, dans ce cas, google-oauth2.
login_hint(Facultatif) Utilisez uniquement login_hint si l’utilisateur possède plusieurs comptes provenant de la même connexion, par exemple un compte Google professionnel et un compte Google personnel. Lorsque vous transmettez une valeur pour login_hint au cours de l’échange de jetons, vous identifiez explicitement pour lequel des multiples comptes liés de l’utilisateur la requête est effectuée.

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

Le Serveur d’autorisation Auth0 valide et charge le profil de l’utilisateur associé au jeton d’accès Auth0 :
  • Auth0 vérifie que le client qui effectue la requête 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 de l’utilisateur contient un compte d’utilisateur avec le nom de la connexion transmis dans la requête d’autorisation.
  • Si la requête d’autorisation contient login_hint, Auth0 recherche une identité correspondant à la fois au nom de la connexion et à la valeur de 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 localise le jeton d’accès Google dans le Token Vault. S’il est encore 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 l’API Google Calendar au nom de l’utilisateur pour planifier la réunion.