Configurer les métadonnées du jeton d’actualisation

Découvrez comment configurer les métadonnées du jeton d’actualisation d’Auth0 à l’aide d’Actions ou de la Management API.

Pour configurer les métadonnées du jeton d’actualisation, vous pouvez utiliser une Action post-login d’Auth0 et la Management API.

​

Actions post-login d’Auth0

Vous pouvez gérer les opérations CRUD des métadonnées du jeton d’actualisation à l’aide des objets api.refreshToken dans une Action post-login. Cela vous permet de gérer les métadonnées du jeton d’actualisation selon une logique propre à l’utilisateur ou au contexte.

​

Récupérer les métadonnées existantes associées au jeton d’actualisation

Utilisez l’objet event.refresh_token.metadata pour lire les métadonnées du jeton d’actualisation :

const deviceName = event.refresh_token?.metadata?.deviceName;

L’objet event.refresh_token.metadata contient les métadonnées définies dans :

• les Actions précédentes du même flux
• des transactions antérieures, si le jeton d’actualisation a été réutilisé lors d’un échange de jeton d’actualisation

​

Ajouter ou mettre à jour les métadonnées existantes

Utilisez la méthode api.refreshToken.setMetadata() pour définir ou mettre à jour les métadonnées du jeton d’actualisation :

api.refreshToken.setMetadata("deviceName", "Auth0's iPhone");

Les modifications sont immédiatement disponibles dans l’objet event.refresh_token lors des Actions suivantes.

​

Supprimer les métadonnées du jeton d’actualisation

Utilisez les méthodes api.refreshToken suivantes pour supprimer les métadonnées du jeton d’actualisation :

• api.refreshToken.deleteMetadata("key") supprime les métadonnées du jeton d’actualisation indiquées

• api.refreshToken.evictMetadata() supprime toutes les métadonnées du jeton d’actualisation

Pour en savoir plus sur ces objets, consultez :

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

​

Auth0 Management API

Vous pouvez gérer les requêtes CRUD (création, remplacement, mise à jour et suppression) associées aux métadonnées du jeton d’actualisation à l’aide de la Management API :

Les requêtes vers le point de terminaison /api/v2/refresh-tokens/{id} nécessitent un jeton d’accès à la Management API avec la portée update:refresh_tokens.

​

Récupérer les métadonnées d’un jeton d’actualisation existant

Effectuez une requête GET au point de terminaison /api/v2/refresh-tokens/{id} :

GET /api/v2/refresh-tokens/{id}

​

Ajouter ou mettre à jour les métadonnées d’un jeton d’actualisation existant

Envoyez une requête PATCH au point de terminaison /api/v2/refresh-tokens/{id} :

PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {
    "my_metadata": "my new metadata"
  }
}

​

Supprimer les métadonnées du jeton d’actualisation

Effectuez une requête PATCH vers le point de terminaison /api/v2/refresh-tokens/{id} avec un objet de métadonnées vide :

PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {}
}

​

Cas d’utilisation : stocker et exploiter le contexte de l’organisation

Vous pouvez utiliser les métadonnées du jeton d’actualisation pour stocker le contexte de l’organisation lors de l’authentification initiale, puis l’exploiter plus tard lors des échanges de jeton d’actualisation. C’est utile pour les systèmes en aval, comme les pipelines d’audit, d’analyse et de révocation.

​

Définir les métadonnées lors de l’authentification initiale

Lors de la connexion initiale, définissez le contexte de l’organisation dans les métadonnées du jeton d’actualisation :

