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

> Découvrez comment configurer l’échange de jetons personnalisé en associant une Action à un profil de jetons personnalisé.

# Configurer l’échange de jetons personnalisé

Pour configurer l’échange de jetons personnalisé pour votre application, vous devez :

* [Remplir les conditions préalables](#prerequisites)
* [Activer l’échange de jetons personnalisé pour votre application](#enable-custom-token-exchange-for-your-application)
* [Configurer](#configure-custom-token-exchange-profile) et [gérer](#manage-custom-token-exchange-profile) un profil d’échange de jetons personnalisé

<h2 id="prerequisites">
  Prérequis
</h2>

Avant de configurer l’Échange de jetons personnalisé, assurez-vous que votre application remplit les prérequis suivants :

* Est un [client de première partie](/docs/fr-ca/get-started/applications/first-party-and-third-party-applications)
* Est [conforme à OIDC](/docs/fr-ca/get-started/applications/application-settings#oauth)

<h2 id="enable-custom-token-exchange-for-your-application">
  Activer l’échange de jetons personnalisé pour votre application
</h2>

Vous pouvez activer l’échange de jetons personnalisé pour plusieurs applications. Il est désactivé par défaut pour une application. Pour l’activer :

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Accédez à **Applications > Applications** et sélectionnez votre application.
    2. Sélectionnez l’onglet **Settings**.
    3. Repérez **Échange de jetons personnalisé** et activez la bascule.
    4. Sélectionnez **Save**.
  </Tab>

  <Tab title="Management API">
    Utilisez la Management API pour envoyer une requête `POST` à [Créer un client](https://auth0.com/docs/api/management/v2/clients/post-clients) ou une requête `PATCH` à [Mettre à jour un client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id), en définissant l’attribut `allow_any_profile_of_type` dans `token_exchange` sur `["custom_authentication"]` :

    ```json lines theme={null}
    {
      "token_exchange": {
        "allow_any_profile_of_type": ["custom_authentication"]
      }
    }
    ```
  </Tab>
</Tabs>

Une fois l’échange de jetons personnalisé activé pour l’application, activez également la connexion que vous souhaitez utiliser avec celui-ci.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Les bases de données personnalisées dont le mode d’importation est `ON` ne sont prises en charge que pour les opérations `setUserById()`.
</Callout>

Prenez note des valeurs `client_id` et `client_secret` de l’application; vous en aurez besoin plus tard pour appeler le endpoint `/oauth/token`.

<h2 id="configure-custom-token-exchange-profile">
  Configurer le Profil d’échange de jetons personnalisé
</h2>

Chaque Profil d’échange de jetons personnalisé établit un mappage un à un entre un `subject_token_type` et une Action, qui contient la logique de code pour un cas d’utilisation précis.

Les requêtes d’échange de jetons personnalisé envoyées au endpoint `/oauth/token` avec une valeur `subject_token_type` précise seront associées au profil de jeton personnalisé correspondant et acheminées vers l’Action associée pour traitement.

Utilisez les objets Event et API de échange de jetons personnalisé pour écrire l’Action associée à un profil. L’Action doit :

* Décode et valide le `subject_token` selon le `subject_token_type`. Vous obtiendrez ainsi des renseignements sur l’utilisateur pour la transaction.
* Applique toute politique d’autorisation nécessaire à la transaction.

Une fois que vous avez la certitude que la transaction peut se poursuivre, définissez l’utilisateur. Auth0 émettra alors des jetons d’accès, d’ID et d’actualisation pour cet utilisateur dans le cadre de l’authentification de l’utilisateur.

Pour voir des exemples d’Actions de échange de jetons personnalisé, consultez [Exemples de cas d’utilisation et échantillons de code](/docs/fr-ca/authenticate/custom-token-exchange/cte-example-use-cases).

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `subject_token_type` doit être un URI unique commençant par `https://` ou `urn`. Les espaces de noms suivants sont réservés et ne peuvent pas être utilisés : `http://auth0.com`, `https://auth0.com`, `http://okta.com`, `https://okta.com`, `urn:ietf`, `urn:auth0`, `urn:okta`.
</Callout>

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Accédez à **Authentication > Échange de jetons personnalisé** et sélectionnez **Créer un profil**.
    2. Dans la boîte de dialogue **Créer un profil** :
       * Saisissez un **nom** pour le profil.
       * Saisissez un **type de jeton du sujet** unique.
       * Choisissez comment fournir l’Action associée à ce profil :
         * **Partir de zéro** : saisissez un **nom** pour la nouvelle Action. Auth0 crée une Action vide, associée au déclencheur Échange de jetons personnalisé, lorsque vous créez le profil.
         * **Créer à partir d’un modèle** : sélectionnez un [modèle d’Action](/docs/fr-ca/customize/actions/actions-templates). Auth0 crée une nouvelle Action préremplie avec le code du modèle.
         * **Utiliser une Action existante** : sélectionnez une Action existante déjà associée au déclencheur Échange de jetons personnalisé.
    3. Sélectionnez **Créer**. Auth0 crée le profil — et l’Action, si vous avez choisi d’en créer une ou d’en créer une à partir d’un modèle — puis vous redirige vers la page **Détails** du profil.
    4. Dans la page **Détails** :
       * Modifiez le **nom** ou le **type de jeton du sujet** du profil au besoin.
       * Modifiez le **nom** de l’Action associée au besoin.
       * Utilisez l’éditeur de code intégré pour modifier le code de l’Action associée. Sélectionnez **Enregistrer** pour enregistrer un brouillon ou **Déployer** pour déployer une nouvelle version de l’Action.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Une fois le profil créé, vous ne pouvez plus modifier l’Action qui lui est associée.
    </Callout>
  </Tab>

  <Tab title="Management API">
    La création d’un profil d’échange de jetons personnalisé via la Management API se fait en deux étapes : créez d’abord l’Action, puis créez le profil qui référence l’ID de cette Action.

    <h3 id="create-the-action">
      Créer l’Action
    </h3>

    Écrivez le code de votre Action, puis utilisez l’API de gestion pour la [créer](https://auth0.com/docs/api/management/v2/actions/post-action) et la [déployer](https://auth0.com/docs/api/management/v2/actions/post-deploy-action).

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">Vous utilisez l’Auth0 CLI ? Si ce n’est pas déjà fait, [configurez et authentifiez votre session CLI](/docs/fr-ca/deploy-monitor/auth0-cli) avant d’exécuter ces commandes.</Callout>

    1. Effectuez la requête `POST` suivante vers l’endpoint `/actions/actions` pour créer l’Action associée au déclencheur `custom-token-exchange` :

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api post "actions/actions" \
          --data '{
              "name": "<YOUR_ACTION_NAME>",
              "supported_triggers": [
                { "id": "custom-token-exchange", "version": "v1" }
              ],
              "code": "exports.onExecuteCustomTokenExchange = async (event, api) => {\n  // votre logique personnalisée ici\n};"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location 'https://{yourDomain}/api/v2/actions/actions' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data '{
            "name": "<YOUR_ACTION_NAME>",
            "supported_triggers": [
                { "id": "custom-token-exchange", "version": "v1" }
            ],
            "code": "exports.onExecuteCustomTokenExchange = async (event, api) => {\n  // votre logique personnalisée ici\n};"
        }'
        ```
      </Tab>
    </Tabs>

    Vous devriez trouver l’ID de l’Action dans la propriété `id` du corps de la réponse. Vous en aurez besoin pour déployer l’Action et créer le profil d’échange de jetons personnalisé.

    2. Effectuez la requête `POST` suivante vers le point de terminaison `/actions/actions/{id}/deploy` pour déployer l’Action :

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api post "actions/actions/{yourActionId}/deploy"
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location --request POST 'https://{yourDomain}/api/v2/actions/actions/{yourActionId}/deploy' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Une Action doit être déployée avant de pouvoir être associée à un profil Custom Token Exchange.
    </Callout>

    Pour découvrir des exemples d’Actions Custom Token Exchange, consultez [Exemples de cas d’utilisation et d’échantillons de code](/docs/fr-ca/authenticate/custom-token-exchange/cte-example-use-cases).

    <h3 id="create-the-custom-token-exchange-profile">
      Créer le profil d’échange de jetons personnalisé
    </h3>

    Pour créer le profil d’échange de jetons personnalisé, utilisez l’API Management pour envoyer une requête `POST` avec les paramètres suivants au point de terminaison `/token-exchange-profiles` :

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api post "token-exchange-profiles" \
          --data '{
              "name": "<YOUR_PROFILE_NAME>",
              "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
              "action_id": "<YOUR_ACTION_ID>",
              "type": "custom_authentication"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data '{
            "name": "<YOUR_PROFILE_NAME>",
            "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
            "action_id": "<YOUR_ACTION_ID>",
            "type": "custom_authentication"
        }'
        ```
      </Tab>
    </Tabs>

    | Paramètre            | Description                                                                                                                                                                                                                                                                                                                                                 |
    | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `subject_token_type` | URI unique du type de token de profil commençant par `https://` ou `urn`<br /><br />Les espaces de noms suivants sont réservés et ne peuvent pas être utilisés :<br /><br /><ul><li>`http://auth0.com`</li><li>`https://auth0.com`</li><li>`http://okta.com`</li><li>`https://okta.com`</li><li>`urn:ietf`</li><li>`urn:auth0`</li><li>`urn:okta`</li></ul> |
    | `action_id`          | ID de l’Action associée au profil de jeton personnalisé.                                                                                                                                                                                                                                                                                                    |
    | `type`               | Doit être défini à `custom_authentication`.                                                                                                                                                                                                                                                                                                                 |

    Si vous avez créé avec succès un profil d’échange de jetons personnalisé, vous devriez recevoir une réponse semblable à la suivante :

    ```json lines theme={null}
    {
      "id":"tep_9xqewuejpa2RTltf",
      "name":"<YOUR_PROFILE_NAME>",
      "type":"custom_authentication",
      "subject_token_type":"<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
      "action_id":"<YOUR_ACTION_ID>",
      "created_at":"2025-01-30T13:19:00.616Z",
      "updated_at":"2025-01-30T13:19:00.616Z"
    }
    ```
  </Tab>
</Tabs>

<h3 id="manage-custom-token-exchange-profile">
  Gérer les profils d’échange de jetons personnalisés
</h3>

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Accédez à **Authentication > Custom Token Exchange** pour afficher la liste de vos profils d’échange de jetons personnalisés ainsi que leur **Nom**, leur **Type de jeton du sujet** et leur **ID d’Action**.
    2. Sélectionnez un profil pour ouvrir sa page **Détails**, où vous pouvez modifier son **Nom**, son **Type de jeton du sujet**, ainsi que le **Nom** et le code de l’Action associée (consultez [Configurer le profil d’échange de jetons personnalisé](#configure-custom-token-exchange-profile) ci-dessus).
    3. Pour supprimer un profil, ouvrez le menu d’options (l’icône à trois points) à côté du profil dans la liste, puis sélectionnez **Supprimer**.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Une Action liée à un profil d’échange de jetons personnalisé ne peut pas être supprimée séparément. Supprimez d’abord le profil, puis l’Action si vous n’en avez plus besoin.
    </Callout>
  </Tab>

  <Tab title="Management API">
    Pour gérer vos profils d’échange de jetons personnalisés, utilisez la Management API pour envoyer des requêtes au endpoint `/token-exchange-profiles`.

    Pour obtenir tous vos profils d’échange de jetons personnalisés, envoyez la requête `GET` suivante au endpoint `/token-exchange-profiles`. Ce endpoint prend en charge la pagination par checkpoint si vous avez plusieurs profils.

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api get "token-exchange-profiles"
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        ```
      </Tab>
    </Tabs>

    Pour mettre à jour le nom ou le `subject_token_type` d’un profil existant, envoyez la requête `PATCH` suivante au endpoint `/token-exchange-profiles`.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Une fois l’Action créée, vous ne pouvez plus modifier son ID.
    </Callout>

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api patch "token-exchange-profiles/{yourProfileId}" \
          --data '{
              "name": "external-idp-migration",
              "subject_token_type": "urn:partner0:external-idp-migration"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location --request PATCH 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data '{
            "name": "external-idp-migration",
            "subject_token_type": "urn:partner0:external-idp-migration"
        }'
        ```
      </Tab>
    </Tabs>

    Pour supprimer un profil d’échange de jetons personnalisé, envoyez la requête `DELETE` suivante au endpoint `/token-exchange-profiles` :

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api delete "token-exchange-profiles/{yourProfileId}" \
          --data ''
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data ''
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Une Action liée à un profil d’échange de jetons personnalisé ne peut pas être supprimée séparément. Supprimez d’abord le profil, puis l’Action si vous n’en avez plus besoin.
    </Callout>
  </Tab>
</Tabs>