カスタム ID トークン
はじめに
ID トークン は、 OpenID Connect (OIDC) プロトコルで定義された特別な種類のトークンです。これは、ユーザーが正常に認証 (Authentication) された後、認可 (Authorization) サーバー（Logto）によって発行されるアイデンティティの証明であり、認証 (Authentication) されたユーザーのアイデンティティに関するクレーム (Claims) を運びます。
アクセス トークン が保護されたリソースへのアクセスに使用されるのとは異なり、ID トークンは認証 (Authentication) 済みユーザーのアイデンティティをクライアントアプリケーションに伝えるために特化されています。これらは JSON Web Token (JWT) であり、認証 (Authentication) イベントと認証 (Authentication) 済みユーザーに関するクレーム (Claims) を含みます。
ID トークンのクレーム (Claims) の仕組み
Logto では、ID トークンのクレーム (Claims) は 2 つのカテゴリに分かれています：
- 標準 OIDC クレーム (Claims)：OIDC 仕様で定義されており、これらのクレーム (Claims) は認証 (Authentication) 時にリクエストされたスコープ (Scopes) によって完全に決まります。
- 拡張クレーム (Claims)：Logto によって拡張され、追加のアイデンティティ情報を運ぶクレーム (Claims) であり、二重条件モデル（スコープ (Scope) + トグル）で制御されます。
標準 OIDC クレーム (Claims)
標準クレーム (Claims) は OIDC 仕様によって完全に管理されています。ID トークンに含まれるかどうかは、認証 (Authentication) 時にアプリケーションがリクエストするスコープ (Scopes) のみに依存します。Logto では、個々の標準クレーム (Claims) を無効化したり選択的に除外したりするオプションは提供していません。
以下の表は、標準スコープ (Scopes) とそれに対応するクレーム (Claims) のマッピングを示しています：
| スコープ (Scope) | クレーム (Claims) |
|---|---|
openid | sub |
profile | name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at |
email | email, email_verified |
phone | phone_number, phone_number_verified |
address | address |
たとえば、アプリケーションが openid profile email スコープ (Scopes) をリクエストした場合、ID トークンには openid、profile、email スコープ (Scopes) からすべてのクレーム (Claims) が含まれます。
拡張クレーム (Claims)
標準 OIDC クレーム (Claims) に加えて、Logto は Logto エコシステム固有のアイデンティティ情報を運ぶ追加のクレーム (Claims) を拡張しています。これらの拡張クレーム (Claims) は、ID トークンに含めるために 二重条件モデル に従います：
- スコープ (Scope) 条件：アプリケーションが認証 (Authentication) 時に対応するスコープ (Scope) をリクエストする必要があります。
- コンソールのトグル：管理者が Logto コンソールでそのクレーム (Claim) を ID トークンに含める設定を有効にする必要があります。
両方の条件が同時に満たされる必要があります。スコープ (Scope) はプロトコル層のアクセス宣言、トグルはプロダクト層の公開制御として機能し、それぞれの役割は明確で代替できません。
利用可能な拡張スコープ (Scopes) とクレーム (Claims)
| スコープ (Scope) | クレーム (Claims) | 説明 | デフォルトで含まれる |
|---|---|---|---|
custom_data | custom_data | ユーザーオブジェクトに保存されたカスタムデータ | |
identities | identities, sso_identities | ユーザーの連携済みソーシャルおよび SSO アイデンティティ | |
roles | roles | ユーザーに割り当てられたロール (Roles) | ✅ |
urn:logto:scope:organizations | organizations | ユーザーの組織 (Organizations) ID | ✅ |
urn:logto:scope:organizations | organization_data | ユーザーの組織 (Organizations) データ | |
urn:logto:scope:organization_roles | organization_roles | ユーザーの組織 (Organizations) ロール (Roles) 割り当て | ✅ |
Logto コンソールでの設定方法
拡張クレーム (Claims) を ID トークンに有効化するには：
- コンソール > カスタム JWT に移動します。
- ID トークンに含めたいクレーム (Claims) のトグルをオンにします。
- アプリケーションが認証 (Authentication) 時に対応するスコープ (Scopes) をリクエストしていることを確認します。
関連リソース
カスタム アクセス トークンOpenID Connect Core - ID トークン