/**
 * Action post-connexion
 * Ajoute le contexte d'organisation aux métadonnées du jeton d'actualisation lors de l'authentification initiale.
 * Ces métadonnées seront disponibles lors des échanges de jetons d'actualisation ultérieurs.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Continuer uniquement si la transaction cible une organisation
  if (!event.organization) return;

  // Garder les valeurs courtes et de type chaîne seulement (les métadonnées du jeton d'actualisation exigent des chaînes)
  const orgId = String(event.organization.id || "");
  const orgSlug = String(event.organization.name || "");
  const orgDisplay = String(event.organization.display_name || orgSlug);

  // Définir les métadonnées - elles seront stockées avec le jeton d'actualisation
  api.refreshToken.setMetadata("org_id", orgId);
  api.refreshToken.setMetadata("org_slug", orgSlug);
  api.refreshToken.setMetadata("org_name", orgDisplay);
};

​

Utiliser les métadonnées lors d’un échange de jeton d’actualisation

Lors d’un échange de jeton d’actualisation, l’objet event.refresh_token existe et vous pouvez lire les métadonnées stockées précédemment :

/**
 * Post-Login Action
 * Consomme le contexte d'organisation à partir des métadonnées du refresh token lors de l'échange de token.
 * Utilisez ceci pour appliquer des politiques ou ajouter des claims selon le contexte d'authentification d'origine.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Vérifier s'il s'agit d'un échange de refresh token (event.refresh_token existe)
  if (!event.refresh_token) return;

  // Lire le contexte d'organisation stocké lors de l'authentification initiale
  const orgId = event.refresh_token.metadata?.org_id;
  const orgSlug = event.refresh_token.metadata?.org_slug;

  if (orgId) {
    // Utiliser le contexte d'organisation pour la logique conditionnelle
    console.log(`Refresh token exchange for organization: ${orgSlug}`);
    
    // Exemple : Ajouter des custom claims selon le contexte d'organisation d'origine
    api.accessToken.setCustomClaim("org_id", orgId);
  }
};

​

Récupérer au moyen de la Management API

Vous pouvez aussi consulter les métadonnées du jeton d’actualisation au moyen du point de terminaison /api/v2/refresh-tokens/ :

GET /api/v2/refresh-tokens/{id}

Exemple de réponse :

{
  "refresh_token_metadata": {
    "org_id": "org_abc123",
    "org_slug": "acme",
    "org_name": "Acme Corp"
  }
}

​

Cas d’utilisation : Suivre et valider les informations sur l’appareil

Vous pouvez utiliser les métadonnées du jeton d’actualisation pour consigner des informations sur l’appareil au moment de l’authentification initiale et les valider lors des échanges subséquents du jeton d’actualisation à des fins de sécurité.

​

Définir les renseignements sur l’appareil lors de l’authentification initiale

exports.onExecutePostLogin = async (event, api) => {
  // Ne définir les informations de l'appareil que si ce n'est PAS un échange de refresh token
  // (c.-à-d., il s'agit de l'authentification initiale)
  if (event.refresh_token) return;

  // Stocker les informations de l'appareil dans les métadonnées du refresh token
  api.refreshToken.setMetadata("initial_ip", event.request?.ip || "unknown");
  api.refreshToken.setMetadata("initial_asn", event.request?.asn?.value || "unknown");
  api.refreshToken.setMetadata("initial_country", event.request?.geoip?.country_code || "unknown");
  api.refreshToken.setMetadata("initial_user_agent", event.request?.user_agent || "unknown");
};

​

Valider les renseignements de l’appareil lors de l’échange du jeton d’actualisation

exports.onExecutePostLogin = async (event, api) => {
  // Valider uniquement s'il s'agit d'un échange de jeton d'actualisation
  if (!event.refresh_token) return;

  // Lire les informations d'appareil d'origine
  const initialCountry = event.refresh_token.metadata?.initial_country;
  const currentCountry = event.request?.geoip?.country_code;

  // Exemple : Détecter un changement de pays et agir en conséquence
  if (initialCountry && currentCountry && initialCountry !== currentCountry) {
    console.log(`Country changed from ${initialCountry} to ${currentCountry}`);
    
    // Option 1 : Révoquer le jeton d'actualisation en cas d'activité suspecte
    // api.refreshToken.revoke("Suspicious country change detected");
    
    // Option 2 : Mettre à jour les métadonnées pour suivre le changement
    api.refreshToken.setMetadata("country_changed", "true");
    api.refreshToken.setMetadata("last_country", currentCountry);
  }
};

​

Gestion des erreurs

Vous pouvez consulter les événements de journal liés aux métadonnées des jetons d’actualisation en accédant à Dashboard > Monitoring > Logs ou récupérer les logs au moyen du point de terminaison Management API logs.

• Si une erreur se produit lors de l’ajout ou de la mise à jour des métadonnées des jetons d’actualisation avec Actions, la transaction d’authentification échoue et une erreur est renvoyée à l’URL de rappel.

Un code d’événement d’échec f est consigné avec l’erreur correspondante :

{
  "error": "access_denied",
  "error_description": "Failed to set refresh token metadata: Invalid metadata: Metadata keys may only include letters, numbers, underscores, or hyphens",
  "state": "my-custom-state"
}

• En cas d’échec lors de la gestion des métadonnées du jeton d’actualisation au moyen de l’Auth0 Management API, l’API renvoie une erreur HTTP status: 400 ainsi que le message correspondant :

{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}

​

En savoir plus

• Métadonnées du jeton d’actualisation
• Jetons d’actualisation avec Actions
• Jetons d’actualisation
• Objet d’événement post-login
• Objet API post-login