Passer au contenu principal
L’utilisation de avec Actions vous permet de configurer des capacités de détection et de réponse aux risques après l’authentification afin de protéger vos applications et vos utilisateurs contre les jetons d’actualisation compromis. Vous pouvez également personnaliser dynamiquement l’expiration des jetons d’actualisation. À cette fin, les Actions post-login offrent 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 basés sur le navigateur, session_id. Cet objet est alimenté 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 :
  • objet d’événement : Découvrez l’objet d’événement du jeton d’actualisation et ses propriétés.
  • objet API : Découvrez l’objet API du jeton d’actualisation et ses méthodes.

​
Révoquer les 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 refuser la transaction en cours et consigne un événement de révocation de jeton d’actualisation dans les journaux du locataire (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 journalisation de révocation

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, l’entrée de journal inclura une référence à la 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 des jetons 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 d’un utilisateur à un groupe ou son profil
  • l’évaluation du risque
  • 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 pendant 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 Refresh Token expirations.La méthode api.refreshToken.setIdleExpiresAt(idle) définit le délai d’expiration lié à l’inactivité des jetons d’actualisation. Si elle n’est pas appelée à chaque échange réussi, ce délai d’expiration sera remplacé par les paramètres de l’application pour la durée de vie du jeton d’actualisation.

​
Limitations

  • Les jetons d’actualisation émis à compter du 21-09-2023 (du 22-02-2024 pour les locataires de la région US-3) contiennent la propriété d’identifiant de session (session_id) avec la valeur correspondante. Les jetons d’actualisation émis avant cette date contiennent cette propriété avec la valeur null.
  • Les jetons d’actualisation émis avant la mise en disponibilité de la méthode d’API post-login api.refreshToken.revoke(reason) ne contiennent pas l’information event.refresh_token.device.
  • Les jetons d’actualisation sans expiration ou les jetons d’actualisation qui n’ont pas été échangés ne contiennent pas la propriété event.refresh_token.last_exchanged_at.
  • Pour des raisons de sécurité, les délais d’expiration d’inactivité et les délais d’expiration absolus ne peuvent pas être définis au-delà des paramètres d’expiration des jetons d’actualisation de l’application définis dans l’expiration des jetons d’actualisation. Si vous tentez de définir une valeur supérieure aux paramètres d’expiration, les méthodes d’API effectueront la mise à jour jusqu’aux valeurs de l’expiration des jetons d’actualisation et consigneront un événement d’avertissement (w) dans les journaux du locataire.
  • api.refreshToken.setExpiresAt() et api.refreshToken.setIdleExpiresAt() peuvent uniquement raccourcir leur durée de validité respective par rapport aux valeurs actuelles. Elles ne peuvent pas la prolonger ni l’augmenter.

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

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

​
Révoquer des jetons d’actualisation en cas d’ImpossibleTravel

Vous pouvez utiliser l’objet assessments pour déterminer si un utilisateur se connecte depuis un emplacement suggérant 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 qu'il s'agit d'un échange de jeton d'actualisation
  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 :
  • Refuser la transaction
  • Révoquer le jeton d’actualisation
  • Renvoyer une erreur access_denied avec une réponse 403
  • Retourner l’erreur « Jeton d’actualisation révoqué en raison d’un déplacement impossible »

​
Révoquer les jetons d’actualisation en raison de la 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 reste liée à la même adresse IP pendant toute sa durée de vie. Dans ce scénario, tout changement d’adresse IP est considéré comme un risque et exige un nouveau jeton d’actualisation. 
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 assurer le suivi des 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 :
  • Refuser la transaction
  • Révoquer le jeton d’actualisation
  • Renvoyer une erreur access_denied avec une réponse 403
  • Produire l’erreur « Invalid IP change »
Autrement, pour une Action moins restrictive, vous pouvez assurer le suivi des propriétés event.request.asn et event.refresh_token.device.initial_asn afin de 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 les Actions pour personnaliser la durée de vie du jeton d’actualisation ainsi que 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 précise à 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 une durée de vie du jeton d’actualisation pour chaque 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 précis est défini pour une Organisation, l’Action définit le délai d’expiration absolu du jeton d’actualisation pour 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’expiration d’inactivité du jeton d’actualisation en fonction du rôle du membre

Vous pouvez utiliser une Action Post-Login pour définir un délai d’expiration d’inactivité du jeton d’actualisation à l’aide de l’application et des métadonnées utilisateur. L’exemple ci-dessous utilise les rôles des métadonnées utilisateur pour définir le rôle du membre, ainsi que les métadonnées de l’application pour définir le délai d’expiration d’inactivité attendu pour le jeton d’actualisation. 
exports.onExecutePostLogin = async (event, api) => {
  // les administrateurs sont configurés avec un délai d'expiration 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 dans les 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'expiration d'inactivité spécifique défini, appliquer 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é avant expiration précis est 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 avant expiration comme étant égal à current_time plus refresh_token_idle_timeout. Notez que nous modifions ce délai d’expiration à la fois pour les jetons nouvellement émis et pour les jetons existants lors de l’échange du jeton d’actualisation.