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

# Jetons d’actualisation avec des Actions

> En savoir plus sur la gestion des jetons d’actualisation avec des Actions

L’utilisation des jetons d’actualisation avec des [Actions](/docs/fr-ca/customize/actions) vous permet de configurer des capacités de détection et de réponse aux risques post-authentification afin de protéger vos applications et vos utilisateurs contre les jetons d’actualisation compromis. Vous pouvez également personnaliser dynamiquement [les expirations des jetons d’actualisation](/docs/fr-ca/secure/tokens/refresh-tokens/configure-refresh-token-expiration).

Pour faciliter cela, les Actions post-connexion comportent deux objets clés :

* **event.refresh\_token** : Fournit des renseignements pertinents pour les refresh\_tokens existants, y compris les données `id`, `created_at`, `expires_at`, `idle_expires_at`, `clients_id`, des données liées à `device`, comme `ASN`, `IP` et `User_agent`, et pour les flux basés sur le navigateur, `session_id`. Cet objet est rempli par des flux [d’échange de jetons d’actualisation](/docs/fr-ca/secure/tokens/refresh-tokens/use-refresh-token-rotation).
* **api.refreshToken** : Vous permet de gérer les jetons d’actualisation existants en révoquant des sessions ou en modifiant les dates d’expiration.

Vous pouvez utiliser l’objet `event.refresh_token` pour examiner la propriété `last_exchange_at` et évaluer les risques associés aux transactions en cours. Vous pouvez également combiner l’objet `event.refresh_token` avec d’autres objets d’événement, tels que `event.authentication`.

Vous pouvez ensuite utiliser l’objet `api.refreshToken` pour définir des dates d’expiration du jeton d’actualisation ou révoquer le jeton d’actualisation.

Pour en savoir plus sur ces objets, consultez :

* [Objet événement](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object) : En savoir plus sur l’objet et les propriétés d’événement de jeton d’actualisation.
* [Objet API](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)  : En savoir plus sur l’objet API du jeton d’actualisation et ses méthodes.

## Révoquer les jetons d’actualisation à l’aide d’actions

La méthode post-connexion **api.refreshToken.revoke(reason)** vous permet de réagir aux risques associés à une transaction. Révoquer le jeton d’actualisation invalide celui-ci, renvoie un code d’état HTTP 403 pour refuser la transaction en cours et enregistre un événement révoqué de jeton d’actualisation dans les [journaux du client](/docs/fr-ca/deploy-monitor/logs/log-event-type-codes) (`srrt`).

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Si vous souhaitez utiliser la méthode `api.refreshToken.revoke(reason)`, assurez-vous que l’objet event.refresh\_token existe.
</Callout>

### Surveiller les événements de révocation du journal

L’opération de révocation ajoute l’événement de journal suivant dans vos [journaux du locataire](/docs/fr-ca/deploy-monitor/logs) :

Un code d’événement `srrt` indiquant qu’un jeton d’actualisation a été révoqué.

Si le jeton d’actualisation est lié à une session précédemment authentifiée, le journal inclura une référence à la session authentifiée dans l’attribut `session_id`.

## Cas d’utilisation des jetons d’actualisation avec les Actions

Vous pouvez modifier les dates d’expiration des jetons d’actualisation avec les méthodes de post-connexion suivantes :

* **api.refreshToken.setExpiresAt(absolute)** vous permet de définir une nouvelle date d’expiration absolue pour un jeton d’actualisation spécifié.
* **api.refreshToken.setIdleExpiresAt(idle)** vous permet de définir une nouvelle date d’expiration du délai d’inactivité pour un jeton d’actualisation spécifié.

Vous pouvez utiliser ces méthodes pour personnaliser dynamiquement les stratégies de durée de vie et d’inactivité des jetons d’actualisation en fonction de :

* L’organisation d’un utilisateur
* La connexion Auth0 d’un utilisateur
* L’adhésion ou le profil de groupe d’un utilisateur spécifique
* L’évaluation des risques
* Tout autre critère dynamique disponible lors de l’exécution de l’Action

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `api.refreshToken.setExpiresAt(absolute)` et `api.refreshToken.setIdleExpiresAt(idle)` permettent de définir l’expiration d’un jeton d’actualisation, avant son émission, ou de modifier l’expiration d’un jeton d’actualisation existant au cours d’un flux [échange de jetons d’actualisation](/docs/fr-ca/secure/tokens/refresh-tokens/use-refresh-tokens).

  `api.refreshToken.setExpiresAt(absolute)` et `api.refreshToken.setIdleExpiresAt(idle)` convertissent les jetons d’actualisation qui n’expirent pas en jetons d’actualisation expirant en utilisant les paramètres par défaut [Refresh Token Expirations (Expirations du jeton d’actualisation)](/docs/fr-ca/secure/tokens/refresh-tokens/configure-refresh-token-expiration) comme valeurs maximales.

  `api.refreshToken.setIdleExpiresAt(idle)` définit le délai d’inactivité pour les jetons d’actualisation. Si la méthode n’est pas appelée dans tous les échanges réussis, le délai d’inactivité sera écrasé à l’aide des paramètres de l’application de durée de vie du jeton d’actualisation.
