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

Découvrez comment configurer les métadonnées du jeton d’actualisation dans Auth0

Les métadonnées du jeton d’actualisation sont actuellement en accès anticipé, uniquement pour les clients Enterprise. En utilisant cette fonctionnalité, vous acceptez les conditions applicables de l’essai gratuit énoncées dans le Master Subscription Agreement d’Okta. Pour en savoir plus sur le cycle de publication des produits d’Auth0, consultez les étapes de publication des produits.

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

​

Actions de post-connexion 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 du jeton d’actualisation

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

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

L’objet event.refresh_token.metadata inclut 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 dans les 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éer, remplacer, mettre à jour, supprimer) pour les métadonnées des jetons d’actualisation à l’aide de la Management API :

Les appels au point de terminaison /api/v2/refresh-tokens/{id} nécessitent un jeton d’accès à la Management API avec le scope update:refresh_tokens.

​

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

Effectuez une requête GET vers le 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 à l’adresse du 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

Envoyez une requête PATCH au 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 et l’exploiter plus tard lors des échanges de jetons d’actualisation. Cela est utile pour les systèmes en aval, comme les pipelines d’audit, d’analytique et de révocation.

​

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

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

/**
 * Action Post-Login
 * 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 ultérieurs de Jeton d'actualisation.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Ne continuer que si la transaction cible une Organisation
  if (!event.organization) return;

  // Garder les valeurs courtes et en chaînes uniquement (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 - celles-ci 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 de l’échange d’un 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 Jeton d'actualisation lors de l'échange de jetons.
 * Utilisez ceci pour appliquer des politiques ou ajouter des claims basés sur le contexte d'authentification d'origine.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Vérifier s'il s'agit d'un échange de Jeton d'actualisation (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 claims personnalisés basés sur le contexte d'organisation d'origine
    api.accessToken.setCustomClaim("org_id", orgId);
  }
};

​

Récupération via la Management API

Vous pouvez également consulter les métadonnées du jeton d’actualisation à l’aide 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 renseignements sur l’appareil

Vous pouvez utiliser les métadonnées du jeton d’actualisation pour consigner les renseignements sur l’appareil lors de l’authentification initiale et les valider lors des échanges ultérieurs de jetons d’actualisation à des fins de sécurité.

​

Définir les informations de 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 jeton d'actualisation
  // (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 jeton d'actualisation
  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 informations sur 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 à Auth0 Dashboard > Monitoring > Logs ou récupérer les journaux à l’aide 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 la Management API d’Auth0, 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 Event Post-Login
• Objet API Post-Login