リフレッシュトークンメタデータを設定する

Actions または Management API を使用してAuth0のリフレッシュトークンメタデータを設定する方法を説明します。

リフレッシュトークンメタデータを設定するには、Auth0 の Post-Login Action と Management API を使用できます。

​

Auth0 Post-Login Actions

post-login Action を使用すると、api.refreshToken オブジェクトを通じて、リフレッシュトークンメタデータに対する CRUD 操作を管理できます。これにより、ユーザーやコンテキストに応じたロジックに基づいて、リフレッシュトークンメタデータを管理できます。

​

既存のリフレッシュトークンメタデータを取得する

リフレッシュトークンメタデータを読み取るには、event.refresh_token.metadata オブジェクトを使用します。

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

event.refresh_token.metadata オブジェクトには、以下で設定されたメタデータが含まれます。

• 同じフロー内のそれ以前の Actions
• リフレッシュトークン交換中にリフレッシュトークンが再利用された場合の、以前のトランザクション

​

既存のメタデータを追加または更新

api.refreshToken.setMetadata() メソッドを使用して、リフレッシュトークンのメタデータを設定または更新できます。

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

変更内容は、後続のActionsで event.refresh_token オブジェクトにすぐ反映されます。

​

リフレッシュトークンのメタデータを削除する

リフレッシュトークンのメタデータを削除するには、次の api.refreshToken メソッドを使用します。

• api.refreshToken.deleteMetadata("key") は、指定したリフレッシュトークンのメタデータを削除します

• api.refreshToken.evictMetadata() は、リフレッシュトークンのメタデータをすべて削除します

これらのオブジェクトの詳細については、次を参照してください。

• Event object: リフレッシュトークンの Event オブジェクトとそのプロパティについて説明します。
• API object: リフレッシュトークンの API オブジェクトとそのメソッドについて説明します。

​

Auth0 Management API

Management API を使用して、リフレッシュトークンのメタデータに対する CRUD (作成、置換、更新、削除) リクエストを実行できます。

/api/v2/refresh-tokens/{id} エンドポイントを呼び出すには、update:refresh_tokens スコープを持つ Management API アクセストークン が必要です。

​

既存のリフレッシュトークンメタデータを取得する

/api/v2/refresh-tokens/{id} エンドポイントに GET リクエストを送信します。

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

​

既存のリフレッシュトークンメタデータを追加または更新する

/api/v2/refresh-tokens/{id} エンドポイントに対して PATCH リクエストを実行します:

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

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

​

リフレッシュトークンのメタデータを削除する

空のメタデータオブジェクトを指定して、/api/v2/refresh-tokens/{id} エンドポイントに PATCH リクエストを送信します:

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

{
  "refresh_token_metadata": {}
}

​

ユースケース: 組織コンテキストを保存して利用する

初回認証時にリフレッシュトークンメタデータを使用して 組織コンテキストを保存し、後でリフレッシュトークン交換時に利用できます。これは、監査、分析、失効パイプラインなどの下流システムで役立ちます。

​

初回認証時にメタデータを設定

初回ログイン時に、リフレッシュトークンのメタデータに組織コンテキストを設定します。

/**
 * Post-Login Action
 * 初回認証時にリフレッシュトークンメタデータにorganizationのコンテキストを追加します。
 * このメタデータは、以降のリフレッシュトークン交換時に利用できます。
 */
exports.onExecutePostLogin = async (event, api) => {
  // transactionがOrganizationを対象とする場合のみ処理を続行する
  if (!event.organization) return;

  // 値は短くStringのみにする（リフレッシュトークンメタデータにはStringが必要）
  const orgId = String(event.organization.id || "");
  const orgSlug = String(event.organization.name || "");
  const orgDisplay = String(event.organization.display_name || orgSlug);

  // メタデータを設定する - リフレッシュトークンと共に保存される
  api.refreshToken.setMetadata("org_id", orgId);
  api.refreshToken.setMetadata("org_slug", orgSlug);
  api.refreshToken.setMetadata("org_name", orgDisplay);
};

​

リフレッシュトークン交換時にメタデータを利用する

リフレッシュトークン交換の際は、event.refresh_token オブジェクトが存在するため、以前に保存したメタデータを読み取ることができます。

/**
 * Post-Login Action
 * トークン交換時にリフレッシュトークンのメタデータから組織コンテキストを取得します。
 * 元の認証コンテキストに基づいてポリシーを適用したり、claimを追加したりする際に使用します。
 */
exports.onExecutePostLogin = async (event, api) => {
  // リフレッシュトークン交換かどうかを確認します（event.refresh_token が存在する場合）
  if (!event.refresh_token) return;

  // 初回認証時に保存された組織コンテキストを読み取ります
  const orgId = event.refresh_token.metadata?.org_id;
  const orgSlug = event.refresh_token.metadata?.org_slug;

  if (orgId) {
    // 条件付きロジックに組織コンテキストを使用します
    console.log(`Refresh token exchange for organization: ${orgSlug}`);
    
    // 例: 元の組織コンテキストに基づいてカスタムclaimを追加します
    api.accessToken.setCustomClaim("org_id", orgId);
  }
};

​

Management API で取得

/api/v2/refresh-tokens/ エンドポイントを使用して、リフレッシュトークンメタデータを取得することもできます。

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

レスポンス例：

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

​

ユースケース: デバイス情報の追跡と検証

セキュリティ対策として、初回認証時にリフレッシュトークンメタデータを使ってデバイス情報を取得し、以降のリフレッシュトークン交換時にその情報を検証できます。

​

初回認証時にデバイス情報を設定する

exports.onExecutePostLogin = async (event, api) => {
  // リフレッシュトークン交換でない場合のみデバイス情報を設定する
  // （初回認証時のみ）
  if (event.refresh_token) return;

  // デバイス情報をリフレッシュトークンメタデータに保存する
  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");
};

​

リフレッシュトークン交換時のデバイス情報の検証

exports.onExecutePostLogin = async (event, api) => {
  // リフレッシュトークン交換の場合のみ検証する
  if (!event.refresh_token) return;

  // 元のデバイス情報を読み取る
  const initialCountry = event.refresh_token.metadata?.initial_country;
  const currentCountry = event.request?.geoip?.country_code;

  // 例: 国の変更を検出してアクションを実行する
  if (initialCountry && currentCountry && initialCountry !== currentCountry) {
    console.log(`Country changed from ${initialCountry} to ${currentCountry}`);
    
    // オプション1: 不審なアクティビティが検出された場合にリフレッシュトークンを失効させる
    // api.refreshToken.revoke("Suspicious country change detected");
    
    // オプション2: 変更を追跡するためにメタデータを更新する
    api.refreshToken.setMetadata("country_changed", "true");
    api.refreshToken.setMetadata("last_country", currentCountry);
  }
};

​

エラー処理

Auth0 Dashboard > Monitoring > Logs に移動してリフレッシュトークンメタデータのログイベントを確認するか、Management API logs エンドポイントを使用してログを取得できます。

• Actions でリフレッシュトークンメタデータの追加または更新中にエラーが発生すると、認証トランザクションは失敗し、callback URL にエラーが返されます。

失敗を示す f イベントコードが、対応するエラーとともに記録されます。

{
  "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"
}

• Auth0 Management API を使用してリフレッシュトークンメタデータを管理する際にエラーが発生した場合、API は対応するメッセージとともに HTTP status: 400 エラーを返します:

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

​

詳しくはこちら

• リフレッシュトークンのメタデータ
• Actions でのリフレッシュトークン
• リフレッシュトークン
• Post-Login イベントオブジェクト
• Post-Login API オブジェクト