Passer au contenu principal
Token Vault prend en charge l’échange de jetons d’accès, ce qui permet à une application d’échanger un jeton d’accès Auth0 (jeton sujet) contre le jeton d’accès d’un fournisseur externe (jeton demandé). 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 et appeler des API externes. À la place, l’API backend peut échanger le jeton d’accès Auth0 reçu de la SPA contre le jeton d’accès d’un fournisseur externe, autrement dit effectuer un échange de jetons d’accès. Ce processus permet de protéger les informations d’identification externes sensibles sur le backend. Dans l’échange de jetons d’accès d’Auth0, l’API backend agit à la fois comme application et comme serveur de ressources :
  • Application : 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 : met l’API backend à la disposition de 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 applications non autorisées 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 jetons d’accès comprennent :
  • Une API backend : un utilisateur interagit avec une SPA, qui appelle ensuite une API backend pour échanger un jeton d’accès Auth0 contre un jeton d’accès d’un fournisseur externe auprès du 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 pour accéder à des API externes.

​
Comment ça fonctionne

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

​
Prérequis

Avant de commencer, vous devez configurer l’échange de jetons 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’intermédiaire d’Auth0, puis obtenir l’autorisation de l’utilisateur pour accéder à l’API Google Calendar. L’utilisateur se connecte à l’application avec Google au moyen du flux Connected Accounts, qui utilise la My Account API. Si l’application utilise des Organisations, l’utilisateur se connecte d’abord à l’organisation cible avant de poursuivre. Une fois que la My Account API a validé et mené à bien la demande Connected Accounts, elle stocke dans le Token Vault les jetons Google d’accès et d’actualisation avec les scopes de calendrier demandés.

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

Lorsque la SPA appelle l’API backend, elle 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é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 locataire Auth0.
  • Audience : vérifie la revendication aud pour s’assurer qu’elle correspond à l’identifiant unique de l’API backend elle-même. Cela confirme que le jeton a bien été émis pour ce serveur de ressources.
  • Expiration : valide la revendication exp pour s’assurer que le jeton est toujours valide et n’a pas expiré.
  • Scopes : vérifie la revendication scope pour déterminer quelles autorisations ont été accordées à l’utilisateur.
Une fois ces vérifications effectuées avec succès, 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 jetons d’accès

Pour l’échange de jetons d’accès, vous devez créer un Custom API Client associé à l’API backend. Le Custom API Client a le même identifiant que votre API backend et le type d’octroi Token Vault est activé. Lorsque l’API backend effectue l’échange de jetons d’accès, elle s’authentifie en transmettant les informations d’identification du Custom API Client au serveur d’autorisation Auth0, ce qui prouve qu’il s’agit bien de la même entité que celle enregistrée dans l’Auth0 Dashboard. Pour effectuer l’échange de jetons d’accès, l’API backend appelle les SDK Auth0 pour envoyer une requête POST au point de terminaison /oauth/token. Dans la requête de jeton, l’API backend :
  • Transmet les informations d’identification de l’API backend (celles 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ètreDescription
grant_typeLe type d’octroi. Pour Token Vault, définissez-le sur urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_idID de l’application
client_secretSecret client. Remarque : Vous pouvez utiliser n’importe quelle méthode d’authentification d’application pour obtenir le jeton d’accès d’un fournisseur externe.
subject_token_typeLe type de jeton du sujet. Pour l’échange de jetons 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 sur http://auth0.com/oauth/token-type/federated-connection-access-token
connectionLe nom de la connexion, dans ce cas-ci, google-oauth2.
login_hint(Facultatif) Utilisez login_hint uniquement si l’utilisateur a 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 pendant l’échange de jeton, vous indiquez explicitement lequel des comptes liés de l’utilisateur est visé par la demande.

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

Le serveur d’autorisation Auth0 valide et récupère le profil de l’utilisateur associé au jeton d’accès Auth0 :
  • Auth0 vérifie que l’application qui effectue la demande d’échange de jetons d’accès est liée à 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 demande d’autorisation.
  • Si la demande d’autorisation contient login_hint, Auth0 recherche une identité 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 accompagné d’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 sa date 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.