Skip to main content
Authlete 2.x のドキュメントは 2.x 版をご覧ください。

概要

本ドキュメントでは、Authlete で FAPI の機能を利用するための具体的な方法について解説します。 Authlete は FAPI 1.0 と FAPI 2.0 の両方をサポートします。どちらの場合も、どのプロファイルを適用するかを Authlete に伝える方法は共通です。本ドキュメントの前半でその共通のしくみを説明し、後半では FAPI 1.0 の各プロファイルについて、サービス・クライアント・リクエストに必要な設定を解説します。

各プロファイルの詳細

はじめに

Authlete がサポートする FAPI

Authlete は FAPI 1.0FAPI 2.0 の両方をサポートします。 FAPI 1.0 と 2.0 には、それぞれ複数のセキュリティープロファイルがあります。各セキュリティープロファイルにおける認可サーバーの要件は異なっており、どちらのプロファイルに従うかによって認可サーバーの振る舞いも異なります。 FAPI の機能を有効にするには、FAPI における要求事項を満たすようにサービスおよびクライアントを適切に設定したうえで、どのプロファイルを適用するかを Authlete に伝える必要があります。

プロファイルの指定方法

プロファイルの指定方法は 2 通りあります。 静的な設定を使うと、そのサービスまたはクライアントのすべてのリクエストに同じプロファイルが適用されます。準拠レベルの異なる複数のクライアントを 1 つの認可サーバーで収容する場合は、クライアントごとに「FAPI モード」を設定するか、スコープ属性による動的判定を使います。
「FAPI モード」はサービスとクライアントの設定項目で、Authlete 3.0 で追加されました。Authlete 2.x にはスコープ属性による動的判定のみがあります。

Authlete がプロファイルを決定する順序

Authlete は、リクエストごとに以下の順序で適用するプロファイルを決定します。先に条件を満たしたものが採用され、それ以降は評価されません。
  1. Authlete サーバーで FAPI 機能が有効でない場合、通常の OAuth 2.0 / OpenID Connect の仕様に従います。
  2. サービスの「指定可能なサービスプロファイル」で FAPI が有効でない場合、通常の OAuth 2.0 / OpenID Connect の仕様に従います。
  3. サービスの「FAPI モード」が設定されていれば、その値に従います。
  4. クライアントの「FAPI モード」が設定されていれば、その値に従います。
  5. リクエストに含まれる (あるいは関連付けられる) スコープの属性に従います。
  6. いずれにも該当しない場合、通常の OAuth 2.0 / OpenID Connect の仕様に従います。
サービスに「FAPI モード」を設定すると、そのサービスへのすべてのリクエストがそのモードで処理され、クライアントの「FAPI モード」とスコープ属性はいずれも参照されなくなります。クライアントごとに準拠レベルを分けたい場合は、サービスの「FAPI モード」を設定しないでください。

FAPI モードとスコープ属性の対応

fapi2 の値 baselineadvanced-jaradvanced-jarm は旧来の値で、現在は非推奨です。新たに設定する場合は上表の値を使用してください。

スコープ属性が複数のプロファイルを指す場合

スコープの属性は、リクエストに含まれる (あるいは関連付けられる) すべてのスコープから集めて評価されます。そのため、異なるプロファイルの属性を持つスコープが 1 つのリクエストに同時に含まれることがあります。 この場合、Authlete は以下の順序で判定します。先に該当したグループが採用され、それ以降は評価されません。 同時に適用されるのは 1 位のグループの中だけです。 FAPI 2.0 のメッセージ署名は、該当する属性を複数付与すれば複数が同時に適用されます。2 位から 4 位は、いずれか 1 つだけが採用されます。 たとえば、あるスコープが fapi = rw を、別のスコープが fapi2 = sp を持つリクエストでは、FAPI 2.0 セキュリティプロファイルだけが適用され、FAPI 1.0 アドバンスの属性は無視されます。
グループをまたいだ組み合わせはできません。FAPI 2.0 のメッセージ署名を指すスコープ属性が 1 つでも含まれていると、同じリクエストに fapi2 = spfapi = rw があってもそれらは評価されません。

FAPI に関する設定項目の場所

サービスの設定は、サービス設定の エンドポイント > 詳細設定 > FAPI タブにあります。「指定可能なサービスプロファイル (任意)」で FAPI プロファイルを有効にし、「FAPI モード」でこのサービスに適用するモードを選びます。「FAPI モード」で「FAPI 2.0 メッセージ署名」を選ぶと、「FAPI 2.0 メッセージ署名要件」で対象を選べるようになります。 サービス設定の「FAPI」タブ サービス設定の「FAPI」タブ クライアントの設定は、クライアント設定の エンドポイント > 詳細設定 > FAPI タブにあります。「FAPI 1.0 モード」と「FAPI 2.0 モード」があります。 クライアント設定の「FAPI」タブ クライアント設定の「FAPI」タブ スコープの属性は、サービス設定の トークン & クレーム > 詳細設定 > スコープ タブで設定します。

FAPI モードの組み合わせ規則

複数の FAPI モードを同時に指定できるのは、FAPI 2.0 のメッセージ署名同士の場合だけです。以下の 3 つは、それぞれ単独でのみ指定できます。
  • FAPI 1.0 Baseline
  • FAPI 1.0 Advanced
  • FAPI 2.0 セキュリティプロファイル
