Gérer les jetons d’actualisation avec Actions

Gérez les jetons d’actualisation Auth0 avec Actions pour lire ou modifier les revendications de jetons d’actualisation, définir des expirations personnalisées ou révoquer des jetons.

L’utilisation des jetons d’actualisation avec Actions vous permet de configurer des mécanismes de détection des risques et de réponse après l’authentification afin de protéger vos applications et vos utilisateurs contre les jetons d’actualisation compromis. Vous pouvez aussi personnaliser dynamiquement les expiration des jetons d’actualisation.

À cette fin, les Actions post-login comportent deux objets clés :

• event.refresh_token: Fournit des renseignements pertinents sur les refresh_tokens existants, notamment id, created_at, expires_at, idle_expires_at, clients_id, les renseignements sur device, comme ASN, IP et User_agent, ainsi que, pour les flux dans le navigateur, session_id. Cet objet est renseigné par les flux d’échange de jeton d’actualisation.
• 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 aussi combiner l’objet event.refresh_token avec d’autres objets d’événement, comme event.authentication.

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

Pour en savoir plus sur ces objets, consultez :

• Event object : Découvrez l’objet Event du jeton d’actualisation et ses propriétés.
• API object : Découvrez l’objet API du jeton d’actualisation et ses méthodes.

​

Révoquer des jetons d’actualisation avec Actions

La méthode api.refreshToken.revoke(reason) de post-login vous permet de réagir aux risques associés à une transaction. La révocation du jeton d’actualisation invalide ce jeton, renvoie un code d’état HTTP 403 pour rejeter la transaction en cours et consigne un événement de révocation de jeton d’actualisation dans les journaux du tenant (srrt).

Si vous souhaitez utiliser la méthode api.refreshToken.revoke(reason), assurez-vous que l’objet event.refresh_token existe.

​

Surveiller les événements de journal liés à la révocation

L’opération de révocation ajoute l’événement de journal suivant dans vos journaux du tenant :

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

Si le jeton d’actualisation est associé à une session authentifiée antérieurement, le journal comprendra une référence à cette session authentifiée dans l’attribut session_id.

​

Modifier les dates d’expiration des jetons d’actualisation avec Actions

Vous pouvez modifier les dates d’expiration des jetons d’actualisation à l’aide des méthodes post-login suivantes :

• api.refreshToken.setExpiresAt(absolute) vous permet de définir une nouvelle date d’expiration absolue pour un jeton d’actualisation donné.
• api.refreshToken.setIdleExpiresAt(idle) vous permet de définir une nouvelle date d’expiration liée au délai d’inactivité pour un jeton d’actualisation donné.

Vous pouvez utiliser ces méthodes pour personnaliser dynamiquement la durée de vie du jeton d’actualisation et les politiques d’inactivité en fonction des éléments suivants :

• l’organisation d’un utilisateur
• la connexion Auth0 d’un utilisateur
• l’appartenance à un groupe d’un utilisateur donné ou son profil
• l’évaluation des risques
• tout autre critère dynamique disponible lors de l’exécution de l’Action

Les méthodes 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 dans le cadre d’un flux d’échange de jeton d’actualisation.

Les méthodes api.refreshToken.setExpiresAt(absolute) et api.refreshToken.setIdleExpiresAt(idle) convertissent les jetons d’actualisation sans expiration en jetons d’actualisation avec expiration, en utilisant comme valeurs maximales les paramètres par défaut de l’expiration des jetons d’actualisation.

La méthode api.refreshToken.setIdleExpiresAt(idle) définit le délai d’inactivité des jetons d’actualisation. Si la méthode n’est pas appelée à chaque échange réussi, le délai d’inactivité sera remplacé par les paramètres de durée de vie du jeton d’actualisation de l’application.

​

Limitations

• Les jetons d’actualisation émis le 21-09-2023 ou après cette date (le 22-02-2024 pour les tenants de la région US-3) contiennent la propriété d’ID 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 d’API post-login api.refreshToken.revoke(reason) ne contiendront pas l’information event.refresh_token.device.

• Les jetons d’actualisation sans expiration ou 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’expiration absolus et d’inactivité ne peuvent pas être définis au-delà des paramètres de jeton d’actualisation de l’application définis dans les expirations des jetons d’actualisation. Si vous essayez de définir une date qui dépasse les paramètres d’expiration, les méthodes d’API mettront à jour la valeur jusqu’aux expirations des jetons d’actualisation et consigneront un événement d’avertissement (w) dans les journaux du tenant.

• api.refreshToken.setExpiresAt() et api.refreshToken.setIdleExpiresAt() ne peuvent que réduire leur durée de vie respective à partir des valeurs actuelles. Elles ne peuvent ni la prolonger ni l’augmenter.

​

Cas d’utilisation : Révoquer un jeton d’actualisation

Vous pouvez utiliser Actions pour configurer des détections de risque et révoquer des jetons d’actualisation à l’aide de la méthode api.refreshToken.revoke(reason) et des objets d’événement.

​

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

