Authlete を使って FAPI 2.0 セキュリティプロファイルをサポートする

このページは Authlete 3.x 用です。2.x のドキュメントはこちらをご覧ください。

概要

本ドキュメントでは、Authlete を利用して FAPI 2.0 セキュリティプロファイルをサポートする方法について解説します。

FAPI 2.0 セキュリティプロファイルは Authlete 2.3 以降で利用可能です。

前提条件

本ドキュメントでは、認可コードフローを例に解説を行います。
クライアント認証には private_key_jwt が使用されます。
アクセストークンの送信者制限メカニズムとして DPoP が使用されます。

サービスの設定

以下のようにサービスを設定してください。

☑️ 基本設定 > 発行者識別子

認可サーバーの識別子 (issuer) を設定します。

☑️ 基本設定 > 指定可能なサービスプロファイル (任意)

有効にします。

☑️ エンドポイント > 基本設定 > サポート可能なグラントタイプ

AUTHORIZATION_CODE を含めます。

☑️ エンドポイント > 基本設定 > サポート可能なレスポンスタイプ

CODE を含めます。

☑️ エンドポイント > 認可 > 認可エンドポイントURL

認可エンドポイントの URI を設定します。

☑️ エンドポイント > 認可 > 発行者識別レスポンスパラメーター

本設定は無効にします。

“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.2. Authorization endpoint flows”
7. [RFC9207] に従って、認可レスポンスに iss レスポンスパラメーターを含めなければならない。

☑️ エンドポイント > 認可 > ループバックリダイレクト URI

本設定は有効にします。

“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.2. Authorization endpoint flows”
8. 暗号化されていないネットワーク接続を介して認可レスポンスを送信しないこと、及びこの目的で http スキームを使用するリダイレクト URI を許可してはならない。ただし [RFC8252] セクション 7.3 に記述されたループバックインターフェースリダイレクションを使用するネイティブクライアントについてはこの限りではない。

☑️ エンドポイント > トークン > トークンエンドポイントURL

トークンエンドポイントの URI を設定します。

☑️ エンドポイント > トークン > サポート可能なクライアント認証方式

PRIVATE_KEY_JWT を選択します。

“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.1. General requirements”
6. クライアント認証は以下のいずれかを利用しなければならない:

[RFC8705] のセクション 2 に規定される MTLS

[OIDC] のセクション 9 に規定される private_key_jwt

☑️ エンドポイント > トークン > クライアントアサーションに含まれる aud クレームの値

本設定は有効にします。

“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.1. General requirements”
8. クライアントアサーションの aud クレームに含まれる値は、文字列型かつ認可サーバーの発行者識別子 ([RFC8414] にて規定) の値でなければならない。

☑️ エンドポイント > 一般 > プッシュ式認可リクエスト（PAR）

PAR エンドポイントの URL を設定します。
PAR エンドポイントの有効期間 (リクエスト URI の有効期間) に 600 秒未満の値を設定します。

“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.2. Authorization endpoint flows”
12. プッシュ式認可リクエストに対して発行される request_uri は expires_in の値が 600 秒未満でなければならない。

☑️ トークン＆クレーム > リフレッシュトークン > リフレッシュトークンローテーション

トークンローテーションは無効にします。

“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.1. General requirements”
9. 例外的な状況を除いて、リフレッシュトークンのローテーションは使用してはならない。(NOTE 1 を参照)
… NOTE 1: コンフィデンシャルクライアントと送信者制限されたアクセストークンが併用される場合、リフレッシュトークンのローテーションはセキュリティ上のメリットをもたらさない。本仕様では、リフレッシュトークンのローテーションをセキュリティ上の理由から禁止する。これは、クライアントが新しいリフレッシュトークンの保存や受理に失敗した場合に再試行する手段がなく、ユーザー体験（UX）の劣化や運用上の問題を引き起こすためである。もっとも、インフラ移行などの例外的な状況ではリフレッシュトークンのローテーションが必要となる場合もある。そのため、クライアントが新しいリフレッシュトークンの保存・受理に失敗した場合に、一定期間内で古いリフレッシュトークンを使って再試行できる仕組みを認可サーバーが提供している場合には、リフレッシュトークンのローテーションは許容される。実装者は、クライアントが新しいリフレッシュトークンを失ってしまった状態から安全にリカバリーする仕組みついて検討する必要があるが、そのような仕組みの詳細については本仕様の対象外とする。

