> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Découvrez des exemples de mise en œuvre de cas d’utilisation pour les métadonnées de jeton d’actualisation et les métadonnées de session.
# 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](/docs/fr-ca/secure/tokens/refresh-tokens/refresh-token-metadata) et les [métadonnées de session](/docs/fr-ca/manage-users/sessions/session-metadata) 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 :
* [Créer des claims personnalisés persistants](/docs/fr-ca/secure/tokens/refresh-tokens/refresh-token-metadata/use-cases#create-persistent-custom-claims)
* [Créer un ID de session unique](/docs/fr-ca/secure/tokens/refresh-tokens/refresh-token-metadata/use-cases#create-a-unique-session-id)
* [Propager les identifiants de tenant](/docs/fr-ca/secure/tokens/refresh-tokens/refresh-token-metadata/use-cases#create-a-tenant-identifier)
* [Gérer les données transitoires provenant des fournisseurs d’identité en amont (IDP)](/docs/fr-ca/secure/tokens/refresh-tokens/refresh-token-metadata/use-cases#manage-transient-data-from-upstream-identity-providers-idps)
* [Renforcer la sécurité et la détection de fraude](/docs/fr-ca/secure/tokens/refresh-tokens/refresh-token-metadata/use-cases#enhance-security-and-fraud-detection)
Pour en savoir plus, consultez [A guide to Auth0 Session and Refresh Token Metadata](https://auth0.com/blog/auth0-session-refresh-token-metadata-guide).
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](/docs/fr-ca/secure/data-privacy-and-compliance/gdpr).
## 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](/docs/fr-ca/secure/tokens#id-tokens) et d’[accès](/docs/fr-ca/secure/tokens/access-tokens).
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](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#login-/-post-login) d’[Action](/docs/fr-ca/customize/actions) 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()`.
```javascript custom claim Action example expandable theme={null}
/**
* @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](/docs/fr-ca/secure/tokens/refresh-tokens/use-refresh-tokens#use-refresh-tokens), 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](docs/secure/tokens/refresh-tokens/refresh-token-rotation).
À 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](/docs/fr-ca/get-started/apis#apis) 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](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#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()`.
```javascript unique session ID Action example expandable theme={null}
/**
* @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](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#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()`.
```javascript tenant identifier Action example expandable theme={null}
/**
* @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](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#login-/-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()`.
```javascript transient data Action example expandable theme={null}
/**
* @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](/docs/fr-ca/authenticate/login/configure-silent-authentication).
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](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#login-/-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()`.
```javascript security detection Action example expandable theme={null}
/**
* @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}](/docs/fr-ca/api/management/v2/refresh-tokens/get-refresh-token) et [/api/v2/sessions/\{id}](/docs/fr-ca/api/management/v2/sessions/get-session) 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 :
```json theme={null}
{
"id": "object_id",
"metadata": {
"deviceIdentifier": "deviceIdentifier"
}
}
```
## En savoir plus
* [Jetons d’actualisation](/docs/fr-ca/secure/tokens/refresh-tokens) : En savoir plus sur les jetons d’actualisation.
* [Sessions](/docs/fr-ca/manage-users/sessions) : En savoir plus sur les sessions.
* [Objets Event des Actions](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object) : En savoir plus sur l’objet Event `post-login` et ses propriétés.
* [Objet API des Actions](/docs/fr-ca/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object) : En savoir plus sur l’objet API `post-login` et ses méthodes.