FAPI の機能を利用する

概要


本ドキュメントでは、Authlete で Financial-grade API (通称 FAPI) の機能を利用するための具体的な方法について解説します。


はじめに


FAPI の仕様書はいくつかに分かれており、そのうち part1 は参照系 (read-only) API、 part2 は更新系 (read-and-write) API に関するセキュリティープロファイルとなっています。各セキュリティープロファイルにおける認可サーバーの要件は異なっており、どちらのプロファイルに従うかによって認可サーバーの振る舞いも異なる形となります。Authlete において FAPI の機能を有効にするためには、FAPI における要求事項を満たすようにサービスおよびクライアントを適切に設定する必要があります。また、クライアントから認可サーバーへのリクエストについても適切にパラメーターを設定する必要があります。これは、Authlete では FAPI の機能を有効化するかどうかをランタイム で (リクエスト時に) 判定しているためです。したがって、仮にサービス・クライアントが FAPI に対応するよう設定されていても、リクエストの内容が不適切であった場合は FAPI の機能は有効化されないため注意が必要です。Authlete サーバー上で FAPI の機能を有効化するかどうかを判定する具体的な手順は以下のようになります。

  1. クライアントから認可サーバーへのリクエストに含まれる (あるいは関連付けられる) スコープを取り出します。
  2. 各スコープの属性 (補足 1. を参照) をチェックします。この時、Authlete 側では以下のような判定・処理が行われます。
    判定条件
    Authelte の処理
    スコープが 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
リダイレクト 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_KWT を選択している場合、以下のいずれかを選択する。

  • 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 属性を持つスコープを少なくとも一つ指定すること。


リクエストの例

#
# 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_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") として含めること。

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

(注意) OAuth 2.0 の仕様により、client_id と response_type パラメーターはリクエストパラメーター群に含まれなければなりませんが、他のパラメーターについてはリクエストオブジェクト内に含まれるのであればリクエストパラメーター群に含まれる必要はありません。

リクエストの例

#
# 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 プロファイルにおけるリクエスト>


各リクエストパラメーターに対する要求事項
対象のパラメーター
要求事項
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
      }
    }
  }
}
How did we do with this article?