Échange de jeton d’actualisation avec Token Vault

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

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

Comme les jetons d’actualisation ne sont échangés que sur un canal sécurisé côté serveur entre le client et le serveur d’autorisation, ils ne sont jamais exposés à l’utilisateur final. Les clients peuvent ainsi maintenir la session d’un utilisateur sans l’obliger à autoriser de nouveau la connexion.

​

Cas d’utilisation

Les cas d’utilisation courants de l’échange de jeton d’actualisation comprennent :

• Application Web : une application Web de productivité se connecte au Google Calendar d’un utilisateur et effectue des tâches en son nom, comme planifier des réunions, sans obliger l’utilisateur à s’authentifier de nouveau.
• Application mobile : une application mobile de galerie photo se connecte au compte Google Photos d’un utilisateur et téléverse des photos au fur et à mesure qu’elles sont prises, tout en maintenant la session de l’utilisateur ouverte grâce à l’actualisation du jeton d’accès en arrière-plan.

​

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’actualisation dans Auth0 :

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

​

Prérequis

Avant de commencer, vous devez configurer l’échange du jeton d’actualisation avec Token Vault.

​

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

Pour planifier la réunion, l’application Web 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 avec Google à l’aide du Connected Accounts flow, qui utilise la My Account API. Si l’application utilise Organizations, l’utilisateur se connecte d’abord à l’organisation cible avant de poursuivre. Une fois la Connected Accounts request validée et menée à bien par la My Account API, celle-ci stocke les jetons d’accès et d’actualisation Google avec les scopes de calendrier demandés dans le Token Vault.

​

Étape 2 : Effectuer l’échange de jeton d’actualisation

Bien que Token Vault ne prenne pas en charge la rotation des jetons d’actualisation, vous pouvez utiliser DPoP pour lier les jetons émis par Auth0 à votre client afin de renforcer la sécurité. Pour réussir l’échange de jeton d’actualisation avec Token Vault, désactivez l’option Allow Refresh Token Rotation pour votre application dans l’Auth0 Dashboard.

L’application peut utiliser un jeton d’actualisation Auth0 valide pour demander un jeton d’accès Google à Token Vault avec les scopes accordés dans le flux Connected Accounts. Ce processus permet à l’application d’obtenir un nouveau jeton d’accès sans obliger l’utilisateur à autoriser de nouveau la connexion.

Pour effectuer l’échange de jeton d’actualisation, l’application appelle les SDK Auth0 pour envoyer une requête POST au point de terminaison /oauth/token avec les paramètres suivants :

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

Parameter	Description
grant_type	Le type de grant. Pour Token Vault, définissez-le à urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_id	ID de l’application cliente
client_secret	Secret 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 de sujet. Pour Token Vault, définissez-le comme jeton d’actualisation : urn:ietf:params:oauth:token-type:refresh_token
subject_token	Le jeton d’actualisation 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 comme le jeton d’accès du fournisseur externe ou comme 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 uniquement si l’utilisateur possède plusieurs comptes 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 jetons, vous indiquez explicitement lequel des comptes liés de l’utilisateur est visé par la demande.

​

Étape 3 : Auth0 Authorization Server valide le jeton d’actualisation

Auth0 Authorization Server valide et charge le profil utilisateur associé au jeton d’actualisation Auth0 :

1. 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.
2. Si la demande d’autorisation contient login_hint, Auth0 recherche une identity correspondant à la fois au nom de la connexion et au login_hint.
3. Si Auth0 ne trouve pas l’utilisateur, il renvoie un code d’état 401 avec un message d’erreur.

Une fois qu’Auth0 Authorization Server a validé l’utilisateur, il repère le Google jeton d’accès dans le Token Vault. S’il est toujours valide, Auth0 renvoie le Google jeton d’accès avec ses scopes et son délai 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"
}

Si le Google jeton d’accès a expiré, Auth0 utilise le Google jeton d’actualisation stocké dans le Token Vault pour obtenir un nouveau Google jeton d’accès doté des mêmes scopes.

À l’aide du Google jeton d’accès, l’application appelle la Google Calendar API au nom de l’utilisateur.

​

Politique d’expiration du jeton d’actualisation du fournisseur externe

Auth0 supprime les jetons d’actualisation d’un fournisseur externe lorsqu’ils arrivent à expiration selon la date d’expiration définie par le fournisseur externe. Les jetons sont aussi supprimés s’ils n’ont pas été utilisés dans le cadre d’un échange de jetons depuis plus d’un an.