</Callout>

## Limites

Les jetons d’actualisation émis à partir du 21-09-2023 (22-02-2024 pour les locataires de la région US-3) contiennent la propriété identification de session (`session_id`) avec la valeur appropriée. Les jetons d’actualisation émis avant cette date contiennent cette propriété avec une valeur `null`.

Les jetons d’actualisation émis avant la publication de la méthode API post-connexion `api.refreshToken.revoke(reason)` ne contiendront pas les données `event.refresh_token.device`.

Les jetons d’actualisation qui n’expirent pas ou les jetons d’actualisation qui n’ont pas été échangés ne contiendront pas la propriété `event.refresh_token.last_exchanged_at​`.

Pour des raisons de sécurité, les délais d’inactivité et absolu ne peuvent pas être définis au-dessus des paramètres du jeton d’actualisation de l’application définis dans [les dates d’ expiration du jeton d’actualisation](/docs/fr-ca/secure/tokens/refresh-tokens/configure-refresh-token-expiration). Si vous tentez de définir une date au-dessus des paramètres d’expiration, les méthodes de l’API la mettront à jour en fonction [des dates d’ expiration des jetons d’actualisation](/docs/fr-ca/secure/tokens/refresh-tokens/configure-refresh-token-expiration) et enregistreront un événement d’avertissement ( `w` ) dans les journaux du locataire.

## Cas d’utilisation : Révocation d’un jeton d’actualisation

Vous pouvez utiliser les [Actions](/docs/fr-ca/customize/actions) pour configurer les détections de risques et révoquer les jetons d’actualisation avec la méthode `api.refreshToken.revoke(reason)` et les objets d’événement.

### Révoquer les jetons d’actualisation en raison d’ImpossibleTravel

Vous pouvez utiliser l’objet [évaluations](https://auth0.com/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa#assessments-object) de l’authentification multifacteur (<Tooltip href="/docs/fr-ca/glossary?term=multifactor-authentication" tip="Authentification multifacteur (MFA)
Processus d’authentification de l’utilisateur qui utilise un facteur en plus du nom d’utilisateur et du mot de passe, tel qu’un code par SMS." cta="Voir le glossaire">MFA</Tooltip>) adaptative pour déterminer si un utilisateur se connecte à partir d’un lieu qui indique ImpossibleTravel et révoquer le jeton d’actualisation associé à la transaction.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication ?? {};
  const ImpossibleTravel = riskAssessment?.assessments.ImpossibleTravel;

  // If this is an impossible travel and this is a refresh token exchange
  if (ImpossibleTravel?.code === "impossible_travel_from_last_login") {
    if (event.refresh_token) {
      api.refreshToken.revoke("Refresh token revoked due to impossible travel");
    }
  }
};
```

Dans cet exemple, une vérification se produit au début de l’Action pour vérifier si `event.authentication.ImpossibleTravel.code` est égal à `impossible_travel_from_last_login property`. Si la valeur est `true`, l’Action appelle `api.refreshToken.revoke()` pour :

* refuser la transaction;
* Révoquer le jeton d’actualisation
* renvoyer une erreur « 403 access\_denied »;
* émettre l’erreur « Jeton d’actualisation révoqué en raison d’un voyage impossible »

### Révoquer les jetons d’actualisation en raison d’une liaison IP

Si vous utilisez les propriétés des objets post-connexion `event.refresh_token.device.initial_ip` et `event.request.ip`, vous pouvez vous assurer qu’une transaction de jeton d’actualisation conserve la même adresse IP pendant toute sa durée. Dans ce scénario, tout changement d’IP est considéré comme un risque et un nouveau jeton d’actualisation est nécessaire.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const refreshTokenInitialIp = event.refresh_token?.device?.initial_ip;
  const requestCurrentIp = event.request.ip;

  // if there is a refresh token and the IP changes
  if (
    refreshTokenInitialIp &&
    requestCurrentIp &&
    refreshTokenInitialIp != requestCurrentIp
  ) {
    api.refreshToken.revoke("Invalid IP change");
  }
};
```