たとえば「FAPI 2.0 メッセージ署名 - 認可リクエスト」と「FAPI 2.0 メッセージ署名 - 認可レスポンス」は同時に指定でき、両方が有効になります。一方「FAPI 2.0 セキュリティプロファイル」と「FAPI 2.0 メッセージ署名 - 認可リクエスト」を同時に指定することはできません。 以降は FAPI 1.0 の設定です。FAPI 1.0 の各プロファイル (ベースライン / アドバンス) について、サービス・クライアント・リクエストに必要な設定を解説します。FAPI 2.0 の設定は「各プロファイルの詳細」に挙げた各ページをご参照ください。

サービスの設定

ここでは、各セキュリティープロファイルをサポートする場合のサービスの設定について解説します。

FAPI 1.0 ベースラインをサポートする場合

以下のように設定してください。

FAPI 1.0 アドバンスをサポートする場合

FAPI 1.0 アドバンスをサポートする場合、「FAPI 1.0 ベースラインをサポートする場合」の設定に加えて、以下の設定が必要となります。(ただし、一部の設定内容は上書きされます。)

クライアントの設定

ここでは、各セキュリティープロファイルをサポートする場合のクライアントの設定について解説します。

FAPI 1.0 ベースラインをサポートする場合

以下のように設定してください。

FAPI 1.0 アドバンスをサポートする場合

FAPI 1.0 アドバンスをサポートする場合、「FAPI 1.0 ベースラインをサポートする場合」の設定に加えて、以下の設定が必要となります。(ただし、一部の設定内容は上書きされます。)

リクエスト

ここでは、各セキュリティープロファイルにおける、各エンドポイント (認可エンドポイント・トークンエンドポイント) に対するリクエストについて解説します。

認可エンドポイントに対するリクエスト

FAPI 1.0 ベースラインにおけるリクエスト

各リクエストパラメーターに対する要求事項 リクエストの例

FAPI 1.0 アドバンスにおけるリクエスト

各リクエストパラメーターに対する要求事項 FAPI 1.0 アドバンスのリクエストを行う場合、「FAPI 1.0 ベースラインにおけるリクエスト」における要求事項に加えて、以下の要求事項を満たす必要があります。(ただし、一部の要求事項は上書きされます。) claims パラメーターの例を以下に示します。
リクエストの例

トークンエンドポイントに対するリクエスト

FAPI 1.0 ベースラインにおけるリクエスト

各リクエストパラメーターに対する要求事項 リクエストの例

FAPI 1.0 アドバンスにおけるリクエスト

各リクエストパラメーターに対する要求事項 FAPI 1.0 アドバンスにおいてリクエストを行う場合、「FAPI 1.0 ベースラインにおけるリクエスト」での要求事項に加えて、以下の要求事項を満たす必要があります。 クライアント証明書 「TLS クライアント証明書バインディング」が有効となっているため、リクエストを行う際には、クライアントはトークンエンドポイントに対してクライアント証明書を提示する必要があります。 リクエストの例

補足

1. スコープの属性

スコープの属性については、こちらの記事を参照してください。

2. JARM

JARM については、こちらの記事を参照してください。

3. キーのサイズに対する要求事項

FAPI 1.0 Part 1 には、以下の要求事項があげられています。
Financial Services – Financial API - Part 1, 5.2.2. Authorization Server The authorization server, … 5. shall require a key of size 2048 bits or larger if RSA algorithms are used for the client authentication; 6. shall require a key of size 160 bits or larger if elliptic curve algorithms are used for the client authentication;
これより、クライアント認証方式で PRIVATE_KEY_JWT を選択している場合、クライアントがアサーション (JWS) の署名に用いる秘密鍵とその検証用に用いる公開鍵は以下の要求事項を満たす必要があります。

4. リクエストオブジェクトに対する要求事項

FAPI 1.0 Part 2 では、リクエストオブジェクトに対して以下の要求事項が課せられます。
Financial Services – Financial API - Part 2, 5.2.2. Authorization Server The authorization server, …
  1. shall require the request or request_uri parameter to be passed as a JWS signed JWT as in clause 6 of [OIDC]; …
  2. shall require that all parameters are present inside the signed request object passed in the request or request_uri parameter; …
  3. shall require the request object to contain an exp claim; …
  4. shall require the aud claim in the request object to be, or to be an array containing, the OP’s Issuer Identifier URL;
更に、署名についても以下の要求事項が課せられます。
Financial Services – Financial API - Part 2, 8.6 JWS algorithm considerations Both clients and authorization servers:
  1. shall use PS256 or ES256 algorithms;
  2. should not use algorithms that use RSASSA-PKCS1-v1_5 (e.g. RS256);
  3. shall not use none;
これらをまとめると、FAPI 1.0 アドバンスをサポートする場合、リクエストオブジェクトに対して以下の要求事項が課せられることになります。
  • クライアントの「リクエストオブジェクトの署名アルゴリズム」で指定されるアルゴリズム (PS256 または ES256) を用いて署名されていること。
  • 全てのリクエストパラメーターを含むこと。
  • exp クレームを含むこと。
  • aud クレームを含み、その値としてサービスの「発行者識別子」の値が指定されていること。
以下は、上記要求事項を満たすリクエストオブジェクトのペイロードの例になります。