> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAPI の機能を利用する

> FAPI の機能を有効にするための具体的な方法について解説します。

<img src="https://mintcdn.com/authlete/NmFoIJ4VSX_LOgob/img/kb/ja/financial-grade-api/how-to-use-fapi_1.png?fit=max&auto=format&n=NmFoIJ4VSX_LOgob&q=85&s=e5f821600c0af4010b5aa6181b3fccaf" alt="how-to-use-fapi_1" width="596" height="268" data-path="img/kb/ja/financial-grade-api/how-to-use-fapi_1.png" />

*FAPI Profile*

## 概要

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

> 本機能は Authlete 2.0 以降でのみ利用可能になります。

> Authlete 2.2 以降をご利用の場合は [Financial-grade API (FAPI) Basics](/ja/protocols-and-flows/compliance-profiles/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** を選択。                                                                                                                                                                                       |
| サポートするクライアント認証方式 | 以下のうち、少なくとも一つを選択。<br />- TLS\_CLIENT\_AUTH<br />- SELF\_SIGNED\_TLS\_CLIENT\_AUTH<br />- CLIENT\_SECRET\_JWT<br />- PRIVATE\_KEY\_JWT<br />ただし、FAPI に対応したクライアントが全て public クライアントである場合、上記要求事項は不要となる。 |
| スコープ             | read-only 属性を持つスコープを少なくとも一つ作成。                                                                                                                                                                      |

### read-and-write API プロファイルをサポートする場合

read-and-write API プロファイルをサポートする場合、「read-only API プロファイルをサポートする場合」の設定に加えて、以下の設定が必要となります。(ただし、一部の設定内容は上書きされます。)

| 設定対象項目                          | 設定内容                                                                                                                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| サポートする認証コンテキスト                  | 適切な値を設定する。(例: urn:mace:incommon:iap:silver)                                                                                                                              |
| サポートする応答種別                      | 以下のうち、少なくとも一つを選択。<br />- CODE\_ID\_TOKEN<br />- CODE\_ID\_TOKEN\_TOKEN<br />ただし、FAPI に対応したクライアントが常に JARM (補足 2. を参照) を利用する場合、上記要求事項は不要となる。                               |
| サポートするクライアント認証方式                | 以下のうち、少なくとも一つを選択。<br />- TLS\_CLIENT\_AUTH<br />- SELF\_SIGNED\_TLS\_CLIENT\_AUTH<br />- PRIVATE\_KEY\_JWT<br />ただし、FAPI に対応したクライアントが全て public クライアントである場合、上記要求事項は不要となる。 |
| TLS クライアント証明書を紐付けたアクセストークンのサポート | **サポートする**を選択。                                                                                                                                                           |
| スコープ                            | read-and-write 属性を持つスコープを少なくとも一つ作成。                                                                                                                                      |

## クライアントの設定

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

### read-only API プロファイルをサポートする場合

以下のように設定してください。

| 設定対象項目       | 設定内容                                                                                                                                                              |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| クライアント認証方式   | このクライアントが confidential クライアントの場合は、以下のいずれかを選択。<br />- TLS\_CLIENT\_AUTH<br />- SELF\_SIGNED\_TLS\_CLIENT\_AUTH<br />- CLIENT\_SECRET\_JWT<br />- 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 プロファイルをサポートする場合」の設定に加えて、以下の設定が必要となります。(ただし、一部の設定内容は上書きされます。)

| 設定対象項目                        | 設定内容                                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 応答種別                          | 以下のうち、少なくとも一つを選択。<br />- CODE\_ID\_TOKEN<br />- CODE\_ID\_TOKEN\_TOKEN<br />ただし、このクライアントが常に JARM を利用する場合、上記要求事項は不要となる。                |
| クライアント認証方式                    | このクライアントが confidential クライアントの場合、以下のいずれかを選択。<br />- TLS\_CLIENT\_AUTH<br />- SELF\_SIGNED\_TLS\_CLIENT\_AUTH<br />- PRIVATE\_KEY\_JWT |
| TLS クライアント証明書を紐付けたアクセストークンの使用 | **使用する**を選択。                                                                                                                          |
| 認可レスポンスの署名アルゴリズム              | このクライアントが JARM を利用する場合、以下のいずれかを選択する。<br />- PS256<br />- ES256                                                                        |
| アサーション署名アルゴリズム                | クライアント認証方式で PRIVATE\_KEY\_JWT を選択している場合、以下のいずれかを選択する。<br />- PS256<br />- ES256                                                       |
| リクエストオブジェクトの署名アルゴリズム          | 以下のいずれかを選択する。<br />- PS256<br />- ES256                                                                                               |
| ID トークン署名アルゴリズム               | このクライアントが認可サーバーに対して ID トークンを要求する場合、以下のいずれかを選択する。<br />- PS256<br />- ES256                                                            |
| ユーザー情報署名アルゴリズム                | このクライアントがユーザー情報エンドポイントを利用する場合、以下のいずれかを選択する。<br />- PS256<br />- ES256                                                                 |

## リクエスト

ここでは、各セキュリティープロファイルにおける、各エンドポイント (認可エンドポイント・トークンエンドポイント)  に対するリクエストについて解説します。

## 認可エンドポイントに対するリクエスト

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

\*\*各リクエストパラメーターに対する要求事項\
\*\*

| 対象のパラメーター               | 要求事項                                                                              |
| ----------------------- | --------------------------------------------------------------------------------- |
| redirect\_uri           | 以下の要求事項を満たすリダイレクト URI 指定すること。<br />- サービスに事前登録された値と完全合致すること。<br />- https で始まること。 |
| state                   | scope パラメーターに openid スコープが含まれない場合のみ、必須となる。                                        |
| code\_challenge         | PKCE ([RFC 7636](https://tools.ietf.org/html/rfc7636)) に準拠する値を指定すること。             |
| 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") として含めること。以下に例を示す:<br /><br />`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 については、[こちらの記事](https://qiita.com/TakahikoKawasaki/items/8567c80528da43c7e844#jwt-secured-authorization-response-mode) を参照してください。

### 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 クレームを含み、その値としてサービスの「トークン発行者識別子」の値が指定されていること。

以下は、上記要求事項を満たすリクエストオブジェクトのペイロードの例になります。

```json theme={null}
{
  "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
      }
    }
  }
}
```