はじめに
このページは Authlete 2.x 用です。3.0 については こちらのページ をご覧ください。
| 日付 | 変更内容 |
|---|---|
| 2023-01-01 | 初版を公開 |
| 2024-08-03 | 仕様の名称が “OpenID Connect Federation 1.0” から “OpenID Federation 1.0” に変更されたため、テキストおよび図を更新。「はじめに」セクションを追加し、「変更履歴」を掲載。 |
概要
OpenID Federation 1.0 は、アイデンティティプロバイダー(IDP) / 認可サーバー と リライングパーティー(クライアント)が、直接的な関係を持たなくても トラストチェーン を介して互いに信頼し、IDP が事前登録なしでリライングパーティーから OAuth/OIDC リクエストを受け入れる仕組みを定義しています。






トラストチェーン
技術的には、トラストチェーンは JWT(RFC 7519 JSON Web Token)のシーケンスであり、リーフエンティティ、中間認証機関(ゼロ個以上)、およびトラストアンカーによって発行されます。リーフエンティティによる JWT の発行
リーフエンティティは、自身の秘密鍵で署名した JWT を発行します。
jwks クレームに格納されます。

iss クレーム(Issuer; RFC 7519 セクション 4.1.1)と sub クレーム(Subject; RFC 7519 セクション 4.1.2)の両方に、リーフエンティティの識別子が格納されます。

中間認証機関による JWT の発行
リーフエンティティを認可する中間認証機関(または、トラストチェーンに中間認証機関が存在しない場合はトラストアンカー)が、リーフエンティティを認可することを示す JWT を発行します。この JWT は、中間認証機関の秘密鍵で署名されます。
sub クレームにはリーフエンティティの識別子が格納され、iss クレームには中間認証機関の識別子が格納されます。

jwks クレームにはリーフエンティティの公開鍵が格納されます。

トラストアンカーによる JWT の発行
トラストチェーンは、トラストアンカーの秘密鍵で署名された JWT によって終端されます。
sub クレームには最後の中間認証機関の識別子が格納され、iss クレームにはトラストアンカーの識別子が格納されます。中間認証機関が存在しない場合は、トラストアンカーが直接リーフエンティティを認可する JWT を発行します。この場合、sub クレームにはリーフエンティティの識別子が格納されます。



iss クレームと sub クレームの両方にトラストアンカーの識別子が格納されます。

トラストチェーンの概要
以下の図は、トラストチェーン全体の構成を示しています。
トラストチェーンの解決
エンティティ構成
トラストチェーンの解決プロセスは、リーフエンティティの自己署名 JWT を取得することから始まります。 OpenID Federation 仕様では、自己署名 JWT の取得場所が定義されています。それは、リーフエンティティの識別子に固定文字列"/.well-known/openid-federation" を追加した URL です。
http:// または https:// で始まる URL であることを想像するでしょう。その想像は正しいです。
フェデレーションの参加者(IDP、リライングパーティー、中間認証機関、トラストアンカー)は “フェデレーションエンティティ” と呼ばれます。各フェデレーションエンティティは、一意の識別子 “エンティティ ID” を持ちます。そして、エンティティ ID は http または https をスキームとする URL である必要があります。この URL により、Web サーバーがエンティティを識別し、必要な JWT を発行できます。
例えば、リライングパーティーのエンティティ ID が https://rp.example.com/123 の場合、リライングパーティーの自己署名 JWT は以下の URL で公開されることが期待されます。
/.well-known/openid-federation に公開される自己署名 JWT は “エンティティ構成”(Entity Configuration)と呼ばれます。
認証機関のヒント
エンティティ構成のペイロードにはauthority_hints クレームが含まれます。このクレームは JSON 配列であり、エンティティ構成のフェデレーションエンティティを認可できる中間認証機関またはトラストアンカーのエンティティ ID をリストします。
例えば、リライングパーティー https://rp.example.com/123 が直接の中間認証機関 https://ia.example.com を持つ場合、リライングパーティーのエンティティ構成の authority_hints クレームには https://ia.example.com が含まれます。

