Correlation ID を設定する

Correlation ID を使用して、認証フロー内のイベントを追跡する方法を学びます。

前提条件

correlation_id を使用するには、以下を満たしている必要があります。

• Auth0 Universal Login が設定されていること: Correlation ID は Universal Login フローで利用できます。
• 一意の ID を生成できるアプリケーション: アプリケーションで UUID やトランザクション ID を生成できる必要があります。 (例: txn_12345_xyz、セッション ID、注文 ID)

認可リクエストで correlation_id を利用できない場合は、お使いのテナントでこの機能が有効になっていない可能性があります。

Auth0 では、Correlation ID を使用して認証トランザクションを追跡できます。この追跡機能により、サポート対応時間を短縮し、認証イベント以降も複数のシステムにまたがって追跡できるようになります。

correlation_id パラメーターは、アプリケーションで生成した一意の識別子を認可 URL に追加します。この ID は自動的に記録されるため、Auth0 テナントログ でイベントを追跡したり、絞り込んだりできます。

Correlation ID は、次のイベント全体を通して保持されます。

• サインアップ
• ログイン
• 多要素認証 (MFA) の登録とチャレンジ
• パスワードのリセット

Correlation ID は、Universal Login、Universal Login Page Templates、メールテンプレート、SMS テンプレート、カスタムエラーページ、Flows、Auth0 Actions で使用できます。

correlation ID を設定する

correlation_id の値には、次の制限があります。

• 使用できる文字: 英数字、および /^[-\w.*~@+/:]{1,64}$/ に一致する特殊文字
• 最大長: 64 文字
• 含めてはならない情報: 個人を特定できる情報 (PII)

次の例のように、authorizationParams オブジェクトに correlation_id パラメーターを渡すと、一意の ID が認可 URL に追加されます。

const { loginWithRedirect } = useAuth0();
loginWithRedirect({
  authorizationParams: {
    // トラッキング用にURLへ "&correlation_id=..." を追加します
    correlation_id: "YOUR_CORRELATION_ID"
  }
});

Universal Login

すべての Universal Login フローで correlation_id がサポートされています。相関 ID の値を /authorize endpoint に渡すと、authentication イベントにより、追跡に使用できる相関 ID を含む tenant logs が生成されます。Management API SDK を使用して最近のイベントを取得し、絞り込むことで、特定のトランザクションを切り分けることができます。

次のサンプル呼び出しでは、Management API SDK を使用して最新の authentication イベントを取得し、その後ローカルで絞り込んで特定のイベントを切り分けます。

// 1. Management API を呼び出す（SDK v5 構文）
const { data: logs } = await management.logs.list({
  per_page: 100,
  sort: 'date:-1'
});
// 2. クライアント側で配列をフィルタリングして対象の ID を見つける
const transactionEvents = logs.filter(log =>
  log.references?.correlation_id === "YOUR_CORRELATION_ID"
);
console.log(`Found ${transactionEvents.length} events for this transaction.`);

ログインページテンプレート

Universal Login Page Templates を使用してログイン画面をカスタマイズする場合は、カスタムログインの認証イベントを追跡できるよう、テンプレートに correlation_id を追加します。

次のサンプルは、{%- auth0:widget -%} に correlationId: "{{correlation_id}}" を追加した例です。

<!-- 例: IDをクライアントサイドのスクリプトに注入する -->
<!-- 注意: {{ }} はAuth0がサーバーサイドで評価するLiquidテンプレート構文であり、ドキュメントのプレースホルダーではありません -->
<script>
  window.addEventListener("load", function () {
    const loginContext = {
      application: "{{application.name}}",
      // Liquid構文でcorrelation_idに直接アクセスする
      correlationId: "{{correlation_id}}"
    };

    console.log("Tracking Context:", loginContext);
    // loginContext.correlationIdを分析ツールに渡せます
  });
</script>

メールテンプレート

パスワードのリセットや確認用メールの送信など、メール通知をトリガーする認証イベントを追跡しやすくするために、メールテンプレート に correlation_id を含めることができます。

以下のサンプルは、メールテンプレートの本文に {{correlation_id}} を追加した例です。

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

SMS テンプレート

SMS テンプレートには、MFA チャレンジなどの SMS 通知をトリガーする認証イベントを追跡するために、correlation_id を含めることができます。

次のサンプルは、SMS テンプレートに {{correlation_id}} を追加した例です。

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

カスタムエラーページ

カスタムエラーページ に correlation_id を含めることで、追跡用の参照 ID をエラーページに直接表示できます。これにより、ユーザーは問題を報告しやすくなり、サポートチームも失敗したトランザクションを追跡しやすくなります。

次のサンプルは、カスタムエラーページのテンプレートに {{correlation_id}} を追加した例です。

<h1>{{error | escape}}: {{error_description | escape}}</h1>
<p>サポートが必要な場合は、このIDを参照してください: {{correlation_id}}</p>

Auth0 Actions

Auth0 Actions の Signup and Login Triggers では、event オブジェクトを使用してイベントをサードパーティのサービスに記録したり、後続の API に渡したりできます。

以下のイベントオブジェクトは correlation_id をサポートしています。

• Pre-user-registration
• Post-login
• Post-challenge
• Post-change-password
• Custom email provider
• Custom phone provider
• MFA Notification send-phone-message
• Credential Exchange

サンプルの Post-Login Action では、event オブジェクトから correlation_id を取得する方法を示しています。

exports.onExecutePostLogin = async (event, api) => {
  console.log('PostLogin Action Start');
  const correlation_id = event.transaction?.correlation_id;
  // correlation_idが存在するか確認
  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 と Flows では、Correlation ID を使用できます。Forms では、Flows で作成したカスタムロジックを使って、サインアップやログインをカスタマイズできます。Forms と Flows で Correlation ID を使用するには、Flows エディタの context オブジェクトを使用して、相関イベント変数 {{context.transaction.correlation_id}} をロジックに追加します。詳しくは、Variables and helper functions をご覧ください。