☑️ トークン＆クレーム > ID トークン

以下の条件を満たすクロックスキューを設定します:

10 秒 ≤ クロックスキュー ≤ 60 秒

“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.1. General requirements”
13. 時刻のずれに対応するために、JWT に含まれる iat または nbf の値が現在時刻より 0〜10 秒先の値であっても、その JWT を受け入れなければならない。ただし、現在時刻より 60 秒を超える値が設定されている場合は、その JWT を拒否しなければならない。詳細およびその理由については NOTE 3 を参照のこと。
… NOTE 3: クロックスキュー (時刻のずれ) は相互運用性に関わる様々な問題を引き起こす原因となる。数百ミリ秒のクロックスキューですら、JWT が「将来に発行されたものである」と見なされリジェクトされる原因となる。DPoP の仕様 [RFC9449] によれば、JWT が将来のタイムスタンプを持っていても、それが秒や分の単位であれば、その JWT は受理されることが推奨される。本仕様ではさらに踏み込んで、認可サーバーは最大 10 秒先のタイムスタンプを持つ JWT を受理しなければならないとしている。10 秒という値は、セキュリティを損なわず、かつ、相互運用性を大きく向上させる値として選定されている。実装者は、最大 60 秒先のタイムスタンプを持つ JWT を受理することも可能である。いくつかのエコシステムでは、クロックスキュー問題を解決するために 30 秒という値が必要であることも分かっている。実装上 iat と nbf の検証が完全に無効になってしまうのを防ぐために、本仕様ではタイムスタンプの上限を 60 秒先までと定めている。

☑️ トークン＆クレーム > 詳細 > スコープ

以下の条件でスコープを作成します。

スコープ名: myscope
スコープのプロパティ: キー = fapi2、値 = sp

クライアントの設定

以下のようにクライアントを設定してください。

☑️ 基本設定 > クライアントタイプ

機密を選択します。

☑️ エンドポイント > 基本設定 > サポート可能な認可タイプ

AUTHORIZATION_CODE を含めます。

☑️ エンドポイント > 基本設定 > サポート可能なレスポンスタイプ

CODE を含めます。

☑️ エンドポイント > 基本設定 > リダイレクトURI

https で始まるリダイレクト URI を登録します。

☑️ エンドポイント > トークン > クライアント認証方式

PRIVATE_KEY_JWT を選択します。

“FAPI 2.0 Security Profile, 5.3.3. Requirements for clients, 5.3.3.1. General requirements”
2. 以下のいずれかまたは両方を使用してクライアント認証をサポートしなければならない:

[RFC8705] のセクション 2 で規定される MTLS

[OIDC] のセクション 9 で規定される private_key_jwt

☑️ エンドポイント > トークン > アサーション署名アルゴリズム

ES256 を選択します。

“FAPI 2.0 Security Profile, 5.4. Cryptography and secrets, 5.4.1. General requirements”
1. JWT を作成または処理する際、認可サーバー・クライアント・リソースサーバーは、以下に従わなければならない

[RFC8725] に準拠すること
PS256、ES256、または (Ed25519 形式を使用する) EdDSA アルゴリズムのいずれかを使用すること; そして
none アルゴリズムの使用・受理を禁止すること

☑️ キーマネジメント > JWKセット > JWKセットの内容

JWK セットを設定します。今回の設定例では private_key_jwt を使用するため、JWK セットにはクライアントアサーション用の署名鍵を含める必要があります。JWK セットに含める鍵群は下記要件を満たす必要があることに注意してください。

“FAPI 2.0 Security Profile, 5.4. Cryptography and secrets, 5.4.1. General requirements”
2. RSA キーは最低 2048 ビットの長さでなければならない。

3. EC キーは最低 224 ビットの長さでなければならない。

動作確認

