
概要
本ドキュメントでは、Authlete で Financial-grade API (通称 FAPI) の機能を利用するための具体的な方法について解説します。本機能は Authlete 2.0 以降でのみ利用可能になります。
Authlete 2.2 以降をご利用の場合は Financial-grade API (FAPI) Basics をご参照ください。
はじめに
FAPI の仕様書はいくつかに分かれており、そのうち part1 は参照系 (read-only) API、 part2 は更新系 (read-and-write) API に関するセキュリティープロファイルとなっています。各セキュリティープロファイルにおける認可サーバーの要件は異なっており、どちらのプロファイルに従うかによって認可サーバーの振る舞いも異なる形となります。 Authlete において FAPI の機能を有効にするためには、FAPI における要求事項を満たすようにサービスおよびクライアントを適切に設定する必要があります。また、クライアントから認可サーバーへのリクエストについても適切にパラメーターを設定する必要があります。これは、Authlete では FAPI の機能を有効化するかどうかをランタイム で (リクエスト時に) 判定しているためです。したがって、仮にサービス・クライアントが FAPI に対応するよう設定されていても、リクエストの内容が不適切であった場合は FAPI の機能は有効化されないため注意が必要です。 Authlete サーバー上で FAPI の機能を有効化するかどうかを判定する具体的な手順は以下のようになります。- クライアントから認可サーバーへのリクエストに含まれる (あるいは関連付けられる) スコープを取り出します。
- 各スコープの属性 (補足 1. を参照) をチェックします。この時、Authlete 側では以下のような判定・処理が行われます。
| 判定条件 | Authlete の処理 |
|---|---|
| スコープが read-only 属性 (「キー = fapi」 かつ「値 = r」の属性) を持つ場合 | read-only API のプロファイルに従う |
| スコープが read-and-write 属性 (「キー = fapi」 かつ「値 = rw」の属性) を持つ場合 | read-and-write API のプロファイルに従う |
| それ以外の場合 | 通常の OAuth 2.0 / OpenID Connect の仕様に従う |
サービスの設定
ここでは、各セキュリティープロファイルをサポートする場合のサービスの設定について解説します。read-only API プロファイルをサポートする場合
以下のように設定してください。| 設定対象項目 | 設定内容 |
|---|---|
| サポートするプロフィール群 | FAPI を選択。 |
| サポートするクライアント認証方式 | 以下のうち、少なくとも一つを選択。 - TLS_CLIENT_AUTH - SELF_SIGNED_TLS_CLIENT_AUTH - CLIENT_SECRET_JWT - PRIVATE_KEY_JWT ただし、FAPI に対応したクライアントが全て public クライアントである場合、上記要求事項は不要となる。 |
| スコープ | read-only 属性を持つスコープを少なくとも一つ作成。 |
read-and-write API プロファイルをサポートする場合
read-and-write API プロファイルをサポートする場合、「read-only API プロファイルをサポートする場合」の設定に加えて、以下の設定が必要となります。(ただし、一部の設定内容は上書きされます。)| 設定対象項目 | 設定内容 |
|---|---|
| サポートする認証コンテキスト | 適切な値を設定する。(例: urn:mace:incommon:iap:silver) |
| サポートする応答種別 | 以下のうち、少なくとも一つを選択。 - CODE_ID_TOKEN - CODE_ID_TOKEN_TOKEN ただし、FAPI に対応したクライアントが常に JARM (補足 2. を参照) を利用する場合、上記要求事項は不要となる。 |
| サポートするクライアント認証方式 | 以下のうち、少なくとも一つを選択。 - TLS_CLIENT_AUTH - SELF_SIGNED_TLS_CLIENT_AUTH - PRIVATE_KEY_JWT ただし、FAPI に対応したクライアントが全て public クライアントである場合、上記要求事項は不要となる。 |
| TLS クライアント証明書を紐付けたアクセストークンのサポート | サポートするを選択。 |
| スコープ | read-and-write 属性を持つスコープを少なくとも一つ作成。 |
クライアントの設定
ここでは、各セキュリティープロファイルをサポートする場合のクライアントの設定について解説します。read-only API プロファイルをサポートする場合
以下のように設定してください。| 設定対象項目 | 設定内容 |
|---|---|
| クライアント認証方式 | このクライアントが confidential クライアントの場合は、以下のいずれかを選択。 - TLS_CLIENT_AUTH - SELF_SIGNED_TLS_CLIENT_AUTH - CLIENT_SECRET_JWT - PRIVATE_KEY_JWT |
| リダイレクト URI | https で始まる URI を設定。 |
| JWK セットの内容 | (「JWK セットのURI」を設定する場合、本項目の設定は不要となる。)クライアント認証方式で PRIVATE_KEY_JWT を選択している場合、本項目が直接参照する JWK セットには、補足 3. の要求事項を満たす「アサーションの署名検証用の公開鍵」を含めること。 |
| JWK セットの URI | (「JWK セットの内容」を設定する場合、本項目の設定は不要となる。)クライアント認証方式で PRIVATE_KEY_JWT を選択している場合、本項目が間接参照する JWK セットには、補足 3. の要求事項を満たす「アサーションの署名検証用の公開鍵」を含めること。 |
read-and-write API プロファイルをサポートする場合
read-and-write API プロファイルをサポートする場合、「read-only API プロファイルをサポートする場合」の設定に加えて、以下の設定が必要となります。(ただし、一部の設定内容は上書きされます。)| 設定対象項目 | 設定内容 |
|---|---|
| 応答種別 | 以下のうち、少なくとも一つを選択。 - CODE_ID_TOKEN - CODE_ID_TOKEN_TOKEN ただし、このクライアントが常に JARM を利用する場合、上記要求事項は不要となる。 |
| クライアント認証方式 | このクライアントが confidential クライアントの場合、以下のいずれかを選択。 - TLS_CLIENT_AUTH - SELF_SIGNED_TLS_CLIENT_AUTH - PRIVATE_KEY_JWT |
| TLS クライアント証明書を紐付けたアクセストークンの使用 | 使用するを選択。 |
| 認可レスポンスの署名アルゴリズム | このクライアントが JARM を利用する場合、以下のいずれかを選択する。 - PS256 - ES256 |
| アサーション署名アルゴリズム | クライアント認証方式で PRIVATE_KEY_JWT を選択している場合、以下のいずれかを選択する。 - PS256 - ES256 |
| リクエストオブジェクトの署名アルゴリズム | 以下のいずれかを選択する。 - PS256 - ES256 |
| ID トークン署名アルゴリズム | このクライアントが認可サーバーに対して ID トークンを要求する場合、以下のいずれかを選択する。 - PS256 - ES256 |
| ユーザー情報署名アルゴリズム | このクライアントがユーザー情報エンドポイントを利用する場合、以下のいずれかを選択する。 - PS256 - ES256 |
リクエスト
ここでは、各セキュリティープロファイルにおける、各エンドポイント (認可エンドポイント・トークンエンドポイント) に対するリクエストについて解説します。認可エンドポイントに対するリクエスト
read-only API プロファイルにおけるリクエスト
**各リクエストパラメーターに対する要求事項**
| 対象のパラメーター | 要求事項 |
|---|---|
| redirect_uri | 以下の要求事項を満たすリダイレクト URI 指定すること。 - サービスに事前登録された値と完全合致すること。 - https で始まること。 |
| state | scope パラメーターに openid スコープが含まれない場合のみ、必須となる。 |
| code_challenge | PKCE (RFC 7636) に準拠する値を指定すること。 |
| code_challenge_method | S256 を指定すること。 |
| scope | read-only 属性を持つスコープを少なくとも一つ指定すること。 |
**
read-and-write API プロファイルにおけるリクエスト
**各リクエストパラメーターに対する要求事項**
read-and-write API プロファイルのリクエストを行う場合、「read-only API プロファイルに対応するリクエスト」における要求事項に加えて、以下の要求事項を満たす必要があります。(ただし、一部の要求事項は上書きされます。)
| 対象のパラメーター | 要求事項 |
|---|---|
| request | (request_uri パラメーターを利用する場合、本要求事項は不要となる。)補足 4. の要求事項を満たすリクエストオブジェクトを指定すること。 |
| request_uri | (request パラメーターを利用する場合、本要求事項は不要となる。)補足 4. の要求事項を満たすリクエストオブジェクトを参照する URL を指定すること。 |
| response_type | code id_token または code id_token token を指定すること。ただし、このクライアントが常に JARM を利用する場合、上記要求事項は不要となる。 |
| code_challenge | public クライアントの場合のみ必須。PKCE (RFC 7636) に準拠する値を指定すること。 |
| code_challenge_method | public クライアントの場合のみ必須。S256 を指定すること。 |
| scope | read-and-write 属性を持つスコープを少なくとも一つ指定すること。 |
| claims | acr クレームを必須クレーム (“essential”:true”) として含めること。以下に例を示す:json<br />{<br /> "id_token": {<br /> "acr": {<br /> "essential": true,<br /> "values": ["urn:mace:incommon:iap:silver"]<br /> }<br /> }<br />}<br /> |
**
トークンエンドポイントに対するリクエスト
read-only API プロファイルにおけるリクエスト
各リクエストパラメーターに対する要求事項| 対象のパラメーター | 要求事項 |
|---|---|
| client_assertion | クライアント認証方式で PRIVATE_KEY_JWT を選択している場合、本パラメーターに指定されるアサーションを生成する際には、補足 3. の要求事項を満たす鍵を用いて署名を行うこと。 |
**
read-and-write API プロファイルにおけるリクエスト
**各リクエストパラメーターに対する要求事項**
read-and-write API プロファイルにおいてリクエストを行う場合、「read-only API プロファイルにおけるリクエスト」での要求事項に加えて、以下の要求事項を満たす必要があります。
| 対象のパラメーター | 要求事項 |
|---|---|
| client_assertion | クライアント認証方式で PRIVATE_KEY_JWT を選択している場合、本パラメーターに指定するアサーションに署名を付与する際には、「アサーション署名アルゴリズム」で指定したアルゴリズムを用いること。 |
**
「TLS クライアント証明書を紐付けたアクセストークンの使用」が有効となっているため、リクエストを行う際には、クライアントはトークンエンドポイントに対してクライアント証明書を提示する必要があります。
**
**リクエストの例
**
補足
1. スコープの属性
スコープの属性については、こちらの記事 (TBW) を参照してください。2. JARM
JARM については、こちらの記事 を参照してください。3. キーのサイズ対する要求事項
FAPI part1 には、以下の要求事項があげられています。Financial Services – Financial API - Part 1, 5.2.2. Authorization Server The authorization server,これより、クライアント認証方式で PRIVATE_KEY_JWT を選択している場合、クライアントがアサーション (JWS) の署名に用いる秘密鍵とその検証用に用いる公開鍵は以下の要求事項を満たす必要があります。
…
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;
| アサーション署名アルゴリズム | アサーションの署名・検証に用いる鍵に対する要求事項 |
|---|---|
| RSA 系のアルゴリズムを選択している場合 | 鍵のサイズが 2048 ビット以上であること。 |
| EC 系のアルゴリズムを選択している場合 | 鍵のサイズが 160 ビット以上であること。 |
| それ以外の場合 | 要求事項はない。 |
4. リクエストオブジェクトに対する要求事項
FAPI part2 では、リクエストオブジェクトに対して以下の要求事項が課せられます。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];
…
10. shall require that all parameters are present inside the signed request object passed in the request or request_uri parameter;
…
13. shall require the request object to contain an exp claim;
…
15. 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:これらをまとめると、read-and-write API プロファイルをサポートする場合、リクエストオブジェクトに対して以下の要求事項が課せられることになります。
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;
- クライアントの「リクエストオブジェクトの署名アルゴリズム」で指定されるアルゴリズム (PS256 または ES256) を用いて署名されていること。
- 全てのリクエストパラメーターを含むこと。
- exp クレームを含むこと。
- aud クレームを含み、その値としてサービスの「トークン発行者識別子」の値が指定されていること。