> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Auth0のリフレッシュトークンのメタデータを設定する方法を説明します

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

<Warning>
  リフレッシュトークンのメタデータは現在、Enterpriseのお客様のみを対象に早期アクセスで提供されています。この機能を使用すると、Oktaの[Master Subscription Agreement](https://www.okta.com/legal)に記載されている該当するFree Trialの条件に同意したものとみなされます。Auth0の製品リリースサイクルの詳細については、[Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages)を参照してください。
</Warning>

リフレッシュトークンのメタデータを設定するには、Auth0の[Post-Login Action](/ja/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger)と[Management API](https://auth0.com/docs/api/management/v2)を使用できます。

<div id="auth0-post-login-actions">
  ## Auth0 Post-Login Actions
</div>

[post-login Action](/ja/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) では、`api.refreshToken` オブジェクトを使用して、リフレッシュトークンのメタデータに対する CRUD 操作を実行できます。これにより、ユーザー固有またはコンテキスト固有のロジックに基づいて、リフレッシュトークンのメタデータを管理できます。

<div id="retrieve-existing-refresh-token-metadata">
  ### 既存のリフレッシュトークンのメタデータを取得する
</div>

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

```javascript lines theme={null}
const deviceName = event.refresh_token?.metadata?.deviceName;
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `event.refresh_token.metadata` オブジェクトには、次の場所で設定されたメタデータが含まれます。

  * 同じフロー内の先行する Actions
  * リフレッシュトークン交換中にリフレッシュトークンが再利用された場合は、以前のトランザクション
</Callout>

<div id="add-or-update-existing-metadata">
  ### 既存のメタデータを追加または更新する
</div>

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

```javascript lines theme={null}
api.refreshToken.setMetadata("deviceName", "Auth0's iPhone");
```

変更は、後続のActionsの `event.refresh_token` オブジェクトですぐに利用できます。

<div id="delete-refresh-token-metadata">
  ### リフレッシュトークンのメタデータを削除する
</div>

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

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

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

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

* [Event object](/ja/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): リフレッシュトークンの Event object とそのプロパティについて説明します。
* [API object](/ja/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): リフレッシュトークンの API object とそのメソッドについて説明します。

<div id="auth0-management-api">
  ## Auth0 Management API
</div>

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

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `/api/v2/refresh-tokens/{id}` エンドポイントを呼び出すには、`update:refresh_tokens` スコープを持つ [Management API アクセストークン](/ja/docs/secure/tokens/access-tokens) が必要です。
</Callout>

<div id="retrieve-existing-refresh-token-metadata">
  ### 既存のリフレッシュトークンのメタデータを取得する
</div>

[`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/get-refresh-token) エンドポイントに `GET` リクエストを送信します。

```bash lines theme={null}
GET /api/v2/refresh-tokens/{id}
```

<div id="add-or-update-existing-refresh-token-metadata">
  ### 既存のリフレッシュトークンのメタデータを追加または更新する
</div>

[`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/patch-refresh-token) エンドポイントに `PATCH` リクエストを送信します。

```bash lines theme={null}
PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

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

<div id="delete-refresh-token-metadata">
  ### リフレッシュトークンのメタデータを削除する
</div>

空のメタデータオブジェクトを指定して、[`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/patch-refresh-token) エンドポイントに `PATCH` リクエストを実行します。

```bash lines theme={null}
PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {}
}
```

<div id="use-case-store-and-consume-organization-context">
  ## ユースケース: 組織コンテキストを保存して利用する
</div>

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

<div id="set-metadata-at-initial-authentication">
  ### 初回認証時にメタデータを設定する
</div>

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

```javascript lines theme={null}
/**
 * Post-Login Action
 * 初回認証時にリフレッシュトークンのメタデータへ組織コンテキストを追加します。
 * このメタデータは、以降のリフレッシュトークン交換時に利用可能になります。
 */
exports.onExecutePostLogin = async (event, api) => {
  // トランザクションが組織を対象とする場合のみ処理を続行する
  if (!event.organization) return;

  // 値は短い文字列のみにする（リフレッシュトークンのメタデータには文字列が必要）
  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);
};
```

<div id="consume-metadata-during-refresh-token-exchange">
  ### リフレッシュトークン交換時にメタデータを利用する
</div>

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

```javascript lines theme={null}
/**
 * Post-Login Action
 * トークン交換時にリフレッシュトークンのメタデータから組織コンテキストを取得します。
 * 元の認証コンテキストに基づいてポリシーを適用したり、クレームを追加したりする際に使用します。
 */
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}`);
    
    // 例: 元の組織コンテキストに基づいてカスタムクレームを追加します
    api.accessToken.setCustomClaim("org_id", orgId);
  }
};
```

<div id="retrieve-via-management-api">
  ### Management API 経由で取得
</div>

[/api/v2/refresh-tokens/{id}](https://auth0.com/docs/api/management/v2/refresh-tokens/get-refresh-token) エンドポイントを使用して、リフレッシュトークンのメタデータを取得することもできます。

```bash lines theme={null}
GET /api/v2/refresh-tokens/{id}
```

レスポンス例:

```json lines theme={null}
{
  "refresh_token_metadata": {
    "org_id": "org_abc123",
    "org_slug": "acme",
    "org_name": "Acme Corp"
  }
}
```

<div id="use-case-track-and-validate-device-information">
  ## ユースケース: デバイス情報の追跡と検証
</div>

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

<div id="set-device-information-at-initial-authentication">
  ### 初回認証時にデバイス情報を設定する
</div>

```javascript lines theme={null}
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");
};
```

<div id="validate-device-information-during-refresh-token-exchange">
  ### リフレッシュトークンの交換時にデバイス情報を検証する
</div>

```javascript lines theme={null}
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);
  }
};
```

<div id="error-handling">
  ## エラー処理
</div>

リフレッシュトークンのメタデータに関するログイベントは、[Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs) に移動して確認するか、[Management API logs](/ja/docs/api/management/v2/logs/get-logs) エンドポイントを使用して取得できます。

* Actions を使用してリフレッシュトークンのメタデータを追加または更新する際にエラーが発生すると、認証トランザクションは失敗し、エラーがコールバック URL に返されます。

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

```json lines theme={null}
{
  "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` エラーと、それに対応するメッセージを返します。

```json lines theme={null}
{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}
```

<div id="learn-more">
  ## 詳しくはこちら
</div>

* [リフレッシュトークンのメタデータ](/ja/docs/secure/tokens/refresh-tokens/refresh-token-metadata)
* [Actions を使用するリフレッシュトークン](/ja/docs/secure/tokens/refresh-tokens/manage-refresh-tokens-actions)
* [リフレッシュトークン](/ja/docs/secure/tokens/refresh-tokens)
* [Post-Login Event オブジェクト](/ja/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object)
* [Post-Login API オブジェクト](/ja/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)