Cas d’utilisation des métadonnées de jeton d’actualisation et des métadonnées de session

Les métadonnées de jeton d’actualisation et les métadonnées de session vous permettent, ensemble, de créer et de stocker des données qui persistent tout au long du cycle de vie de la session Auth0 d’un utilisateur. Cet article présente des exemples pour les cas d’utilisation suivants :

Pour en savoir plus, consultez A guide to Auth0 Session and Refresh Token Metadata.

Les métadonnées de session Auth0 ne constituent pas un stockage de données sécurisé et ne doivent pas servir à stocker des renseignements sensibles. Cela comprend les secrets et les PII à risque élevé, comme les numéros d’assurance sociale ou de carte de crédit. Il est fortement recommandé aux clients d’Auth0 d’évaluer les données stockées dans les métadonnées et de ne conserver que celles qui sont nécessaires à des fins de gestion des identités et des accès. Pour en savoir plus, consultez Conformité d’Auth0 au Règlement général sur la protection des données.

Créer des revendications personnalisées persistantes

Les métadonnées du jeton d’actualisation et les métadonnées de session vous permettent de créer des revendications personnalisées persistantes afin d’enrichir les informations contenues dans les jetons ID et d’accès. Grâce aux revendications personnalisées persistantes, vous pouvez accéder à des données propres à l’application, par exemple :

Les rôles des utilisateurs
Les Permissions
Les ID de tenant
Et d’autres attributs nécessaires à l’autorisation et à la personnalisation lors des échanges de jeton d’actualisation.

Configurez un déclencheur d’Action post-login post-login d’Action pour créer des revendications personnalisées persistantes et les attribuer aux métadonnées du jeton d’actualisation à l’aide de l’objet api.refreshToken.setMetadata().

custom claim Action example

/**
 * @param {Event} event - Détails sur l'utilisateur et la transaction d'authentification.
 * @param {PostLoginActionAPI} api - Interface pour modifier la transaction d'authentification complétée.
 */
exports.onExecutePostLogin = async (event, api) => {
  let customClaimValue1;
  let customClaimValue2;

  // --- Fonction auxiliaire pour simuler le calcul des revendications personnalisées ---
  // Dans un scénario réel, cette fonction effectuerait une logique complexe
  // basée sur les données utilisateur, des API externes, etc.
  const calculateCustomClaims = (user) => {
    // Après avoir effectué vos calculs, retourner
    return { claim1: value1, claim2: value2 };
  };

  // --- Déterminer s'il s'agit d'une connexion initiale ou d'un échange de jeton d’actualisation ---
  // Si event.request.body.grant_type n'est pas 'refresh_token', il s'agit probablement d'une connexion interactive initiale
  const isRefreshTokenGrant = event.request.body.grant_type === 'refresh_token';

  if (!isRefreshTokenGrant) {
    // --- Connexion initiale (p. ex., mot de passe, Social, MFA-OOB) ---
    // Calculer les valeurs des revendications personnalisées
    const calculatedClaims = calculateCustomClaims(event.user);
    customClaimValue1 = calculatedClaims.claim1;
    customClaimValue2 = calculatedClaims.claim2;

    // Enregistrer ces valeurs calculées dans les métadonnées du jeton d’actualisation pour la persistance
    // Vérifier si un jeton d’actualisation sera émis et, le cas échéant, ajouter les métadonnées
if (event.transaction.requested_scopes.indexOf('offline_access') > -1) {
api.refreshToken.setMetadata('customClaim1', customClaimValue1);
api.refreshToken.setMetadata('customClaim2', customClaimValue2);
}

  } else {
    // --- Échange de jeton d’actualisation ---
    // Utiliser les valeurs des revendications personnalisées provenant des métadonnées du jeton d’actualisation
    customClaimValue1 = event.refresh_token?.metadata?.customClaim1;
    customClaimValue2 = event.refresh_token?.metadata?.customClaim2;

  } 
  // --- Enfin, ajouter les valeurs déterminées comme revendications personnalisées aux jetons ---
  api.idToken.setCustomClaim('custom_claim_1', customClaimValue1);
  api.accessToken.setCustomClaim('custom_claim_1', customClaimValue1);

  api.idToken.setCustomClaim('custom_claim_2', customClaimValue2);
  api.accessToken.setCustomClaim('custom_claim_2', customClaimValue2);
};