本セクションでは、FAPI 2.0 セキュリティプロファイルに準拠した認可コードフローの動作確認を行います。

1. プッシュ式認可リクエスト (PAR リクエスト)

最初に、クライアントは認可サーバーへプッシュ式認可リクエスト (PAR リクエスト) を送信します。この際、以下の要件が必要となります。

☑️ クライアント認証

上記で設定した通り、PAR エンドポイントでのクライアント認証には private_key_jwt が利用されます。

☑️ スコープ

scope リクエストパラメーターには myscope をセットします。

☑️ レスポンスタイプ

response_type リクエストパラメーターの値は code にセットします。

“FAPI 2.0 Security Profile, 5.3.3. Requirements for clients, 5.3.3.2. Authorization code flow”
1. [RFC6749] で説明されている認可コードグラントを使用しなければならない。

☑️ PKCE

code_challenge リクエストパラメーターをセットし、code_challenge_method リクエストパラメーターには S256 をセットします。

“FAPI 2.0 Security Profile, 5.3.3. Requirements for clients, 5.3.3.2. Authorization code flow”
3. PKCE [RFC7636] を使用し、コードチャレンジメソッドとして S256 を設定しなければならない。

☑️ リダイレクト URI

redirect_uri リクエストパラメーターには、クライアントの設定で登録した URI をセットします。

“FAPI2 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.2. Authorization endpoint flows”
6. プッシュ式認可リクエスト内に redirect_uri パラメーターが含まれることを要求しなければならない。

8. 暗号化されていないネットワーク接続を介して認可レスポンスを送信しないこと、及びこの目的で http スキームを使用するリダイレクト URI を許可してはならない。ただし [RFC8252] セクション 7.3 に記述されたループバックインターフェースリダイレクションを使用するネイティブクライアントについてはこの限りではない。

これらを踏まえると、PAR エンドポイントへのリクエストは以下のようになります。

POST /oauth/par HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJraWQi...
&client_id={Client ID}
&response_type=code
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&scope=myscope
&code_challenge=E9Melhoa...
&code_challenge_method=S256

その後、認可サーバーは受け取ったリクエストパラメーター群を Authlete の /pushed_auth_req API に送信します。認可サーバーから /pushed_auth_req API への呼び出しは以下のようになります。

curl -s -X POST https://us.authlete.com/api/{Service ID}/pushed_auth_req \
-H 'Authorization: Bearer {Authlete API Access Token}' \
-H 'Content-type: application/json' \
-d '{"parameters":"client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJraWQi...&client_id={Client ID}&response_type=code&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb&scope=myscope&code_challenge=E9Melhoa...&code_challenge_method=S256"}'

成功レスポンスには以下のようにリクエスト URI (requestUri) が含まれています。

{
  "resultCode": "A245001",
  "resultMessage": "[A245001] Successfully registered a request object for client ({Client ID}), URI is urn:ietf:params:oauth:request_uri:QbG....",
  "action": "CREATED",
  "requestUri": "urn:ietf:params:oauth:request_uri:QbG...",
  "responseContent": "{\"expires_in\":300,\"request_uri\":\"urn:ietf:params:oauth:request_uri:QbG...\"}"
}

2. 認可リクエスト

リクエスト URI を取得した後、クライアントは認可サーバーに認可リクエストを送信します。認可リクエストの内容は以下のようになります。

GET /oauth/authorize?client_id={Client ID}&request_uri=urn:ietf:params:oauth:request_uri:QbG... HTTP/1.1
Host: server.example.com

その後、認可サーバーは Authlete の /auth/authorization API を呼び出します。認可サーバーから /auth/authorization API への呼び出しは以下のようになります。

curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/authorization \
-H 'Authorization: Bearer {Authlete API Access Token}' \
-H 'Content-type: application/json' \
-d '{"parameters":"client_id={Client ID}&request_uri=urn:ietf:params:oauth:request_uri:QbG..."}'

成功レスポンスは以下のようになります。

{
  "resultCode": "A004001",
  "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = {Service API Key}) for the authorization request from the client (ID = {Client ID}). [response_type=code, openid=false]",
  "ticket": "CBKnPeMO...",
  ...
}