https://ta.example.com を直接の認証機関として持つ場合、中間認証機関のエンティティ構成の authority_hints クレームには https://ta.example.com が含まれます。

authority_hints クレームが含まれません。

フェデレーションフェッチエンドポイント
リーフエンティティのエンティティ構成を取得した後の次のステップは、リーフエンティティを認可する認証機関(中間認証機関またはトラストアンカー)から JWT を取得することです。 認証機関はこのために フェデレーションフェッチエンドポイント(Federation Fetch Endpoint)を提供することが求められます。このエンドポイントの仕様は次の表にまとめられています。 リクエスト| 項目 | 内容 |
|---|---|
| HTTP メソッド | GET |
パラメータ iss | 任意。発行者のエンティティ ID |
パラメータ sub | 任意。対象(サブジェクト)のエンティティ ID |
| 項目 | 内容 |
|---|---|
| HTTP ステータスコード | 200 |
| Content-Type | application/entity-statement+jwt |
https://ia.example.com が https://ia.example.com/fetch にフェデレーションフェッチエンドポイントを提供している場合、次の HTTP リクエストを送信することで、リライングパーティー https://rp.example.com/123 を認可する JWT を取得できます。
federation_fetch_endpoint クレームに格納されますが、このクレームは metadata JSON オブジェクト内の federation_entity オブジェクト内に配置されています。

トラストチェーン解決の流れ
トラストチェーン解決の流れを振り返ります。 (1) 最初のステップは、リーフエンティティのエンティティ構成を取得することです。
authority_hints クレームが含まれています。これは、リーフエンティティを認可する中間認証機関またはトラストアンカーのエンティティ ID を示す JSON 配列です。この例では、中間認証機関 https://ia.example.com が含まれています。