Lors d’un échange de jeton d’actualisation, un déclencheur d’Action post-login post-login ultérieur peut accéder à ces revendications personnalisées à l’aide de l’objet event.refresh_token.metadata et les appliquer aux nouveaux jetons d’actualisation émis au moyen des objets api.idToken.setCustomClaim() et api.accessToken.setCustomClaim().

Une même Action post-login peut gérer différents scénarios de grant_type à l’aide de l’objet event.request.body.grant_type pour gérer l’enregistrement des revendications. L’objet event.refresh_token est accessible en lecture seule pendant les échanges de jetons d’actualisation.

Créer un ID de session unique

Les métadonnées du jeton d’actualisation et les métadonnées de session vous permettent de créer un ID de session unique afin de mettre en place un identifiant de session persistant qui est conservé pendant toute la durée de la session d’un utilisateur, y compris lors de la rotation des jetons d’actualisation. À l’aide d’ID de session uniques, vous pouvez :

Consigner avec précision la session d’un utilisateur à des fins de débogage et d’audit.
Fournir aux applications un mécanisme pour suivre l’état interne de la session.
Permettre aux API d’offrir une journalisation granulaire, une limitation du taux de requêtes et des décisions d’autorisation contextuelles.
Offrir une expérience UX cohérente sur plusieurs cycles de vie des jetons.

Configurez un déclencheur d’Action post-login post-login pour créer un ID de session unique et l’attribuer à la session de l’utilisateur à l’aide des objets api.session.setMetadata() et api.refreshToken.setMetadata(). Ajoutez l’ID de session unique comme revendication personnalisée aux jetons d’ID et d’accès à l’aide des objets api.idToken.setCustomClaim() et api.accessToken.setCustomClaim().

unique session ID Action example

/**
 * @param {Event} event - Détails sur l'utilisateur et la transaction d'authentification.
 * @param {PostLoginActionAPI} api - Interface pour modifier la transaction d'authentification complétée.
 */
exports.onExecutePostLogin = async (event, api) => {
  let sessionId;

  // 1) Vérifier si une clé de métadonnées de session appelée 'ses_id' existe déjà.
  if (event.session && event.session.metadata && event.session.metadata.ses_id) {
    sessionId = event.session.metadata.ses_id;
  }
  // Si introuvable dans les métadonnées de session, vérifier si elle est disponible dans les métadonnées du jeton d'actualisation.
  // Ceci est particulièrement pertinent pour les flux ROPG où il n'y avait pas de session réelle.
  else if (event.refresh_token && event.refresh_token.metadata && event.refresh_token.metadata.ses_id) {
    sessionId = event.refreshToken.metadata.ses_id;
  }

  // Si un 'ses_id' n'existe pas, en générer un nouveau 
  if (!sessionId) {
    sessionId = generateSesId(); // Votre propre fonction utilitaire pour générer un UUID

    // Stocker le 'ses_id' nouvellement généré dans les métadonnées de session
    // Ne faire ceci que si une session est réellement émise/présente dans l'événement. 
    if (event.session) {
      api.session.setMetadata('ses_id', sessionId);
    }

    // Stocker le 'ses_id' dans les métadonnées du jeton d'actualisation.
    // Ne faire ceci que si un jeton d'actualisation est réellement émis/présent dans l'événement.
    if (event.refresh_token) {
      api.refreshToken.setMetadata('ses_id', sessionId);
    }
  } else {
    // S'assurer également que les métadonnées du jeton d'actualisation contiennent le ses_id, au cas où il serait manquant
    // ou mis à jour ailleurs. Cela peut se produire si l'utilisateur n'a pas demandé offline_access au départ, mais l'a ajouté par la suite.
    if (event.refresh_token && event.refresh_token.metadata && !event.refresh_token.metadata.ses_id) {
        api.refreshToken.setMetadata('ses_id', sessionId);
    }
  }


  // 2) Ajouter ce 'ses_id' en tant que revendication personnalisée au jeton d'identité et au jeton d'accès.
  api.idToken.setCustomClaim('ses_id', sessionId);
  api.accessToken.setCustomClaim('ses_id', sessionId);
};

Pendant un échange de jeton d’actualisation, un déclencheur d’Action post-login ultérieur peut accéder à ces revendications personnalisées au moyen de l’objet event.refresh_token.metadata et les appliquer aux jetons d’actualisation nouvellement émis à l’aide des objets api.idToken.setCustomClaim() et api.accessToken.setCustomClaim().

Créer un identifiant de tenant