Vous pouvez utiliser l’objet assessments d’Adaptive MFA pour déterminer si un utilisateur se connecte à partir d’un emplacement indiquant un ImpossibleTravel, puis révoquer le jeton d’actualisation actuel associé à la transaction.

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

  // S'il s'agit d'un déplacement impossible et que c'est un échange de refresh token
  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 est effectuée au début de l’Action pour s’assurer que event.authentication.ImpossibleTravel.code est égal à la propriété impossible_travel_from_last_login. Si la valeur est true, l’Action appelle api.refreshToken.revoke() pour :

• Rejeter la transaction
• Révoquer le jeton d’actualisation
• Retourner une réponse d’erreur 403 access_denied
• Émettre l’erreur « Jeton d’actualisation révoqué en raison d’un déplacement impossible »

​

Révoquer des jetons d’actualisation en raison d’une liaison à l’adresse IP

Si vous utilisez les propriétés de l’objet post-login event.refresh_token.device.initial_ip et event.request.ip pour vous assurer qu’une transaction de jeton d’actualisation demeure associée à la même adresse IP pendant toute sa durée. Dans ce scénario, tout changement d’adresse IP est considéré comme un risque, et un nouveau jeton d’actualisation est requis.

exports.onExecutePostLogin = async (event, api) => {
  const refreshTokenInitialIp = event.refresh_token?.device?.initial_ip;
  const requestCurrentIp = event.request.ip;

  // s'il existe un jeton d'actualisation et que l'IP change
  if (
    refreshTokenInitialIp &&
    requestCurrentIp &&
    refreshTokenInitialIp != requestCurrentIp
  ) {
    api.refreshToken.revoke("Invalid IP change");
  }
};

Dans cet exemple, une vérification est effectuée au début de l’Action pour suivre les adresses IP à l’aide des 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 true, l’Action appelle api.refreshToken.revoke() pour :

• Rejeter la transaction
• Révoquer le jeton d’actualisation
• Retourner une réponse d’erreur 403 access_denied
• Émettre l’erreur « Invalid IP change »

Autrement, pour une Action moins restrictive, vous pouvez suivre les propriétés event.request.asn et event.refresh_token.device.initial_asn pour surveiller les changements d’ASN plutôt que les changements d’adresse IP.

​

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

Vous pouvez utiliser Actions pour personnaliser la durée de vie du jeton d’actualisation et ses dates d’expiration liées à l’inactivité. Plus précisément, vous pouvez configurer les dates d’expiration absolue et d’inactivité du jeton d’actualisation pour une transaction donnée à l’aide des méthodes post-login api.refreshToken.setExpiresAt(absolute) et api.refreshToken.setIdleExpiresAt(idle).

​

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

Vous pouvez utiliser une action Post Login pour définir la durée de vie d’un jeton d’actualisation par organisation. L’exemple ci-dessous utilise les métadonnées refresh_token_timeout de l’organisation pour définir la date d’expiration du jeton d’actualisation.

exports.onExecutePostLogin = async (event, api) => {
  // Métadonnées du délai d'expiration du jeton d'actualisation (en millisecondes) configurées dans les organisations
  const organization_refresh_token_lifetime =
    event.organization?.metadata?.refresh_token_timeout;

  if (organization_refresh_token_lifetime) {
    // Le jeton d'actualisation existe déjà
    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 {
      // Le jeton d'actualisation n'existe pas encore (p. ex., le jeton est en cours d'émission)
      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, si un délai d’expiration absolu particulier est défini pour une Organization, l’Action définit le délai d’expiration absolu du jeton d’actualisation de façon à ce qu’il soit égal à :

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

​

Personnaliser le délai d’inactivité du jeton d’actualisation selon le rôle d’appartenance

Vous pouvez utiliser une action Post Login pour définir le délai d’inactivité d’un jeton d’actualisation à l’aide de l’application et des métadonnées utilisateur. L’exemple ci-dessous utilise les rôles dans les métadonnées utilisateur pour déterminer le rôle d’appartenance de l’utilisateur, et les métadonnées de l’application pour définir le délai d’inactivité attendu du jeton d’actualisation.

exports.onExecutePostLogin = async (event, api) => {
  // les administrateurs sont configurés avec un délai d'inactivité plus court pour les jetons d’actualisation, dans les métadonnées de l'application
  const max_idle_lifetime =
    event.client.metadata?.admin_refresh_token_idle_timeout;

  // Vérifier l'attribut roles des métadonnées d'application de l'utilisateur pour déterminer s'il s'agit d'un administrateur.
  const isAdmin = event.user?.app_metadata?.roles?.find(
    (role) => role === "admin",
  );

  // Si l'application a un délai d'inactivité spécifique défini, définir le délai d'expiration
  if (max_idle_lifetime && isAdmin) {
    const current_time = new Date().getTime();

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

Dans cet exemple, si un délai d’inactivité précis est défini pour l’Application et que l’utilisateur est un Admin, l’Action définit le délai d’inactivité du jeton d’actualisation pour qu’il soit égal à current_time plus refresh_token_idle_timeout. Notez que nous modifions le délai d’expiration à la fois pour les nouveaux jetons émis et pour les jetons existants lors d’un échange de jeton d’actualisation.