
概要
本ドキュメントでは、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 側では以下のような判定・処理が行われます。
これらを踏まえ、以下では FAPI の機能を利用するために必要となる具体的な設定について解説します。
サービスの設定
ここでは、各セキュリティープロファイルをサポートする場合のサービスの設定について解説します。read-only API プロファイルをサポートする場合
以下のように設定してください。read-and-write API プロファイルをサポートする場合
read-and-write API プロファイルをサポートする場合、「read-only API プロファイルをサポートする場合」の設定に加えて、以下の設定が必要となります。(ただし、一部の設定内容は上書きされます。)クライアントの設定
ここでは、各セキュリティープロファイルをサポートする場合のクライアントの設定について解説します。read-only API プロファイルをサポートする場合
以下のように設定してください。read-and-write API プロファイルをサポートする場合
read-and-write API プロファイルをサポートする場合、「read-only API プロファイルをサポートする場合」の設定に加えて、以下の設定が必要となります。(ただし、一部の設定内容は上書きされます。)リクエスト
ここでは、各セキュリティープロファイルにおける、各エンドポイント (認可エンドポイント・トークンエンドポイント) に対するリクエストについて解説します。認可エンドポイントに対するリクエスト
read-only API プロファイルにおけるリクエスト
**各リクエストパラメーターに対する要求事項**
**リクエストの例
**
read-and-write API プロファイルにおけるリクエスト
**各リクエストパラメーターに対する要求事項**
read-and-write API プロファイルのリクエストを行う場合、「read-only API プロファイルに対応するリクエスト」における要求事項に加えて、以下の要求事項を満たす必要があります。(ただし、一部の要求事項は上書きされます。)
**リクエストの例
**
トークンエンドポイントに対するリクエスト
read-only API プロファイルにおけるリクエスト
各リクエストパラメーターに対する要求事項
**リクエストの例
**
read-and-write API プロファイルにおけるリクエスト
**各リクエストパラメーターに対する要求事項**
read-and-write API プロファイルにおいてリクエストを行う場合、「read-only API プロファイルにおけるリクエスト」での要求事項に加えて、以下の要求事項を満たす必要があります。
クライアント証明書
**
「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;
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 クレームを含み、その値としてサービスの「トークン発行者識別子」の値が指定されていること。