Les métadonnées du jeton d’actualisation et les métadonnées de session vous permettent de créer un identifiant de tenant persistant pour gérer des applications multitenant, où une seule instance d’une application dessert plusieurs organisations clientes, et qui est conservé pendant toute la durée de la session de l’utilisateur. À l’aide d’un identifiant de tenant persistant, vous pouvez :

Ajouter un contrôle d’accès dynamique pour appliquer facilement des permissions propres au tenant dans vos applications et API
Créer une expérience utilisateur adaptée afin d’offrir du contenu et des fonctionnalités pertinents selon le contexte de tenant actuel de l’utilisateur
Simplifier la logique multitenant en centralisant l’identification du tenant et sa propagation dans Auth0
Renforcer la sécurité en évitant l’exposition accidentelle de données entre tenants grâce à un contexte de tenant cohérent dans tous les jetons
Améliorer l’évolutivité en réduisant le recours à des requêtes répétées vers la base de données ou à une logique complexe pour déterminer le contexte de tenant à chaque appel d’API ou actualisation de jeton

Configurez un déclencheur d’Action post-login post-login pour identifier le tenant actif de l’utilisateur, soit en interrogeant l’application pour obtenir une valeur ext-tenantId fournie pendant la requête d’authentification, soit en déduisant le tenant à l’aide de la géolocalisation, soit en demandant à l’utilisateur de sélectionner le tenant souhaité. Une fois le tenant identifié, attribuez la valeur de l’identifiant de tenant à la session de l’utilisateur à l’aide des objets api.session.setMetadata() et api.refreshToken.setMetadata(), puis ajoutez-la comme revendication personnalisée aux jetons d’identité et d’accès à l’aide des objets api.idToken.setCustomClaim() et api.accessToken.setCustomClaim().

tenant identifier Action example

/** 
 * @param {Event} event - Détails sur l'utilisateur et la transaction d'authentification.
 * @param {PostLoginActionAPI} api - Interface pour modifier la transaction d'authentification complétée.
 */
exports.onExecutePostLogin = async (event, api) => {
  let tenantId;

  // 1) Vérifier si une clé de métadonnées de session appelée 'tenant_id' existe déjà.
  if (event.session && event.session.metadata && event.session.metadata.tenant_id) {
    tenantId = event.session.metadata.tenant_id;
  }
  // Si introuvable dans les métadonnées de session, vérifier si elle est disponible dans les métadonnées du jeton d’actualisation.
  // Ceci est particulièrement pertinent pour les flows ROPG où il n'y avait pas de session réelle.
  else if (event.refresh_token && event.refresh_token.metadata && event.refresh_token.metadata.tenant_id) {
    tenantId = event.refreshToken.metadata.tenant_id;
  }

  // Si le 'tenant_id' n'est pas encore connu, on le détermine 
  if (!tenantId) {
    // On suppose que tenant_id est arrivé en tant que paramètre ext-
    tenantId = event.request.query['ext-tenantId'];

    // Il pourrait aussi provenir de la géolocalisation dans l'événement  
    // ou de formulaires. Si vous utilisez des formulaires, vous ouvririez le formulaire
    // maintenant et exécuteriez le reste du code dans la 
    // fonction onContinuePostLogin
  
    // Stocker le 'tenant_id' nouvellement déterminé dans les métadonnées de session 
    // Ne faire ceci que si une session est réellement émise/présente dans l'événement. 
    if (event.session) {
      api.session.setMetadata('tenant_id', tenantId);
    }

    // Stocker le 'tenant_id' dans les métadonnées du jeton d’actualisation.
    // Ne faire ceci que si un jeton d’actualisation est réellement émis/présent dans l'événement.
    if (event.refresh_token) {
      api.refreshToken.setMetadata('tenant_id', tenantId);
    }
  } else {
    // S'assurer également que les métadonnées du jeton d’actualisation contiennent le tenant_id, au cas où il serait absent
    // ou mis à jour ailleurs. Cela peut arriver si l'utilisateur n'a pas demandé offline_access au départ mais l'a ajouté par la suite.
    if (event.refresh_token && event.refresh_token.metadata && !event.refresh_token.metadata.tenant_id) {
        api.refreshToken.setMetadata('tenant_id', tenantId);
    }
  }


  // 2) Ajouter ce 'tenant_id' en tant que revendication personnalisée à la fois au jeton d’identité et au jeton d'accès.
  api.idToken.setCustomClaim('tenant_id', tenantId);
  api.accessToken.setCustomClaim('tenant_id', tenantId);
};

