> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> ### Authlete versions
> Authlete 3.0 is the current version. Unless the user says they use another version, answer for Authlete 3.0 using the 3.x documentation.
> Documentation for Authlete 2.x (pages under `/v2/` and `/ja/v2/`) is for the legacy version. Refer to it only when the user is on Authlete 2.x.
>
> ### Authlete architecture
> Authlete is a backend engine for OAuth 2.0 and OpenID Connect processing. End users and client applications do not call it directly; the service provider's authorization server and API server call Authlete's APIs. Authlete handles protocol processing and token, client, and service management, while the service provider owns the OAuth/OIDC endpoints and user authentication.
> See [Architecture](https://developers.authlete.com/get-started/introduction-to-authlete/architecture.md).
>
> ### Concepts
> If the user is new to Authlete, read these pages first:
> - [Request and Response](https://developers.authlete.com/get-started/concepts/request-and-response.md): Core API requests pass the client's request parameters as-is, and responses return `resultCode`, `action`, and `responseContent`.
> - [Action Handling](https://developers.authlete.com/get-started/concepts/action-handling.md): Branch on `action`, never on `resultCode`, and map each action to the HTTP response your server returns.
> - [Two-Step API Calls](https://developers.authlete.com/get-started/concepts/two-step-api-calls.md): Actions such as `INTERACTION` are completed with a second call (`/auth/authorization/issue` or `/auth/authorization/fail`) linked by a `ticket`.
> - [Management API Overview](https://developers.authlete.com/get-started/concepts/overview.md): The Management API configures services, manages clients, and operates issued tokens, separately from the protocol flows handled by the Core API.
> - [API Authentication](https://developers.authlete.com/get-started/concepts/authentication.md): Authlete APIs use bearer tokens: a Service Access Token (one service) or an Organization Token (the whole organization).
# サブジェクト
> 認可サーバーが Authlete に渡すエンドユーザーの識別子 (subject) について説明します。
## サブジェクトとは
**サブジェクト**は、コードやトークンの発行対象となるエンドユーザー (リソースオーナー) の識別子です。サブジェクトの値は認可サーバーが生成し、`subject` リクエストパラメーターとして Authlete API に渡します。
まず、認可サーバーはユーザー認証後にサブジェクトを Authlete に渡し、Authlete は受け取ったサブジェクトを発行するコードやトークンに紐付けます (図 1)。
```mermaid theme={null}
sequenceDiagram
autonumber
participant U as エンドユーザー
participant AS as 認可サーバー
participant API as Authlete Core API
AS <<->> U: ユーザー認証
AS ->> AS: エンドユーザーを識別し、サブジェクトを特定
AS ->> API: Issue Authorization Response (ticket, subject)
Note over API: サブジェクトをコードとトークンに紐付け
API -->> AS: action=LOCATION, responseContent
```
図 1: ユーザー認証後にサブジェクトを紐付ける例
次に、そのコードと引き換えにトークンを発行する際、Authlete は ID トークンや JWT アクセストークンに含める値としてサブジェクトを返却します (図 2)。
```mermaid theme={null}
sequenceDiagram
autonumber
participant C as クライアント
participant AS as 認可サーバー
participant API as Authlete Core API
C ->> AS: トークンリクエスト
AS ->> API: Process Token Request (トークンリクエストの内容)
Note over API: (OIDC の場合)
ID トークンに含まれる値としてサブジェクトを返却
Note over API: (JWT アクセストークンの場合)
アクセストークンに含まれる値としてサブジェクトを返却
API -->> AS: action=OK, responseContent
AS -->> C: トークンレスポンス
```
図 2: トークンに含めてサブジェクトを返却する例
また、リソースサーバーがアクセストークンをイントロスペクションする際にも、Authlete はアクセストークンに紐付いたサブジェクトを返却します (図 3)。
```mermaid theme={null}
sequenceDiagram
autonumber
participant C as クライアント
participant RS as リソースサーバー
participant API as Authlete Core API
C ->> RS: API リクエスト
RS ->> API: Process Introspection Request (アクセストークンの値)
Note over API: アクセストークンに紐付く値としてサブジェクトを返却
API -->> RS: action=OK, subject
RS -->> C: API レスポンス
```
図 3: トークンの解析結果としてサブジェクトを返却する例
さらに Authlete は、紐付けられているサブジェクトに基づいて、トークン一覧の絞り込みや発行するトークンの制御を行います。
## OAuth/OIDC 仕様との関係
Authlete のサブジェクトは、OAuth/OIDC 仕様の以下の要素の `sub` に相当します。
| `sub` を含む要素 | `sub` の要件 | 関連する仕様 |
| - | - | - |
| ID トークン | 必須。*発行者 (Issuer) 内でエンドユーザーに対してローカルに一意で、再割り当てされることのない識別子で、クライアントが利用することを意図したもの*。255 ASCII 文字以内で、大文字と小文字は区別されます。 | [OpenID Connect Core 1.0, Section 2](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) |
| UserInfo レスポンス | 常に返却。クライアントは ID トークンの `sub` と完全に一致することを検証しなければならず、一致しなければ UserInfo の値を使ってはなりません。 | [OpenID Connect Core 1.0, Section 5.3.2](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse) |
| トークンイントロスペクションレスポンス | 任意。通常は、そのトークンを認可したリソースオーナーの機械可読な識別子です。 | [RFC 7662, Section 2.2](https://www.rfc-editor.org/rfc/rfc7662#section-2.2) |
| JWT アクセストークン | 任意。JWT 内のクレームが言及している主体。発行者内でローカルに一意、またはグローバルに一意です。 | [RFC 7519, Section 4.1.2](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2) |
[OpenID Connect Core 1.0, Section 5.7](https://openid.net/specs/openid-connect-core-1_0.html#ClaimStability) は、クライアントがエンドユーザーの安定した識別子として依拠できるのは `sub` と `iss` の組み合わせだけであり、`email`、`phone_number`、`preferred_username` を一意な識別子として使ってはならないとしています。`sub` は再割り当てされないため、クライアントは自身が管理するユーザーアカウントに `sub` を対応付けて保存し、以降のログインで同じユーザーを識別できます。
認可サーバーは、この性質を満たすエンドユーザーの識別子を生成し、Authlete に `subject` リクエストパラメーターでこの識別子を渡します。受け取った値を、Authlete は前述の各要素の `sub` として出力します。
## 責務の分担
サブジェクトに関する認可サーバーと Authlete の分担は次のとおりです。
### 認可サーバー
* **エンドユーザーが誰であるかを確定します。** このステップに Authlete は関与しません。認可サーバー自身がユーザーを認証する (ログインフォーム、パスキーなど) ほか、既存のセッションに依拠する、フェデレーションにより外部の ID プロバイダーの認証結果を受け入れる、といった方法があります。
* **そのユーザーを表すサブジェクトを決定します。** 上記の性質を満たす値、すなわち内部のアカウント ID のような、変更も再利用もされないものを使ってください。メールアドレスや表示名は変更されることがあるため適しません。外部の ID プロバイダーに認証を委ねる場合も、プロバイダーの識別子をそのまま渡すのではなく、認可サーバー自身のアカウント識別子に対応付けてください。プロバイダーの識別子はそのプロバイダー内で一意かつ安定であっても、認可サーバーの発行者内でそうとは限りません。
* **発行系 API (例: [Issue Authorization Response](https://developers.authlete.com/api-reference/authorization-endpoint/issue-authorization-response.md)) にサブジェクトを渡します。** なお、ID トークンや UserInfo レスポンスに含めるべきユーザーのその他の情報は、クレームとして渡します。Authlete はユーザーストアを持たず、サブジェクトから何かを導出することはありません。
### Authlete
* **サブジェクトの形式をチェックします。** Authlete 3.0 の [Issue Authorization Response](https://developers.authlete.com/api-reference/authorization-endpoint/issue-authorization-response.md) が検査する要件は次のとおりです (他の発行系 API も同じ長さの上限を適用します)。
| 要件 | 詳細 |
| - | - |
| 空でないこと | `subject` パラメーターが無い、または空の場合、API は `server_error` で失敗します。クライアントのリクエストではなく認可サーバーの実装の不備だからです。 |
| 255 文字以内 | 超過した場合も同様に失敗します。OpenID Connect Core が `sub` に課している上限と同じです。 |
| 印字可能な ASCII 文字のみ | それ以外の文字を含む場合も同様に失敗します。 |
* **発行する認可コードやトークンにサブジェクトを紐付けます。**
* **トークンや API レスポンスにサブジェクトを含めて返却します。** ID トークンの `sub` クレーム、UserInfo レスポンスの `sub`、JWT アクセストークンの `sub`、標準イントロスペクションレスポンスの `sub` メンバー、および Authlete 独自のイントロスペクション API の `subject` フィールドとして出力します (以降のセクションを参照)。
## サブジェクトの流通経路
### 認可サーバーからの送信
認可サーバーは、エンドユーザーを特定したあと、サブジェクトを含むリクエストを発行系 (フロー完了) API に送信します。
| API | フロー |
| - | - |
| [Issue Authorization Response](https://developers.authlete.com/api-reference/authorization-endpoint/issue-authorization-response.md) | 認可コードフロー、インプリシットフロー、ハイブリッドフロー。認証と同意のあとに呼び出します。[2 段階の API 呼び出し](https://developers.authlete.com/ja/get-started/concepts/two-step-api-calls.md)を参照してください。 |
| [Issue Token Response](https://developers.authlete.com/api-reference/token-endpoint/issue-token-response.md) | リソースオーナーパスワードクレデンシャルズ。[Process Token Request](https://developers.authlete.com/api-reference/token-endpoint/process-token-request.md) が `action=PASSWORD` で返した資格情報を認可サーバーが検証したあとに呼び出します。 |
| [Complete Device Authorization](https://developers.authlete.com/api-reference/device-flow/complete-device-authorization.md) | デバイスフロー。認可リクエストを承認したエンドユーザーを渡します。 |
| [Complete Backchannel Authentication](https://developers.authlete.com/api-reference/ciba/complete-backchannel-authentication.md) | CIBA。認証デバイスで認証したユーザーを渡します。 |
| [Create Access Token](https://developers.authlete.com/api-reference/token-operations/create-access-token.md) | プロトコルのフローを経ずにアクセストークンを直接作成する場合に使います。エンドユーザーが関与しない `CLIENT_CREDENTIALS` グラントタイプでは不要です。 |
### Authlete からの受信
Authlete に渡したサブジェクトは、発行されるトークンやレスポンスの次の場所に現れます。
* **アクセストークン**にはサブジェクトが紐付けられ、トークンイントロスペクションの結果や、JWT アクセストークンが内包する値として出力されます。
* イントロスペクション: [Process Introspection Request](https://developers.authlete.com/api-reference/introspection-endpoint/process-introspection-request.md) は `subject` として、[Process OAuth 2.0 Introspection Request](https://developers.authlete.com/api-reference/introspection-endpoint/process-oauth-20-introspection-request.md) は RFC 7662 の `sub` メンバーとして返すため、リソースサーバーは受け取ったトークンが誰のものかを判別できます。
* [JWT アクセストークン](https://developers.authlete.com/ja/configuration-reference/tokens-and-claims/using-jwt-based-access-tokens.md): `sub` として持ちます。Authlete の JWT アクセストークンは RFC 9068 のクレーム名を使いますが、同プロファイルには準拠していません。詳細は「[JWTs in OAuth and OpenID Connect](https://darutk.medium.com/jwts-in-oauth-oidc-19c8029551d5#c63c)」の JWT Access Token の節を参照してください。
* クライアントクレデンシャルズグラントで発行されたトークンにはサブジェクトがなく、標準イントロスペクションでは `sub` が省略され、JWT アクセストークンでは `"sub": null` になります。
* **ID トークン**の `sub` クレームにはサブジェクトの値が入ります。
* なお、[Issue Authorization Response](https://developers.authlete.com/api-reference/authorization-endpoint/issue-authorization-response.md)、[Complete Device Authorization](https://developers.authlete.com/api-reference/device-flow/complete-device-authorization.md)、[Complete Backchannel Authentication](https://developers.authlete.com/api-reference/ciba/complete-backchannel-authentication.md) へのリクエストに `sub` パラメーターを用いるとサブジェクト以外の値を指定できます (ただし、アクセストークンはサブジェクトに紐付いたまま)。これにより、実際のサブジェクトの値をクライアントアプリケーションから隠すことができます。詳細は [ID トークンへのクレームの追加](https://developers.authlete.com/ja/configuration-reference/tokens-and-claims/adding-claims-to-an-id-token.md)を参照してください。
* **UserInfo レスポンス**も、ID トークンと同様、`sub` クレームにはサブジェクトの値が入ります。
* なお同じく、[Issue UserInfo Response](https://developers.authlete.com/api-reference/userinfo-endpoint/issue-userinfo-response.md) の `sub` パラメーターを用いるとサブジェクト以外の値を指定できます。
> [!WARNING]
>
> `sub` パラメーターが変えるのは ID トークンと UserInfo レスポンスだけです。アクセストークンはサブジェクトに紐付いたままのため、リソースサーバーが見る識別子とクライアントが見る識別子が異なることがあります。発行系 API に `sub` を渡す場合は、OpenID Connect Core 1.0, Section 5.3.2 が求めるとおり UserInfo の `sub` が ID トークンと一致するよう、[Issue UserInfo Response](https://developers.authlete.com/api-reference/userinfo-endpoint/issue-userinfo-response.md) にも同じ値を渡してください。
## サブジェクトを使ったトークンの操作
トークンにサブジェクトが紐付いたあとは、次の API や設定で、サブジェクトを使ってそのエンドユーザーのトークンを扱えます。
* [Process Introspection Request](https://developers.authlete.com/api-reference/introspection-endpoint/process-introspection-request.md) では `subject` をオプションのパラメーターとして指定できます。指定した場合、その値がアクセストークンに紐付くサブジェクトと一致しなければ、Authlete は `action=FORBIDDEN` を返すため、リソースサーバーはトークンが特定のユーザーのものであることを要求できます。
* [List Issued Tokens](https://developers.authlete.com/api-reference/token-operations/list-issued-tokens.md) は発行済みトークンをサブジェクトで絞り込めます。
* [アクセストークンの単一化](https://developers.authlete.com/ja/configuration-reference/tokens-and-claims/enabling-single-access-token-per-subject.md)は、サブジェクトごとに最新のアクセストークンだけを有効に保ちます。
いずれもサブジェクトを完全一致で比較するため、同じエンドユーザーには常に同じ識別子を渡してください。
## pairwise サブジェクト識別子の処理
### pairwise サブジェクト識別子とは
OpenID Connect Core は `sub` クレームについて 2 種類の[サブジェクト識別子タイプ](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes)を定義しています。
| タイプ | `sub` の値 | 目的 |
| - | - | - |
| `public` | すべてのクライアントで同じ値。 | 既定のタイプです。 |
| `pairwise` | クライアントごと、または**セクター** (`sector_identifier_uri` か共通のリダイレクト URI ホストで識別されるクライアント群) ごとに異なる値。 | クライアント同士が受け取った識別子を突き合わせてユーザーを関連付けることができません。 |
仕様では、pairwise サブジェクト識別子の導出方法は定めていません。ただし、セクター識別子ごとに一意な `sub` を算出すること、およびプロバイダー以外の誰にも逆算できないことを求めています ([Section 8.1](https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg))。
### Authlete の動作
認可サーバーから、その認可サーバー内で一意な識別子を受け取った Authlete は、次の手順で、クライアントごとの `sub` の値を導出します。
> [!NOTE]
>
> サブジェクト識別子タイプが `pairwise` のクライアント、かつ `sub` パラメーターが指定されていないことが前提です。
1. **クライアントのセクター識別子を決めます。** `sector_identifier_uri` が登録されていればそのホスト、なければ全リダイレクト URI に共通するホストです。`sector_identifier_uri` がなく、リダイレクト URI のホストもひとつに定まらない場合は、セクター識別子を導出できないため、Authlete はサブジェクトをそのまま `sub` に使います。
2. **`sub` の値を決定します。** セクター識別子、サービス、サブジェクトなどからハッシュを計算し、URL セーフな Base64 (パディングなし、43 文字) でエンコードした文字列を `sub` とします。つまり、同じユーザーは同じクライアント (および同じセクターの他のクライアント) で常に同じ `sub` を得る一方、異なるクライアントや異なるサービスでは異なる値になります。
変換が適用されるのは、Authlete がクライアントに対してユーザーの識別子を出力する箇所、すなわち各フローの ID トークン (CIBA、デバイスフロー、ID トークンの再発行、Native SSO を含む)、UserInfo レスポンス、ログアウトトークンの `sub` です。一方、アクセストークンには認可サーバーが渡したサブジェクトがそのまま紐付くため、イントロスペクションの `subject` や JWT アクセストークンの `sub` にはその値が返ります。
> [!NOTE]
>
> pairwise サブジェクト識別子は Authlete 2.2 以降でサポートされています。
### 設定
サブジェクト識別子タイプはクライアント単位で設定します。クライアント設定の「サブジェクトタイプ」(`subjectType`、`PUBLIC` または `PAIRWISE`) で選びます。pairwise のクライアントでリダイレクト URI のホストが複数ある場合は、あわせて「セクター識別子 URI」(`sectorIdentifierUri`) を登録してください。登録がないと Authlete はセクター識別子を導出できず、public と同じ動作になります。
## 関連ページ
* [リクエストとレスポンス](https://developers.authlete.com/ja/get-started/concepts/request-and-response.md)
* [2 段階の API 呼び出し](https://developers.authlete.com/ja/get-started/concepts/two-step-api-calls.md)
* [ID トークンへのクレームの追加](https://developers.authlete.com/ja/configuration-reference/tokens-and-claims/adding-claims-to-an-id-token.md)
* [アクセストークンの単一化](https://developers.authlete.com/ja/configuration-reference/tokens-and-claims/enabling-single-access-token-per-subject.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.