その後、エンドユーザーはクライアントからの要求内容を認可し、認可サーバーは Authlete の /auth/authorization/issue API を呼び出します。認可サーバーから /auth/authorization/issue API への呼び出しは以下のようになります。

curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/authorization/issue \
-H 'Authorization: Bearer {Authlete API Access Token}' \
-H 'Content-type: application/json' \
-d '{"ticket":"CBKnPeMO...","subject":"john","result":"AUTHORIZED"}'

成功レスポンスには以下のように認可コード (authorizationCode) が含まれています。

{
  "resultCode": "A040001",
  "resultMessage": "[A040001] The authorization request was processed successfully.",
  "authorizationCode": "smseP17u...",
  ...
}

3. トークンリクエスト

認可コードを取得した後、クライアントは認可サーバーにトークンリクエストを送信します。PAR エンドポイントと同様に、トークンエンドポイントでも private_key_jwt によるクライアント認証が行われます。また、以下の要件に基づき、認可サーバーは送信者制限されたアクセストークンを発行します。

“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.1. General requirements”
4. 送信者制限されたアクセストークンのみを発行しなければならない。

5. 送信者制限のメカニズムとして、以下のいずれかを利用しなければならない:

[RFC8705] に規定される MTLS

[RFC9449] に規定される DPoP

“FAPI 2.0 Security Profile, 5.3.3. Requirements for clients, 5.3.3.1. General requirements”
1. 以下の方法のいずれかを使用して送信者制限されたアクセストークンをサポートしなければならない:

[RFC8705] に規定される MTLS

[RFC9449] に規定される DPoP

今回の場合、送信者制限のメカニズムとして DPoP を使用しているため、クライアントはトークンリクエスト時に DPoP proof JWT を提示する必要があります。また、下記要件により、DPoP proof JWT の署名アルゴリズムは PS256、ES256、EdDSA のいずれかでなければなりません。

“FAPI 2.0 Security Profile, 5.4. Cryptography and secrets, 5.4.1. General requirements”
1. JWT を作成または処理する際、認可サーバー・クライアント・リソースサーバーは、以下に従わなければならない

[RFC8725] に準拠すること
PS256、ES256、または (Ed25519 形式を使用する) EdDSA アルゴリズムのいずれかを使用すること; そして
none アルゴリズムの使用・受理を禁止すること

以上を踏まえると、トークンリクエストは以下のようになります。

POST /oauth/token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAi...

client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGci...
&client_id={Client ID}
&code=smseP17u...
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&grant_type=authorization_code
&code_verifier=ErRt0wrt...

トークンリクエストを受け取った後、認可サーバーは Authlete の /auth/token API をコールします。認可サーバーから /auth/token API への呼び出しは以下のようになります。

curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/token \
-H 'Authorization: Bearer {Authlete API Access Token}' \
-H 'Content-type: application/json' \
-d '{"parameters":"client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJraWQi...&client_id={Client ID}&code=smseP17u...&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&grant_type=authorization_code&code_verifier=ErRt0wrt...","dpop":"eyJ0eXAi..."}'

成功レスポンスには以下のようにアクセストークン (accessToken) が含まれています。

{
  "resultCode": "A050001",
  "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
  "accessToken": "7i9xPkbk...",
  ...
}

4. 保護リソースへのアクセス

取得したアクセストークンを用いて、クライアントは以下のようにリソースサーバーの保護リソースへアクセスします。

GET /api/sample HTTP/1.1
Authorization: DPoP 7i9xPkbk...
DPoP: eyJ0eXAi...
Host: resource.example.com

この際、クライアントはアクセストークンとともに DPoP proof JWT も送信する必要があることに注意してください。その後、リソースサーバーは Authlete の /auth/introspection API を呼び出してアクセストークンを検証します。リソースサーバーから /auth/introspection API への呼び出しは以下のようになります。

curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/introspection \
-H 'Authorization: Bearer {Authlete API Access Token}' \
-H 'Content-type: application/json' \
-d '{"token":"7i9xPkbk...","dpop":"eyJ0eXAi...","htm":"GET","htu":"https://resource.example.com/api/sample"}'

