Table of Contents
本ドキュメントでは、Authlete を利用して FAPI 2.0 セキュリティプロファイルをサポートする方法について解説します。
private_key_jwt が使用されます。
以下のようにサービスを設定してください。
認可サーバーの識別子 (issuer) を設定します。
FAPI を含めます。
AUTHORIZATION_CODE を含めます。
CODE を含めます。
認可エンドポイントの URI を設定します。
含めるを選択します。
“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.2. Authorization endpoint flows”
7. RFC9207 に従って、認可レスポンスに iss レスポンスパラメーターを含めなければならない。
可変を選択します。
“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 に記述されたループバックインターフェースリダイレクションを使用するネイティブクライアントについてはこの限りではない。
トークンエンドポイントの 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
制限する を選択します。
“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.1. General requirements”
8. クライアントアサーションの aud クレームに含まれる値は、文字列型かつ認可サーバーの発行者識別子 ([RFC8414] にて規定) の値でなければならない。
認可リクエスト登録エンドポイント (PAR エンドポイント) の URL を設定します。
事前登録認可リクエストの有効時間 (リクエスト 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）の劣化や運用上の問題を引き起こすためである。
もっとも、インフラ移行などの例外的な状況では、リフレッシュトークンのローテーションが必要となる場合もある。そのため、クライアントが新しいリフレッシュトークンの保存・受理に失敗した場合に、一定期間内で古いリフレッシュトークンを使って再試行できる仕組みを認可サーバーが提供している場合には、リフレッシュトークンのローテーションは許容される。実装者は、クライアントが新しいリフレッシュトークンを失ってしまった状態から安全にリカバリーする仕組みについて検討する必要があるが、そのような仕組みの詳細については本仕様の対象外とする。
以下の条件でスコープを作成します。
myscopefapi2, 属性の値 = sp)
以下の条件を満たすクロックスキューを設定します:
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 秒先までと定めている。
認可サーバーの識別子 (issuer) を設定します。
有効にします。
AUTHORIZATION_CODE を含めます。
CODE を含めます。
認可エンドポイントの URI を設定します。
本設定は無効にします。
“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.2. Authorization endpoint flows”
7. [RFC9207] に従って、認可レスポンスに iss レスポンスパラメーターを含めなければならない。
本設定は有効にします。
“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 に記述されたループバックインターフェースリダイレクションを使用するネイティブクライアントについてはこの限りではない。
トークンエンドポイントの 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
本設定は有効にします。
“FAPI 2.0 Security Profile, 5.3.2. Requirements for authorization servers, 5.3.2.1. General requirements”
8. クライアントアサーションの aud クレームに含まれる値は、文字列型かつ認可サーバーの発行者識別子 ([RFC8414] にて規定) の値でなければならない。
“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）の劣化や運用上の問題を引き起こすためである。
もっとも、インフラ移行などの例外的な状況ではリフレッシュトークンのローテーションが必要となる場合もある。そのため、クライアントが新しいリフレッシュトークンの保存・受理に失敗した場合に、一定期間内で古いリフレッシュトークンを使って再試行できる仕組みを認可サーバーが提供している場合には、リフレッシュトークンのローテーションは許容される。実装者は、クライアントが新しいリフレッシュトークンを失ってしまった状態から安全にリカバリーする仕組みついて検討する必要があるが、そのような仕組みの詳細については本仕様の対象外とする。
以下の条件を満たすクロックスキューを設定します:
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 秒先までと定めている。
以下の条件でスコープを作成します。
myscopefapi2、値 = sp以下のようにクライアントを設定してください。
CONFIDENTIAL を選択します。
AUTHORIZATION_CODE を含めます。
CODE を含めます。
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 セットを設定します。今回の設定例では 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 ビットの長さでなければならない。
機密を選択します。
AUTHORIZATION_CODE を含めます。
CODE を含めます。
https で始まるリダイレクト URI を登録します。
PRIVATE_KEY_JWT を選択します。
“FAPI 2.0 Security Profile, 5.3.3. Requirements for clients, 5.3.3.1. General requirements”
2. shall support client authentication using one or both of the following methods:
- MTLS as specified in Section 2 of [RFC8705],
-
private_key_jwtas specified in Section 9 of [OIDC];
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 セットを設定します。今回の設定例では 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 セキュリティプロファイルに準拠した認可コードフローの動作確認を行います。
最初に、クライアントは認可サーバーへプッシュ式認可リクエスト (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] で説明されている認可コードグラントを使用しなければならない。
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 を設定しなければならない。
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://api.authlete.com/api/pushed_auth_req \
-u '{Service API Key}:{Service API Secret}' \
-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"}'curl -s -X POST https://us.authlete.com/api/{Service ID}/pushed_auth_req \
-H '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\":600,\"request_uri\":\"urn:ietf:params:oauth:request_uri:QbG...\"}"
}
リクエスト 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://api.authlete.com/api/auth/authorization \
-u '{Service API Key}:{Service API Secret}' \
-H 'Content-type: application/json' \
-d '{"parameters":"client_id={Client ID}&request_uri=urn:ietf:params:oauth:request_uri:QbG..."}'curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/authorization \
-H '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..."}'成功レスポンスは以下のようになります。
{
"type": "authorizationResponse",
"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://api.authlete.com/api/auth/authorization/issue \
-u '{Service API Key}:{Service API Secret}' \
-H 'Content-type: application/json' \
-d '{"ticket":"CBKnPeMO...","subject":"john","result":"AUTHORIZED"}'curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/authorization/issue \
-H 'Bearer {Authlete API Access Token}'
-H 'Content-type: application/json' \
-d '{"ticket":"CBKnPeMO...","subject":"john","result":"AUTHORIZED"}'成功レスポンスには以下のように認可コード (authorizationCode) が含まれています。
{
"type": "authorizationIssueResponse",
"resultCode": "A040001",
"resultMessage": "[A040001] The authorization request was processed successfully.",
"authorizationCode": "smseP17u...",
...
}
認可コードを取得した後、クライアントは認可サーバーにトークンリクエストを送信します。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://api.authlete.com/auth/token \
-u '{Service API Key}:{Service API Secret}' \
-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..."}'curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/token \
-H '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...",
...
}
取得したアクセストークンを用いて、クライアントは以下のようにリソースサーバーの保護リソースへアクセスします。
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://api.authlete.com/api/auth/introspection \
-u '{Service API Key}:{Service API Secret}' \
-H 'Content-type: application/json' \
-d '{"token":"7i9xPkbk...","dpop":"eyJ0eXAi...","htm":"GET","htu":"https://resource.example.com/api/sample"}'curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/introspection \
-H '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",
...
}