Dans cet exemple, une vérification se produit au début de l’Action pour suivre les adresses IP avec les propriétés `event.refresh_token.device.initial_ip` et `event.request.ip`. L’Action détermine si l’adresse IP de la transaction a changé. Si la valeur est `true`, l’Action appelle `api.refreshToken.revoke()` pour :

* refuser la transaction;
* Révoquer le jeton d’actualisation
* renvoyer une `erreur` 403 `access_denied`
* émettre l’erreur « `Invalid IP change` » (Changement d’adresse IP invalide)

Pour une Action moins restrictive, vous pouvez également suivre les propriétés event.`request.asn` et `event.refresh_token.device.initial_asn` pour surveiller les changements d’ASN au lieu des changements d’IP.

## Cas d’utilisation : Personnaliser les dates d’expiration des jetons d’actualisation

Vous pouvez utiliser des [Actions](/docs/fr-ca/customize/actions) pour personnaliser la durée de vie et les dates d’inactivité des jetons d’actualisation. Plus précisément, vous pouvez configurer les dates d’expiration d’inactivité et absolue du jeton d’actualisation pour une transaction particulière à l’aide des méthodes post-connexion `api.refreshToken.setExpiresAt(absolute)` et `api.refreshToken.setIdleExpiresAt(idle)`

### Personnalisation de la date d’expiration absolue du jeton d’actualisation en fonction de l’organisation

Vous pouvez utiliser l’Action post-connexion pour définir une durée de vie du jeton d’actualisation par organisation. L’exemple ci-dessous utilise les métadonnées `refresh_token_timeout` de l’Organization pour définir l’heure d’expiration du jeton d’actualisation.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Refresh token timeout (in miliseconds) metadata configured in the Organizations
  const organization_refresh_token_lifetime =
    event.organization?.metadata?.refresh_token_timeout;

  if (organization_refresh_token_lifetime) {
    // Refresh token already exists
    if (event.refresh_token) {
      const created = Date.parse(event.refresh_token.created_at);

      const new_expiration_time =
        created + Number(organization_refresh_token_lifetime);
      api.refreshToken.setExpiresAt(new_expiration_time);
    } else {
      // Refresh token doesn't exist yet (e.g., token is being issued)
      const current_time = new Date().getTime();

      const new_expiration_time =
        current_time + Number(organization_refresh_token_lifetime);
      api.refreshToken.setExpiresAt(new_expiration_time);
    }
  }
};
```

Dans cet exemple, s’il existe un délai d’expiration absolu spécifique défini pour une Organization, l’Action définit le délai d’expiration absolu du jeton d’actualisation de façon à être égal à :

* Jetons nouvellement émis : `current_time` plus `organization_refresh_token_lifetime`
* Jetons existants : `event.refresh_token.created_at` plus `organization_refresh_token_lifetime`

### Personnalisation du délai d’inactivité du jeton d’actualisation en fonction du rôle d’adhésion

Vous pouvez utiliser l’action post-connexion pour définir un délai d’inactivité du jeton d’actualisation à l’aide des [métadonnées de l’application](/docs/fr-ca/get-started/applications/configure-application-metadata) et de [l’utilisateur](/docs/fr-ca/manage-users/user-accounts/metadata). L’exemple ci-dessous utilise les rôles de métadonnées de l’utilisateur pour définir le rôle d’adhésion de l’utilisateur et les métadonnées de l’application pour définir le délai d’inactivité du jeton d’actualisation attendu.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // admins are configured with a shorter idle timeout for refresh tokens, in an application metadata
  const max_idle_lifetime =
    event.client.metadata?.admin_refresh_token_idle_timeout;

  // Check the user app metadata roles attribute to check if it is an admin user.
  const isAdmin = event.user?.app_metadata?.roles?.find(
    (role) => role === "admin",
  );

  // If the application has an specific idle timeout defined, set the timeout
  if (max_idle_lifetime && isAdmin) {
    const current_time = new Date().getTime();

    api.refreshToken.setIdleExpiresAt(current_time + Number(max_idle_lifetime));
  }
};
```

Dans cet exemple, s’il y a un délai d’inactivité spécifique défini pour l’application et que l’utilisateur est un administrateur, l’Action définit le délai d’inactivité du jeton d’actualisation de façon à être égal à la valeur `current_time` plus le `refresh_token_idle_timeout`. Notez que nous modifions le délai d’expiration des jetons nouvellement émis et des jetons existants lors de l’échange de jetons d’actualisation.