Passer au contenu principal
L’utilisation des jetons d’actualisation avec des 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. 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.
  • 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 : En savoir plus sur l’objet et les propriétés d’événement de jeton d’actualisation.
  • Objet API  : 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 (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 révocation du journal

L’opération de révocation ajoute l’événement de journal suivant dans vos journaux du locataire : 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
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.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) 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.

​
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. 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 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 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 de l’authentification multifacteur () 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. 
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. 
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 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. 
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 et de l’utilisateur. 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. 
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.
⌘I