成功レスポンスは以下のようになります。

{
  "resultCode": "A056001",
  "resultMessage": "[A056001] The access token is valid.",
  "action": "OK",
  ...
}

​概要

​前提条件

​サービスの設定

​☑️ 基本設定 > 発行者識別子

​☑️ 基本設定 > 指定可能なサービスプロファイル (任意)

​☑️ エンドポイント > 基本設定 > サポート可能なグラントタイプ

​☑️ エンドポイント > 基本設定 > サポート可能なレスポンスタイプ

​☑️ エンドポイント > 認可 > 認可エンドポイントURL

​☑️ エンドポイント > 認可 > 発行者識別レスポンスパラメーター

​☑️ エンドポイント > 認可 > ループバックリダイレクト URI

​☑️ エンドポイント > トークン > トークンエンドポイントURL

​☑️ エンドポイント > トークン > サポート可能なクライアント認証方式

​☑️ エンドポイント > トークン > クライアントアサーションに含まれる aud クレームの値

​☑️ エンドポイント > 一般 > プッシュ式認可リクエスト（PAR）

​☑️ トークン＆クレーム > リフレッシュトークン > リフレッシュトークンローテーション

​☑️ トークン＆クレーム > ID トークン

​☑️ トークン＆クレーム > 詳細 > スコープ

​クライアントの設定

​☑️ 基本設定 > クライアントタイプ

​☑️ エンドポイント > 基本設定 > サポート可能な認可タイプ

​☑️ エンドポイント > 基本設定 > サポート可能なレスポンスタイプ

​☑️ エンドポイント > 基本設定 > リダイレクトURI

​☑️ エンドポイント > トークン > クライアント認証方式

​☑️ エンドポイント > トークン > アサーション署名アルゴリズム

​☑️ キーマネジメント > JWKセット > JWKセットの内容

​動作確認

​1. プッシュ式認可リクエスト (PAR リクエスト)

​☑️ クライアント認証

​☑️ スコープ

​☑️ レスポンスタイプ

​☑️ PKCE

​☑️ リダイレクト URI

​2. 認可リクエスト

​3. トークンリクエスト

​4. 保護リソースへのアクセス

概要

前提条件

サービスの設定

☑️ 基本設定 > 発行者識別子

☑️ 基本設定 > 指定可能なサービスプロファイル (任意)

☑️ エンドポイント > 基本設定 > サポート可能なグラントタイプ

☑️ エンドポイント > 基本設定 > サポート可能なレスポンスタイプ

☑️ エンドポイント > 認可 > 認可エンドポイントURL

☑️ エンドポイント > 認可 > 発行者識別レスポンスパラメーター

☑️ エンドポイント > 認可 > ループバックリダイレクト URI

☑️ エンドポイント > トークン > トークンエンドポイントURL

☑️ エンドポイント > トークン > サポート可能なクライアント認証方式

☑️ エンドポイント > トークン > クライアントアサーションに含まれる aud クレームの値

☑️ エンドポイント > 一般 > プッシュ式認可リクエスト（PAR）

☑️ トークン＆クレーム > リフレッシュトークン > リフレッシュトークンローテーション

☑️ トークン＆クレーム > ID トークン

☑️ トークン＆クレーム > 詳細 > スコープ

クライアントの設定

☑️ 基本設定 > クライアントタイプ

☑️ エンドポイント > 基本設定 > サポート可能な認可タイプ

☑️ エンドポイント > 基本設定 > サポート可能なレスポンスタイプ

☑️ エンドポイント > 基本設定 > リダイレクトURI

☑️ エンドポイント > トークン > クライアント認証方式

☑️ エンドポイント > トークン > アサーション署名アルゴリズム

☑️ キーマネジメント > JWKセット > JWKセットの内容

動作確認

1. プッシュ式認可リクエスト (PAR リクエスト)

☑️ クライアント認証

☑️ スコープ

☑️ レスポンスタイプ

☑️ PKCE

☑️ リダイレクト URI

2. 認可リクエスト

3. トークンリクエスト

4. 保護リソースへのアクセス