FAPI の機能を利用する

概要

本ドキュメントでは、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 側では以下のような判定・処理が行われます。

これらを踏まえ、以下では 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 プロファイルにおけるリクエスト>

#
# 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 プロファイルに対応するリクエスト」における要求事項に加えて、以下の要求事項を満たす必要があります。(ただし、一部の要求事項は上書きされます。)

{
  "id_token": {
    "acr": {
      "essential": true,
      "values": ["urn:mace:incommon:iap:silver"]
    }
  }
}
        

#
# 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={"id_token":{"acr":{"essential":true,"values":["urn:mace:incommon:iap:silver"]}}}&
request=eyJh...[省略]...nPQ

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

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

#
# 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 プロファイルにおけるリクエスト」での要求事項に加えて、以下の要求事項を満たす必要があります。

クライアント証明書
「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) の署名に用いる秘密鍵とその検証用に用いる公開鍵は以下の要求事項を満たす必要があります。

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
      }
    }
  }
}