Configurer Correlation ID

Découvrez comment utiliser Correlation ID pour suivre les événements dans le processus d’authentification.

Prérequis

Pour utiliser correlation_id, vous devez avoir :

• Auth0 Universal Login configuré : l’ID de corrélation est disponible dans les flux Universal Login.
• Une application capable de générer des ID uniques : votre application doit pouvoir générer des UUID ou des ID de transaction. (Exemple : txn_12345_xyz, des ID de session ou des ID de commande)

Si correlation_id n’est pas disponible dans vos requêtes d’autorisation, il se peut que cette fonctionnalité ne soit pas activée dans votre tenant.

Auth0 vous permet de suivre les transactions d’authentification à l’aide d’un ID de corrélation. Cette capacité de suivi peut réduire le temps de réponse du soutien et vous offrir une traçabilité dans plusieurs systèmes en aval des événements d’authentification.

Le paramètre correlation_id ajoute à l’URL d’autorisation un identifiant unique généré par votre application. Cet ID est automatiquement enregistré, ce qui vous permet de suivre et de filtrer les événements dans les journaux du tenant Auth0.

L’ID de corrélation est conservé dans les événements suivants :

• Inscription
• Connexion
• Inscription et vérifications de Multi-Factor Authentication (MFA)
• Réinitialisation du mot de passe

Vous pouvez utiliser l’ID de corrélation avec Universal Login, Universal Login Page Templates, modèles de courriel, modèles SMS, pages d’erreur personnalisées, Flows et Auth0 Actions.

Configurer l’ID de corrélation

Les valeurs de correlation_id doivent respecter les contraintes suivantes :

• Caractères autorisés : caractères alphanumériques et caractères spéciaux correspondant à /^[-\w.*~@+/:]{1,64}$/.
• Longueur maximale : 64 caractères
• Ne doit pas contenir de renseignements personnels permettant d’identifier une personne (PII)

Transmettez le paramètre correlation_id dans l’objet authorizationParams pour ajouter l’ID unique à l’URL d’autorisation, comme dans l’exemple suivant :

const { loginWithRedirect } = useAuth0();
loginWithRedirect({
  authorizationParams: {
    // Ajoute "&correlation_id=..." à l'URL à des fins de suivi
    correlation_id: "YOUR_CORRELATION_ID"
  }
});

Universal Login

Tous les flux Universal Login prennent en charge correlation_id. Une fois la valeur de l’ID de corrélation transmise au point de terminaison /authorize, les événements d’authentification génèrent des logs du tenant contenant l’ID de corrélation, que vous pouvez utiliser à des fins de suivi. Utilisez le SDK de la Management API pour récupérer et filtrer les événements récents afin d’isoler une transaction précise.

L’exemple de requête suivant utilise le SDK de la Management API pour récupérer les événements d’authentification les plus récents. Il les filtre ensuite localement afin d’isoler un événement précis :

// 1. Envoyer une requête à la Management API (syntaxe SDK v5)
const { data: logs } = await management.logs.list({
  per_page: 100,
  sort: 'date:-1'
});
// 2. Filtrer le tableau côté client pour trouver votre ID
const transactionEvents = logs.filter(log =>
  log.references?.correlation_id === "YOUR_CORRELATION_ID"
);
console.log(`Found ${transactionEvents.length} events for this transaction.`);

Modèle de page de connexion

Si vous personnalisez votre expérience de connexion avec les Universal Login Page Templates, ajoutez le correlation_id à votre modèle pour suivre les événements d’authentification liés à une connexion personnalisée.

L’exemple suivant montre correlationId: "{{correlation_id}}" ajouté à {%- auth0:widget -%}.

<!-- Exemple : Injection de l'ID dans un script côté client -->
<!-- Remarque : {{ }} est une syntaxe de gabarit Liquid évaluée côté serveur par Auth0, et non des espaces réservés de documentation -->
<script>
  window.addEventListener("load", function () {
    const loginContext = {
      application: "{{application.name}}",
      // Accéder à correlation_id directement via la syntaxe Liquid
      correlationId: "{{correlation_id}}"
    };

    console.log("Tracking Context:", loginContext);
    // Vous pouvez maintenant transmettre loginContext.correlationId à votre outil d'analyse
  });
</script>

Modèles de courriel

Vous pouvez inclure correlation_id dans Modèles de courriel pour faciliter le suivi des événements d’authentification qui déclenchent des notifications par courriel, comme les réinitialisations de mot de passe ou les courriels de vérification.

L’exemple suivant montre {{correlation_id}} ajouté au corps d’un modèle de courriel.

<p>If you did not initiate this request, please ignore this email.</p>
<p>Tracking reference: {{correlation_id}}</p>

Modèles SMS

Vous pouvez inclure correlation_id dans les modèles SMS pour retracer les événements d’authentification qui déclenchent des notifications par SMS, comme les demandes de vérification MFA.

L’exemple suivant montre {{correlation_id}} ajouté à un modèle SMS.

Your verification code is: {{code}}. Ref: {{correlation_id}}

Pages d’erreur personnalisées

Vous pouvez inclure correlation_id dans les Pages d’erreur personnalisées pour afficher directement la référence de suivi sur les pages d’erreur, ce qui permet aux utilisateurs de signaler plus facilement les problèmes et à votre équipe de soutien de retracer la transaction en échec.

L’exemple suivant montre {{correlation_id}} ajouté à un modèle de page d’erreur personnalisée.

<h1>{{error | escape}}: {{error_description | escape}}</h1>
<p>Si vous avez besoin de soutien, mentionnez cet ID : {{correlation_id}}</p>

Auth0 Actions

Avec les déclencheurs d’inscription et de connexion d’Auth0 Actions, utilisez l’objet event pour consigner des événements dans des services tiers ou les transmettre à des API en aval.

Les objets event suivants prennent en charge correlation_id :

• Pre-user-registration
• Post-login
• Post-challenge
• Post-change-password
• fournisseur de courriel personnalisé
• fournisseur de téléphone personnalisé
• MFA Notification send-phone-message
• Échange d’identifiants

L’exemple de Post-Login Action montre comment extraire le correlation_id de l’objet event.

exports.onExecutePostLogin = async (event, api) => {
  console.log('PostLogin Action Start');
  const correlation_id = event.transaction?.correlation_id;
  // Vérifier si correlation_id existe
  if (correlation_id) {
    console.log(`Correlation ID found: ${correlation_id}`);
  } else {
    console.log('No correlation_id found in transaction');
  }
  console.log('PostLogin Action End');
};

Forms

Vous pouvez utiliser l’ID de corrélation dans Forms et Flows. Forms vous permet de personnaliser l’inscription et la connexion à l’aide de la logique personnalisée que vous créez dans Flows. Pour utiliser l’ID de corrélation dans Forms et Flows, utilisez l’objet context dans l’éditeur Flows pour ajouter à votre logique la variable d’événements corrélés {{context.transaction.correlation_id}}. Pour en savoir plus, consultez Variables et fonctions utilitaires.