> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.generaltranslation.app/llms.txt
> Use this file to discover all available pages before exploring further.

> Apprenez 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.

# Échange de jetons d’accès avec Token Vault

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](/docs/fr-CA/secure/tokens/token-vault/refresh-token-exchange-with-token-vault) 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.

<div id="use-cases">
  ## Cas d’utilisation
</div>

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.

<div id="how-it-works">
  ## Fonctionnement
</div>

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 :

<Frame>
  <img src="https://mintcdn.com/generaltranslationinc/78hG6sVmUVcUqk59/docs/images/token-vault/access_token_exchange_flow_diagram.png?fit=max&auto=format&n=78hG6sVmUVcUqk59&q=85&s=5448b94c3101b8b74a3c9cef52f07a25" alt="" width="1322" height="794" data-path="docs/images/token-vault/access_token_exchange_flow_diagram.png" />
</Frame>

Voyons un exemple concret : un utilisateur veut planifier une réunion dans son Google Agenda à l'aide d'une SPA.

<div id="prerequisites">
  ## Prérequis
</div>

Avant de commencer, vous devez [configurer l’échange du jeton d’accès avec Token Vault](/docs/fr-CA/secure/tokens/token-vault/configure-token-vault#configure-access-token-exchange).

<div id="step-1-connect-and-authorize-access">
  ## Étape 1 : Se connecter et autoriser l’accès
</div>

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](/docs/fr-CA/secure/tokens/token-vault/connected-accounts-for-token-vault#how-it-works), qui utilise la [My Account API](/docs/fr-CA/manage-users/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.

<div id="step-2-spa-calls-backend-api-with-auth0-access-token">
  ## Étape 2 : Le SPA appelle l’API back-end avec le jeton d’accès Auth0
</div>

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.

<div id="step-3-backend-api-performs-access-token-exchange">
  ## Étape 3 : l’API backend effectue l’échange de jetons d’accès
</div>

Pour l’échange de jetons d’accès, vous devez [créer un Client d’API personnalisé](/docs/fr-CA/secure/tokens/token-vault/configure-token-vault#create-custom-api-client) 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.

```bash lines theme={null}
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"
  }'
```

<table class="table">
  <thead>
    <tr>
      <th><strong>Paramètre</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Le type de grant. Pour Token Vault, définissez-le sur <code>urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token</code></td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>ID de l’application cliente</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Secret client. <strong>Remarque :</strong> vous pouvez utiliser n’importe quelle méthode d’authentification de client pour obtenir le jeton d’accès du fournisseur externe.</td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td>Type du jeton de sujet. Pour l’échange de jeton d’accès, définissez-le sur le jeton d’accès : <code>urn:ietf:params:oauth:token-type:access\_token</code>.</td>
    </tr>

    <tr>
      <td><code>subject\_token</code></td>
      <td>Le jeton d’accès Auth0 que le Serveur d’autorisation Auth0 valide pour identifier l’utilisateur.</td>
    </tr>

    <tr>
      <td><code>requested\_token\_type</code></td>
      <td>Le type de jeton demandé. Pour Token Vault, définissez-le sur le jeton d’accès du fournisseur externe ou <code>[http://auth0.com/oauth/token-type/federated-connection-access-token](http://auth0.com/oauth/token-type/federated-connection-access-token)</code></td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>Le nom de la connexion, dans ce cas, <code>google-oauth2</code>.</td>
    </tr>

    <tr>
      <td><code>login\_hint</code></td>
      <td>(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.</td>
    </tr>
  </tbody>
</table>

<div id="step-4-auth0-authorization-server-validates-access-token">
  ## Étape 4 : Le Serveur d’autorisation Auth0 valide le jeton d’accès
</div>

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 :

```json lines theme={null}
{
  "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.