sub クエリパラメータを含む HTTP リクエストを送信します。この例では、リーフエンティティのエンティティ ID (https://rp.example.com/123) を sub に指定しています。


authority_hints クレームには、上位の認証機関のエンティティ ID が含まれています。この例では、トラストアンカー https://ta.example.com が含まれています。


sub クエリパラメータを含む HTTP リクエストを送信します。この例では、中間認証機関のエンティティ ID (https://ia.example.com) を sub に指定しています。



トラストチェーン解決のまとめ
以下の図は、トラストチェーン解決の全体の流れを示しています。
メタデータ
エンティティ構成には、フェデレーションエンティティの メタデータ が含まれます。アイデンティティプロバイダーのメタデータ
アイデンティティプロバイダー(IDP)のメタデータは、metadata JSON オブジェクト内の openid_provider JSON オブジェクトに格納されます。

openid_provider JSON オブジェクトに含まれることがあります。
さらに、OpenID Federation 仕様では以下のサーバーメタデータを定義しています。
client_registration_types_supportedorganization_namefederation_registration_endpointrequest_authentication_methods_supportedrequest_authentication_signing_alg_values_supportedsigned_jwks_urijwks
リライングパーティーのメタデータ
リライングパーティーのメタデータは、metadata JSON オブジェクト内の openid_relying_party JSON オブジェクトに格納されます。

openid_relying_party JSON オブジェクトに含まれることがあります。
さらに、OpenID Federation 仕様では以下のクライアントメタデータを定義しています。
client_registration_typesorganization_namesigned_jwks_uri
認証機関のメタデータ
中間認証機関およびトラストアンカーのメタデータは、metadata JSON オブジェクト内の federation_entity JSON オブジェクトに格納されます。


federation_fetch_endpointfederation_list_endpointfederation_resolve_endpointfederation_trust_mark_status_endpointorganization_namecontactslogo_uripolicy_urihomepage_uri
メタデータポリシー
トラストチェーン内のリーフエンティティのエンティティ構成には、そのエンティティのメタデータが含まれています。これらのメタデータはmetadata クレームに格納されます。

metadata_policy クレームに格納されます。




クライアント登録
一般的なアイデンティティプロバイダーの実装では、リライングパーティー(クライアント)の識別子はアイデンティティプロバイダーによって管理されており、その識別子はアイデンティティプロバイダーの範囲内でのみ一意です。一方、OpenID Federation では、すべてのフェデレーションエンティティが グローバルに一意のエンティティ ID を持ちます。 OpenID Federation の興味深い特性の一つは、このグローバルなエンティティ ID を OAuth/OIDC リクエストのクライアント ID として使用できる ことです。例えば、以下のような認可リクエストを送信できます。この例では、client_id パラメータの値としてリライングパーティーのエンティティ ID が使用されている点に注目してください。
自動クライアント登録
OAuth/OIDC リクエストに含まれるクライアント ID が未知であるが、エンティティ ID のように見える場合、OpenID Federation をサポートするアイデンティティプロバイダーは、そのエンティティ ID から開始し、信頼できるトラストアンカーまで続くトラストチェーンを探します。 そのようなトラストチェーンが見つかると、アイデンティティプロバイダーは、エンティティ ID とメタデータを使用して自動的に新しいクライアントを登録し、OAuth/OIDC リクエストの処理を続行します。 自動クライアント登録 をサポートするアイデンティティプロバイダーのディスカバリドキュメント(OpenID Connect Discovery 1.0)には、client_registration_types_supported サーバーメタデータに automatic が含まれます。OpenID Federation 仕様では client_registration_types_supported サーバーメタデータを必須としています。

client_registration_types クライアントメタデータには automatic を含める必要があります。OpenID Federation 仕様では client_registration_types クライアントメタデータも必須としています。

リクエスト認証
OAuth/OIDC リクエストが自動クライアント登録をトリガーするとき、そのリクエストは何らかの方法で認証される必要があります。OpenID Federation 仕様では、リクエスト送信者がリクエスト内の公開鍵とペアになっている秘密鍵を所有していることを証明することを要求します。仕様では、使用可能な リクエスト認証方法 として以下の方法を挙げています。request_object- 非対称アルゴリズムで署名されたリクエストオブジェクトprivate_key_jwt- クライアントアサーションを使用したクライアント認証tls_client_auth- X.509 証明書を使用したクライアント認証self_signed_tls_client_auth- 自己署名 X.509 証明書を使用したクライアント認証
request_object を用いたリクエスト認証は、トークンエンドポイントでは使用できません。なぜなら、トークンエンドポイントでは request または request_uri のリクエストパラメータを認識しないためです。
以下の表は、エンドポイントごとのリクエスト認証方法の利用可否を示しています。
| エンドポイント | request_object | private_key_jwt | tls_client_auth | self_signed_tls_client_auth |
|---|---|---|---|---|
| 認可エンドポイント | ✓ | N/A | N/A | N/A |
| トークンエンドポイント | N/A | ✓ | ✓ | ✓ |
| PAR エンドポイント | ✓ | ✓ | ✓ | ✓ |
request_authentication_methods_supported サーバーメタデータが含まれます。

明示的クライアント登録
自動クライアント登録に加えて、OpenID Federation 仕様ではクライアントを明示的に登録する方法も定義しています。この仕組みは 明示的クライアント登録(Explicit Client Registration)と呼ばれ、OpenID Connect Dynamic Client Registration 1.0 や RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol で定義される 動的クライアント登録 に似ています。 明示的クライアント登録をサポートするアイデンティティプロバイダーは、フェデレーション登録エンドポイント(Federation Registration Endpoint)を提供します。このエンドポイントに対してクライアント登録リクエストを送信することで、明示的にクライアントを登録できます。 フェデレーション登録エンドポイントに送信できるデータは次のいずれかです。- エンティティ構成(Entity Configuration): Content-Type は
application/entity-statement+jwt - トラストチェーン(Trust Chain): エンティティステートメントの JSON 配列。Content-Type は
application/trust-chain+json

trust_anchor_id クレームが含まれている点です。このクレームの値は、登録時に選択されたトラストアンカーのエンティティ ID を示します。
レスポンスの client_id クライアントメタデータの値は、アイデンティティプロバイダーによって割り当てられたクライアント ID です。この値はエンティティ ID と異なる可能性があります。

client_registration_types_supported サーバーメタデータに explicit が含まれ、フェデレーション登録エンドポイントの URL が federation_registration_endpoint サーバーメタデータで公開されます。

client_registration_types クライアントメタデータには explicit を含める必要があります。

自動クライアント更新
トラストチェーン内のすべてのエンティティステートメントにはexp クレーム(有効期限; RFC 7519 セクション 4.1.4)が含まれています。OpenID Federation 仕様ではこのクレームを必須としています。exp クレームの最小値がトラストチェーン全体の有効期限として扱われます。

trust_chain リクエストパラメータ
OAuth/OIDC リクエストには trust_chain リクエストパラメータを含めることができます。アイデンティティプロバイダーは、このリクエストパラメータで指定されたトラストチェーンを使用して、クライアントのメタデータを更新したり、クライアントを新規登録したりする場合があります。
Authlete による実装
バージョン
OpenID Federation 1.0 は Authlete 2.3 以降のバージョンでサポートされています。 仕様は現在も進化を続けており、新機能の追加や破壊的変更が発生する可能性があります。Authlete は、今後のアップデートに合わせて機能を継続的に調整していきます。機能の有効化
OpenID Federation 1.0 の機能を有効にするには、以下の条件を満たす必要があります。これらの条件を満たさない場合、Authlete サーバーは OpenID Federation の仕様を認識しません。- Authlete サーバー に
feature.oidc_federation.enabled=trueが設定されていること。 - サービスの
federationEnabledフラグ がtrueになっていること。(Service.setFederationEnabled(boolean))
- 少なくとも 1 つの認証機関(中間認証機関またはトラストアンカー)を登録 する必要があります。登録がないと、エンティティ構成を生成できません。(Service.setAuthorityHints(URI[]))
- 少なくとも 1 つのトラストアンカーとその JWK セットを登録 する必要があります。登録がないと、どのトラストチェーンも信頼できません。(Service.setTrustAnchors(TrustAnchor[]))
- OpenID Federation 専用の秘密鍵を 1 つ以上登録 する必要があります。登録がないと、エンティティステートメントに署名できません。(Service.setFederationJwks(String))
- 自動クライアント登録または明示的クライアント登録のいずれかをサポート する必要があります。サポートがないと、フェデレーションクライアントを登録できません。(Service.setSupportedClientRegistrationTypes(ClientRegistrationType[]))

Authlete API
Authlete サーバーは OpenID Federation のために以下の API を提供します。/api/federation/configuration API
この API は エンティティ構成エンドポイント(/.well-known/openid-federation)の実装に使用されます。

リクエスト
| 項目 | 内容 |
|---|---|
| HTTP メソッド | GET |
レスポンス
| 項目 | 内容 |
|---|---|
| HTTP ステータスコード | 200 |
| Content-Type | application/json |
action | "OK" の場合、エンティティ構成エンドポイントは 200 OK を返す |
responseContent | エンティティ構成の JWT |
/api/federation/registration API
この API は フェデレーション登録エンドポイント の実装に使用されます。

リクエスト
| 項目 | 内容 |
|---|---|
| HTTP メソッド | POST |
| Content-Type | application/x-www-form-urlencoded または application/json |
entityConfiguration | フェデレーション登録リクエストのエンティティ構成 |
trustChain | フェデレーション登録リクエストのトラストチェーン |
レスポンス
| 項目 | 内容 |
|---|---|
| HTTP ステータスコード | 200 |
| Content-Type | application/json |
action | "OK" の場合、フェデレーション登録エンドポイントは 200 OK を返す |
responseContent | 新しく登録されたクライアントのエンティティステートメント |
client | 登録されたクライアントの情報 |