メインコンテンツへスキップ
how-to-use-fapi_1 FAPI Profile

概要

本ドキュメントでは、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. クライアントから認可サーバーへのリクエストに含まれる (あるいは関連付けられる) スコープを取り出します。
  2. 各スコープの属性 (補足 1. を参照) をチェックします。この時、Authlete 側では以下のような判定・処理が行われます。
判定条件Authlete の処理
スコープが read-only 属性 (「キー = fapi」 かつ「値 = r」の属性) を持つ場合read-only API のプロファイルに従う
スコープが read-and-write 属性 (「キー = fapi」 かつ「値 = rw」の属性) を持つ場合read-and-write API のプロファイルに従う
それ以外の場合通常の OAuth 2.0 / OpenID Connect の仕様に従う
これらを踏まえ、以下では FAPI の機能を利用するために必要となる具体的な設定について解説します。

サービスの設定

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

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
リダイレクト URIhttps で始まる 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 で始まること。
statescope パラメーターに openid スコープが含まれない場合のみ、必須となる。
code_challengePKCE (RFC 7636) に準拠する値を指定すること。
code_challenge_methodS256 を指定すること。
scoperead-only 属性を持つスコープを少なくとも一つ指定すること。
**リクエストの例
**
#
# public クライアントからの認可リクエストの例。
#
# (注意)
#   * scope: accounts スコープは read-only 属性を持つものとする。
#   * state: 必須ではないが OAuth 2.0 の仕様により推奨される。
#   * nonce: OpenID Connect の仕様により response_type に
#      id_token を含む場合は必須。
#
GET /api/authorization?

response_type=code+id_token&
client_id=285946231596&
redirect_uri=https://my-client.com/callback&
scope=openid+accounts&
code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
code_challenge_method=S256&
state=mystate&
nonce=mynonce

read-and-write API プロファイルにおけるリクエスト

**各リクエストパラメーターに対する要求事項
**
read-and-write API プロファイルのリクエストを行う場合、「read-only API プロファイルに対応するリクエスト」における要求事項に加えて、以下の要求事項を満たす必要があります。(ただし、一部の要求事項は上書きされます。)
対象のパラメーター要求事項
request(request_uri パラメーターを利用する場合、本要求事項は不要となる。)補足 4. の要求事項を満たすリクエストオブジェクトを指定すること。
request_uri(request パラメーターを利用する場合、本要求事項は不要となる。)補足 4. の要求事項を満たすリクエストオブジェクトを参照する URL を指定すること。
response_typecode id_token または code id_token token を指定すること。ただし、このクライアントが常に JARM を利用する場合、上記要求事項は不要となる。
code_challengepublic クライアントの場合のみ必須。PKCE (RFC 7636) に準拠する値を指定すること。
code_challenge_methodpublic クライアントの場合のみ必須。S256 を指定すること。
scoperead-and-write 属性を持つスコープを少なくとも一つ指定すること。
claimsacr クレームを必須クレーム (“essential”:true”) として含めること。以下に例を示す:

json<br />{<br /> "id_token": {<br /> "acr": {<br /> "essential": true,<br /> "values": ["urn:mace:incommon:iap:silver"]<br /> }<br /> }<br />}<br />
**リクエストの例
**
#
# confidential クライアントからの認可リクエストの例。
#
# (注意)
#   * scope: payments スコープは read-and-write 属性を持つものとする。
#   * state: 必須ではないが OAuth 2.0 の仕様により推奨される。
#   * nonce: OpenID Connect の仕様により、response_type に
#      id_token を含む場合は必須。
#
GET /api/authorization?

response_type=code+id_token&
client_id=291985138172&
scope=openid+payments&
redirect_uri=https://my-client.com/callback&
state=mystate&
nonce=mynonce&
claims=[REQUEST_OBJECT_PAYLOAD]&
request=eyJh...[省略]...nPQ

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

read-only API プロファイルにおけるリクエスト

各リクエストパラメーターに対する要求事項
対象のパラメーター要求事項
client_assertionクライアント認証方式で PRIVATE_KEY_JWT を選択している場合、本パラメーターに指定されるアサーションを生成する際には、補足 3. の要求事項を満たす鍵を用いて署名を行うこと。
**リクエストの例
**
#
# public クライアントからのトークンリクエストの例。
#
POST /api/token

client_id=285946231596&
grant_type=authorization_code&
code=_vaXlQ_ItUX4hiWzXgOT-Jp9-oVPKGQ6Q6QZu_P2GXw&
redirect_uri=https://my-client.com/callback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

read-and-write API プロファイルにおけるリクエスト

**各リクエストパラメーターに対する要求事項
**
read-and-write API プロファイルにおいてリクエストを行う場合、「read-only API プロファイルにおけるリクエスト」での要求事項に加えて、以下の要求事項を満たす必要があります。
対象のパラメーター要求事項
client_assertionクライアント認証方式で PRIVATE_KEY_JWT を選択している場合、本パラメーターに指定するアサーションに署名を付与する際には、「アサーション署名アルゴリズム」で指定したアルゴリズムを用いること。
クライアント証明書
**
「TLS クライアント証明書を紐付けたアクセストークンの使用」が有効となっているため、リクエストを行う際には、クライアントはトークンエンドポイントに対してクライアント証明書を提示する必要があります。

**
**リクエストの例
**
#
# confidential クライアントからのトークンリクエストの例。
#
# (注意)
#   * クライアント認証方式は PRIVATE_KEY_JWT を選択している想定。
#   * 以下では例示されていないが、「TLS クライアント証明書を紐付
#      けたアクセストークンの使用」が有効化されているため、クライ
#      アントはトークンエンドポイントに対してクライアント証明書を
#      提示する必要がある。
#
POST /api/token

client_id=291985138172&
grant_type=authorization_code&
code=YG-gD9v-vmnuKaHkRHcvWq1UxlxT_9vgj28ffxIAX40&
redirect_uri=https://my-client.com/callback&
client_assertion=eyJh...[省略]...OWg&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer

補足

1. スコープの属性

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

2. JARM

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

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

FAPI part1 には、以下の要求事項があげられています。
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) の署名に用いる秘密鍵とその検証用に用いる公開鍵は以下の要求事項を満たす必要があります。
アサーション署名アルゴリズムアサーションの署名・検証に用いる鍵に対する要求事項
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:
    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;
これらをまとめると、read-and-write API プロファイルをサポートする場合、リクエストオブジェクトに対して以下の要求事項が課せられることになります。
  • クライアントの「リクエストオブジェクトの署名アルゴリズム」で指定されるアルゴリズム (PS256 または ES256) を用いて署名されていること。
  • 全てのリクエストパラメーターを含むこと。
  • exp クレームを含むこと。
  • aud クレームを含み、その値としてサービスの「トークン発行者識別子」の値が指定されていること。
以下は、上記要求事項を満たすリクエストオブジェクトのペイロードの例になります。
{
  "response_type": "code id_token",
  "exp": 1554973000,
  "aud": "https://my-authz-server.com/",
  "client_id": "291985138172",
  "scope": "openid payments",
  "redirect_uri": "https://my-client.com/callback",
  "state": "mystate",
  "nonce": "mynonce",
  "claims": {
    "id_token": {
      "acr": {
        "values": ["urn:mace:incommon:iap:silver"],
        "essential": true
      }
    }
  }
}