É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 jetons d’actualisation, ce qui permet à une application cliente d’accéder à Token Vault pour échanger un jeton d’actualisation Auth0 (jeton sujet) contre un jeton d’accès d’un fournisseur externe (jeton demandé).

Comme les jetons d’actualisation sont échangés uniquement sur un canal sécurisé entre l’application cliente et le serveur d’autorisation, ils ne sont jamais exposés à l’utilisateur final. Les applications clientes peuvent ainsi maintenir la session de l’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 que l’utilisateur ait à 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 les photos au fur et à mesure qu’elles sont prises, tout en maintenant la session de l’utilisateur active 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 appeler 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 par l’entremise 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 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 application et ainsi renforcer la sécurité. Pour effectuer correctement l’échange de jeton d’actualisation avec Token Vault, désactivez Allow Refresh Token Rotation pour votre application dans l’Auth0 Dashboard.

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

Pour effectuer l’échange de jeton d’actualisation, l’application utilise 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 d’octroi. 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 de jeton du sujet. Pour Token Vault, définissez-le sur le 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 sur le jeton d’accès du fournisseur externe ou sur 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 a plusieurs comptes issus 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 auquel des comptes liés de l’utilisateur la demande s’applique.

​

Étape 3 : le serveur d’autorisation Auth0 valide le jeton d’actualisation

Le serveur d’autorisation Auth0 valide et charge le profil de l’utilisateur associé au jeton d’actualisation Auth0 :

1. Auth0 vérifie si le tableau connected_accounts du profil de l’utilisateur contient un compte associé au nom de la connexion transmis dans la demande d’autorisation.
2. Si la demande d’autorisation contient login_hint, Auth0 recherche une identité qui correspond à la fois au nom de la connexion et à login_hint.
3. 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 encore 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"
}

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

À l’aide du jeton d’accès Google, l’application appelle l’API Google Calendar pour le compte de l’utilisateur.

​

Politique d’expiration des jetons d’actualisation du fournisseur externe

Auth0 supprime les jetons d’actualisation d’un fournisseur externe à leur date d’expiration, telle que définie par le fournisseur externe. Les jetons sont également supprimés s’ils n’ont pas été utilisés lors d’un échange de jeton depuis plus d’un an.