Lors d’un échange de jeton d’actualisation, une Action post-login subséquente peut accéder à ces revendications personnalisées au moyen de l’objet event.refresh_token.metadata, puis les appliquer aux jetons d’actualisation nouvellement émis à l’aide des objets api.idToken.setCustomClaim() et api.accessToken.setCustomClaim().

Gérer les données transitoires provenant des fournisseurs d’identité en amont (IDPs)

Les métadonnées du jeton d’actualisation et les métadonnées de session vous permettent de gérer les données transitoires et contextuelles provenant des IDPs en amont tout au long de la session d’un utilisateur, sans les stocker de façon permanente dans son profil Auth0. En utilisant des données transitoires, vous pouvez :

Garder les profils utilisateur épurés en évitant de stocker des données transitoires ou propres à la session
Gagner en flexibilité en prenant en charge des besoins en données variés provenant de différents IDPs, sans imposer de modifications au schéma ni alourdir les profils utilisateur persistants
Améliorer la conformité en facilitant le respect des politiques de protection des données et de conservation, en ne stockant les données transitoires que pendant la durée nécessaire
Réduire la charge de développement en simplifiant la gestion des données transitoires des IDPs, puisque Auth0 Actions et les métadonnées gèrent le cycle de vie des données

Configurez un déclencheur d’Action post-login pour repérer les données de profil utilisateur contenues dans les objets event.request, event.user et event.context. Déterminez quelles données sont transitoires ou contextuelles et attribuez-les à la session de l’utilisateur à l’aide des objets api.session.setMetadata() et api.refreshToken.setMetadata(), puis ajoutez les données transitoires comme revendication personnalisée aux jetons ID et d’accès à l’aide des objets api.idToken.setCustomClaim() et api.accessToken.setCustomClaim().

transient data Action example

/**
 * @param {Event} event - Détails sur l'utilisateur et la transaction d'authentification.
 * @param {PostLoginActionAPI} api - Interface pour modifier la transaction d'authentification complétée.
 */
exports.onExecutePostLogin = async (event, api) => {
  let deviceIdentifier;
  let groups;

  // Exemple : Extraire les informations de l'appareil à partir des en-têtes de requête ou du contexte
  // Ceci est illustratif ; la prise d'empreinte numérique réelle de l'appareil pourrait être plus complexe
  if (event.request.user_agent) {
    deviceIdentifier = event.request.user_agent;
  } else {
    deviceIdentifier = 'unknown';
  }

  // Exemple : Extraire les informations du fournisseur d'identité à partir du contexte d'une connexion en amont
  // Cela dépend fortement du fournisseur d'identité en amont et de la façon dont il transmet les informations.
  // En supposant une revendication personnalisée ou une variable de contexte d'une connexion SAML/OIDC, p. ex. « groups »
  if (event.user.groups) {
    groups = event.user.groups;
  } else {
    groups = [];
  }

  // Stocker les données transitoires dans les métadonnées de session
  api.session.setMetadata('deviceIdentifier', deviceIdentifier);
  api.session.setMetadata('groups', groups);

  // Stocker les données transitoires dans les métadonnées du jeton d'actualisation pour les conserver entre les actualisations
  if (event.refreshToken) {
    api.refreshToken.setMetadata('deviceIdentifier', deviceIdentifier);
    api.refreshToken.setMetadata('groups', groups);
  }

  // Au besoin, ajouter ces éléments comme revendications aux jetons d'accès pour les API
  // L'utilisation d'espaces de noms personnalisés est une bonne pratique pour les revendications propres à l'application.
  api.accessToken.setCustomClaim('https://myapp.example.com/device_id', deviceIdentifier);
  api.accessToken.setCustomClaim('https://myapp.example.com/groups', groups);

  // Exemple : Si le fournisseur d'identité en amont fournit un « niveau d'assurance » pour cet événement d'authentification
  if (event.transaction && event.transaction.acr_values) { // acr : Référence de classe de contexte d'authentification
      api.session.setMetadata('authLevel', event.transaction.acr_values);
      if (event.refreshToken) {
        api.refreshToken.setMetadata('authLevel', event.transaction.acr_values);
      }
      api.accessToken.setCustomClaim('https://myapp.example.com/auth_level', event.transaction.acr_values);
  }
};

Lors d’un échange de jeton d’actualisation, un déclencheur d’Action post-login ultérieur peut accéder à ces revendications personnalisées au moyen de l’objet event.refresh_token.metadata et les appliquer aux nouveaux jetons d’actualisation émis au moyen de l’objet api.accessToken.setCustomClaim().

