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

> Auth0 セッションメタデータの設定方法について説明します

# セッションメタデータの設定

<Warning>
  Session Metadata は現在、Enterprise 顧客のみを対象とした Early Access 機能です。この機能を使用することで、Okta の [Master Subscription Agreement](https://www.okta.com/legal) に定められた該当の無料トライアル条件に同意したものとみなされます。Auth0 の製品リリースサイクルの詳細については、[Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages) を参照してください。
</Warning>

セッションメタデータを設定するには、Auth0 の [Post-Login Action](/docs/ja-JP/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) と [Management API](https://auth0.com/docs/api/management/v2) を使用できます。また、[OpenID Connect Back-Channel Logout](/docs/ja-JP/authenticate/login/logout/back-channel-logout) トークンに含めることもできます。

## Auth0 Management API

Management API を使用して、セッションメタデータの CRUD（作成、置換、更新、削除）操作を行うことができます。

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

<div id="retrieve-existing-session-metadata">
  ### 既存のセッションメタデータを取得する
</div>

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

```bash lines theme={null}
GET /api/v2/sessions/{id}
```

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

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

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

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

<div id="delete-session-metadata">
  ### セッションメタデータを削除する
</div>

セッションメタデータを削除するには、`PATCH` リクエストを [`/api/v2/sessions/{id}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) エンドポイントに送信します。

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

{
  "session_metadata": {}
}
```

<div id="auth0-post-login-actions">
  ## Auth0 ポストログイン Actions
</div>

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

<div id="retrieve-existing-session-metadata">
  ### 既存のセッションメタデータを取得する
</div>

`event.session.metadata?.deviceName` オブジェクトを使用して、`deviceName` メタデータを読み取ります。

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

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `event.session.metadata` オブジェクトには、次のいずれかで設定されたメタデータが含まれます。
  同じフロー内の以前の Actions
  セッションが再利用されている場合の過去のトランザクション
</Callout>

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

`api.session.setMetadata()` メソッドを使用して、セッション メタデータを更新します。

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

変更は、以降の Actions で利用される `event.session` オブジェクトにすぐに反映されます。

<div id="delete-session-metadata">
  ### セッションメタデータを削除する
</div>

セッションメタデータを削除するには、次の `api.session` オブジェクトを使用します。

* `api.session.deleteMetadata("key")` は、指定されたセッションメタデータを削除します
* `api.session.evictMetadata()` は、すべてのセッションメタデータを削除します

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

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

<div id="oidc-back-channel-logout">
  ## OIDC バックチャネル ログアウト
</div>

Auth0 [Dashboard](/docs/ja-JP/get-started/auth0-overview/dashboard) または [Management API](https://auth0.com/docs/api/management/v2) を使用して、`logout_token` にセッションメタデータを含めるように設定できます。

<div id="auth0-dashboard">
  ### Auth0 Dashboard
</div>

セッションメタデータを含む OIDC Back-Channel Logout トークンを設定するには、次の手順に従います。

1. [Dashboard > Applications](https://manage.auth0.com/#/applications) に移動し、対象のアプリケーションを選択します。

2. **Settings** タブを選択します。

3. **OpenID Connect Back-Channel Logout > Back-Channel Logout URL** の項目で、`logout_token` を受信するアプリケーションのログアウト URI を追加します。

4. **Back-Channel Logout Initiators** を次のいずれかに設定します。

   * **Selected initiators only** または

   * **All supported initiators**

5. **Include Session Metadata** をオンに切り替えます。

6. **Save Changes** を選択します。

設定が完了すると、`logout_token` には保存されているすべてのセッションメタデータが含まれます。

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

[`/api/v2/clients/{id}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) エンドポイントを使用して、アプリケーションを更新し、`logout_token` にセッションメタデータを含めることができます。

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

```json lines theme={null}
"oidc_backchannel_logout": {
  "backchannel_logout_initiators": {
    "mode": "all"
  },
  "backchannel_logout_urls": [
    "https://httpdump.app/inspect/9bccf574-e55f-4b2e-9822-f37372588fc1"
  ],
  "backchannel_logout_session_metadata": {
    "include": true
  }
}
```

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

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

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

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

```json lines theme={null}
{
  "error": "access_denied",
  "error_description": "セッションメタデータの設定に失敗しました: 無効なメタデータ: メタデータキーには文字、数字、アンダースコア、ハイフンのみ使用できます",
  "state": "my-custom-state"
}
```

* Auth0 Management API を使用してセッションメタデータを管理している際に失敗が発生すると、API は `HTTP status: 400` エラーとそれに対応するメッセージを返します。

```json lines theme={null}
{
  "statusCode": 400,
  "message": "メタデータは25エントリを超えることはできません。各キーと値は255文字以下である必要があります。"
}
```