Renforcer la sécurité et la détection de fraude

Les métadonnées du jeton d’actualisation et les métadonnées de session vous permettent de mettre en place une sécurité adaptative en suivant et en comparant les données contextuelles tout au long de la session d’un utilisateur, y compris les rotations de jetons d’actualisation et les requêtes d’authentification silencieuse. En mettant en place une sécurité adaptative, vous pouvez :

Mettre en place une détection proactive des menaces en repérant et en traitant automatiquement les changements suspects dans les données de contexte de l’utilisateur, ce qui réduit le risque de détournement de session et d’accès non autorisé.
Réduire les irritants pour les utilisateurs légitimes en ne demandant la MFA ou une vérification supplémentaire que lorsqu’une véritable anomalie est détectée, ce qui améliore l’expérience utilisateur par rapport à une exigence systématique de MFA.

Configurez un déclencheur d’Action post-login pour repérer les données contextuelles de l’utilisateur, qui peuvent inclure l’empreinte de l’appareil, l’emplacement géographique, les attributs réseau et les attributs comportementaux. Stockez ces données contextuelles dans la session de l’utilisateur à des fins de comparaison, à l’aide de l’objet api.session.setMetadata().

security detection Action example

/**
 * @param {Event} event - Détails sur l'utilisateur et la transaction d'authentification.
 * @param {PostLoginActionAPI} api - Interface pour modifier la transaction d'authentification complétée.
 */
exports.onExecutePostLogin = async (event, api) => {
  // --- Capturer les données contextuelles actuelles ---
  // Utiliser les empreintes ja3/ja4 fournies par Auth0
  const {ja3, ja4} = event.security_context;
  // Ajouter ja3/ja4 aux métadonnées si elles n'y sont pas encore
  // (la première connexion n'a pas de métadonnées définies)
  if (event.session && !event.session.metadata) {
    api.session.setMetadata('ja3', ja3);
    api.session.setMetadata('ja4', ja4);
  } else {
    // Comparer l'empreinte stockée avec l'empreinte entrante 
    if(ja3 != event.session?.metadata?.ja3 || ja4 != event.session?.metadata?.ja4) {
      // Si les empreintes diffèrent, déclencher un challenge MFA
      api.authentication.challengeWith(
        { type: 'otp'}, 
        { additionalFactors: [
          { type: 'push-notification'}, { type: 'phone' }
        ]}
      );
    }    
  }
};

Lors d’un échange de jeton d’actualisation ou d’une authentification silencieuse, un déclencheur post-login Action ultérieur peut appliquer une évaluation du risque et des réponses adaptatives.

Accéder aux métadonnées avec la Management API

Vous pouvez utiliser les endpoints GET de l’Auth0 Management API /api/v2/refresh-tokens/{id} et /api/v2/sessions/{id} pour récupérer les données stockées dans les métadonnées d’un jeton d’actualisation ou d’une session. La réponse comprend le champ metadata, qui contient les données stockées :

{
  "id": "object_id",
  "metadata": {
    "deviceIdentifier": "deviceIdentifier"
  }
}

En savoir plus

Jetons d’actualisation : En savoir plus sur les jetons d’actualisation.
Sessions : En savoir plus sur les sessions.
Objets Event des Actions : En savoir plus sur l’objet Event post-login et ses propriétés.
Objet API des Actions : En savoir plus sur l’objet API post-login et ses méthodes.

Protect Your Application

Call APIs On User's Behalf

Protect Your Tenant

Compliance

Cas d’utilisation des métadonnées de jeton d’actualisation et des métadonnées de session

Créer des revendications personnalisées persistantes

Créer un ID de session unique

Créer un identifiant de tenant

Gérer les données transitoires provenant des fournisseurs d’identité en amont (IDPs)

Renforcer la sécurité et la détection de fraude

Accéder aux métadonnées avec la Management API

En savoir plus

​Créer des revendications personnalisées persistantes

​Créer un ID de session unique

​Créer un identifiant de tenant

​Gérer les données transitoires provenant des fournisseurs d’identité en amont (IDPs)

​Renforcer la sécurité et la détection de fraude

​Accéder aux métadonnées avec la Management API

​En savoir plus

Créer des revendications personnalisées persistantes

Créer un ID de session unique

Créer un identifiant de tenant

Gérer les données transitoires provenant des fournisseurs d’identité en amont (IDPs)

Renforcer la sécurité et la détection de fraude

Accéder aux métadonnées avec la Management API

En savoir plus