Authlete 2.x のドキュメントは 2.x 版をご覧ください。

はじめに

このドキュメントでは、Authlete を利用した Financial-grade API Security Profile 1.0 - Part 2: Advanced （以下 FAPI）対応のアイデンティティ・プロバイダーを構築する手順を通じて、同仕様が規定するセキュリティ条項の概要と Authlete の設定方法を紹介します。手順の実施にあたっては、以下のチュートリアルとナレッジベース記事を通読し、 OpenID Connect と Authlete に関する基本的な理解を有していることが必須です。

構成

本チュートリアルでは以下の構成を想定します。なお、実サービスとして動作するのは、Authlete のコンソールと API だけです。認可サーバー（OIDC アイデンティティプロバイダー）とリソースサーバーはいずれも実際には存在しませんが、それぞれのサーバーがクライアント（OIDC リライングパーティ）から認可リクエストやトークンリクエスト、そしてトークンイントロスペクションリクエストを受信したときに、どのような API リクエストを Authlete に行うかを、curl コマンドを用いて試行します。

チュートリアルにおける各要素の構成

本チュートリアルでは便宜上、OIDC アイデンティティプロバイダーを「認可サーバー」、同リライングパーティを「クライアント」と表記します。

各サービスの FQDN は以下の通りです。上述の通り認可サーバーとクライアントは存在しませんが、OAuth のフローを説明する上で FQDN が最低限必要となります。

サービス	FQDN
Authlete API（US クラスターの場合）	`us.authlete.com`
Authlete 管理コンソール	`console.authlete.com`
認可サーバー（OIDC アイデンティティプロバイダー） (Authorization Server)	`as.example.com`
クライアント（OIDC リライングパーティ） (Client)	`client.example.org`
リソースサーバー (Resource Server)	N/A

Authlete 3.0 の API ホストはサービスが属するクラスターによって決まります。本チュートリアルでは US クラスター (us.authlete.com) を前提に記述しています。日本クラスターの場合は jp.authlete.com に読み替えてください。値はコンソールのサービス概要にある「クラスターURL」で確認できます。

FAPI を用いた API クライアントと API サーバーとの間のやりとり

本ドキュメントでは、FAPI に準拠した以下のトークン授受・利用フローに対応するための設定を行います。

FAPI 準拠のトークン授受・利用フロー

1. 認可リクエスト (Authorization Request)

クライアントはリクエストオブジェクトを用いた認可リクエストを作成・送信する必要があります。リクエストオブジェクトは値渡し（request パラメーターを使用）もしくは参照渡し（request_uri パラメーターを使用）のいずれかとなります。本ドキュメントでは前者を用います。

参照渡しの場合には Pushed Authorization Requests (PAR) の利用を推奨します。

また、response_type パラメーターの指定についても FAPI の規定に従う必要があります。 response_type として本ドキュメントでは code id_token を用います。

response_type として code を用いる場合には、JARM (JWT Secured Authorization Response Mode for OAuth 2.0) の設定が必要です。

その他、claims の設定などについては後述します。

2. 認可レスポンス (Authorization Response)

本ドキュメントでは、認可リクエストに response_type=code id_token が指定されることから、フラグメントとして code を返却します。

3. トークンリクエスト (Token Request)

トークンリクエストでは、認可サーバーはクライアントを認証する方法として公開鍵方式を用いる必要があります。本ドキュメントでは TLS 双方向認証を用います。

4. トークンレスポンス (Token Response)

認可サーバーは、トークンエンドポイントに提示されるクライアント証明書と、発行するアクセストークンとをバインド（ひもづけ）し、トークンレスポンスを返却します。

5. API リクエスト (API Request)

クライアントとリソースサーバーは、TLS 双方向認証を用いてクライアント認証を行った上で、アクセストークンを含む API リクエストを送受信します。リソースサーバーはクライアント証明書とアクセストークンとのひもづけを検証の上、API レスポンスを返却します。

初期設定

新規サービスとそのクライアントの追加

サービスの追加と FAPI の有効化

Authlete 管理コンソールにログインし、対象の組織を開いて「サービスを新規作成」をクリックします。サービスの新規作成ページが表示されるので、以下を入力・選択して「作成」をクリックします。

項目	値
API クラスター	任意のクラスター（本チュートリアルでは `US`）
サービス名	任意の値（例: `FAPI Service`）
サービスの詳細情報	任意の値
指定可能なサービスプロファイル (任意)	有効にする

サービスの新規作成

「指定可能なサービスプロファイル (任意)」を有効にすると、このサービスが FAPI プロファイルをサポートするようになります。これは FAPI の機能を使うための前提条件です。既存のサービスで後から有効にする場合は、サービス設定の「エンドポイント > 詳細設定 > FAPI」タブで同じ項目を切り替えます。

作成したサービスの「サービス概要」には「サービスID」と「クラスターURL」が表示されます。以降の curl 例で使うため控えておきます。また、Authlete API を呼び出すための「サービスアクセストークン」を発行します。手順は Authlete のセットアップの「サービスアクセストークンの取得」を参照してください。サービス設定の「エンドポイント > 詳細設定 > FAPI」タブを開くと、FAPI に関する設定項目を確認できます。

サービス設定の「FAPI」タブ

「FAPI モード」を選択すると、このサービスへのすべてのリクエストがそのモードで処理されます。本チュートリアルではリクエストのスコープに応じて FAPI 準拠の処理を適用するため、「FAPI モード」は「なし」のままにします。判定の順序については FAPI の機能を利用するをご参照ください。

次に、FAPI 対象のスコープを作成します。サービス設定の「トークン&クレーム > 詳細設定 > スコープ」タブを開き、「サポートするスコープ」の「追加」をクリックすると、スコープの追加ダイアログが表示されます。ここでは以下の内容のスコープを作成し、「追加」をクリックしたのち「変更を保存」で保存します。

あるスコープの属性として、キー: fapi、値: rw を追加すると、Authlete はそのスコープが要求された場合に FAPI 準拠の処理を行います。スコープ属性についてはスコープの属性をご参照ください。

項目	値
スコープ名	`payment`
詳細	任意の値
デフォルトスコープとして設定	無効
スコープのプロパティ	キー: `fapi` / 値: `rw`

スコープの追加

クライアントの追加と基本設定

サービスの「クライアント」ページで「クライアントを新規作成」をクリックし、以下を入力・選択して「作成」をクリックします。

項目	値
クライアント名	任意の値（例: `FAPI Client`）
クライアントID（任意）	空欄のまま（Authlete が自動生成します）
クライアントの詳細情報	任意の値
クライアントタイプ	`機密` (CONFIDENTIAL)

クライアントの新規作成 作成後、クライアント設定の「エンドポイント > 基本設定 > リダイレクトURI」で以下を追加し、「変更を保存」をクリックします。

項目	値
リダイレクト URI	`https://client.example.org/cb/example.com`

これにより、サービスへのクライアント情報の登録が完了しました。自動生成された「クライアントID」は、クライアントが認可サーバーにリクエストを行う際の client_id の値として用いられます。なお、同時に「クライアントシークレット」も生成されていますが、本チュートリアルでは使いません。

項目	値
クライアント ID	自動生成された値（例: `591205987816490`）
クライアントタイプ	`機密` (CONFIDENTIAL)
リダイレクト URI	`https://client.example.org/cb/example.com`

初期設定後の動作確認

/auth/authorization API 上記の設定によって Authlete がどのように動作するかを、まず /auth/authorization API を用いて確認します。以降の curl 例では、{サービス ID}、{サービスアクセストークン}、{クライアント ID} を、ここまでの手順で取得した値に置き換えてください。

非 FAPI スコープに関する認可リクエスト

認可サーバーが、FAPI 対象のスコープが含まれない (scope=openid のみの) 認可リクエストを受信したと仮定し、 /auth/authorization API に対して以下のリクエストを送信します。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"parameters": "redirect_uri=https://client.example.org/cb/example.com&scope=openid&response_type=code&client_id={クライアント ID}&nonce=n-0S6_WzA2Mj"}' | jq

すると、以下のようなレスポンス（一部折り返しています）が返却されます。

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

resultMessage の記述から、scope=openid のように、FAPI 対象ではないスコープの場合には、認可リクエストが Authlete に受け入れられたことがわかります。それでは、FAPI の対象となるスコープの場合にはどのようになるか、次に試してみます。

FAPI スコープに関する認可リクエスト (1)

認可サーバーが、FAPI 対象のスコープ（payment）を含む認可リクエスト（scope=openid payment）を受信したと仮定し、 /auth/authorization API に対して以下のリクエストを送信します。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"parameters": "redirect_uri=https://client.example.org/cb/example.com&scope=openid+payment&response_type=code&client_id={クライアント ID}&nonce=n-0S6_WzA2Mj"}' | jq

すると、以下のようなエラーレスポンスが返却されます。

{
  "resultCode": "A150312",
  "resultMessage": "[A150312] The value of 'response_type' (code) is not allowed.",
[...]

resultMessage の内容を見ると、response_type=code は許可されていないことがわかります。これは FAPI の 5.2. Advanced security provisions / 5.2.2. Authorization server に

shall require

the response_type value code id_token, or

the response_type value code in conjunction with the response_mode value jwt;

とある通り、FAPI では response_type=code id_token か、もしくは response_mode=jwt を指定した上で response_type=code の、どちらかを用いなくてはならないからです。つまり response_type=code のみの指定は禁止されている（認可サーバーはそのようなレスポンスタイプを受け付けてはならない）のです。

FAPI スコープに関する認可リクエスト (2)

それでは、response_type=code ではなく response_type=code id_token とした認可リクエストの場合にはどうなるでしょうか。 /auth/authorization API に対して以下のリクエストを送信します。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"parameters": "redirect_uri=https://client.example.org/cb/example.com&scope=openid+payment&response_type=code+id_token&client_id={クライアント ID}&nonce=n-0S6_WzA2Mj"}' | jq

すると以下のような異なるエラーレスポンスが返却されます。

{
  "resultCode": "A150301",
  "resultMessage": "[A150301] A request object is required.",
[...]

resultMessage の記述から、この場合には、リクエストオブジェクトが必要だとわかります。これは上述と同じく、FAPI の 5.2. Advanced security provisions / 5.2.2. Authorization server に

shall only use the parameters included in the signed request object passed via the request or request_uri parameter;

とある通り、FAPI では、認可サーバーはクライアントに対して、リクエストオブジェクトを値渡し（request）ないし参照渡し（request_uri）にて認可リクエストに含めるよう、要求しなくてはならないからです。それでは次に、リクエストオブジェクトを用いた認可リクエストを準備してみましょう。

認可リクエストの FAPI 対応

本セクションでは、リクエストオブジェクトを用いた認可リクエストを作成します。

リクエストオブジェクトの設定

リクエストオブジェクトの署名鍵の設定

まず、クライアントがリクエストオブジェクトに署名するための鍵を準備します。ここでは例として、mkjwk を用いて、ES256 の鍵ペアを生成し、 2 種類（秘密鍵を含むもの・含まないもの）の鍵セットを生成します。パラメーターは以下の通り選択・入力しています。

項目	値
タブ	`EC` (楕円曲線)
曲線	`P-256`
鍵の用途	`Signing`
アルゴリズム	`ES256 (ECDSA using P-256 and SHA-256)`
鍵の ID	任意の値（例: `1`）

mkjwk を用いた JWK セット生成 以下は生成された鍵セットの例です。

es256_keyset.txt （秘密鍵 "d" の行を含む)

{
  "keys": [
    {
      "kty": "EC",
      "d": "L6KxA-db4oh5NKYEpO6IulUDSRXP7fqNAmScu6fygIE",
      "use": "sig",
      "crv": "P-256",
      "kid": "1",
      "x": "icP8p_AigyTzwSpLRyv_bBQTSGu_NG7pMVXd-RAxwYE",
      "y": "06tC0MJeBlZNYlnY8g4bCA9wJ34XN-rWfWlmmlhf-F0",
      "alg": "ES256"
    }
  ]
}

es256_keyset_pub.txt （es256_keyset.txt から秘密鍵 "d" の行を削除)

{
  "keys": [
    {
      "kty": "EC",
      "use": "sig",
      "crv": "P-256",
      "kid": "1",
      "x": "icP8p_AigyTzwSpLRyv_bBQTSGu_NG7pMVXd-RAxwYE",
      "y": "06tC0MJeBlZNYlnY8g4bCA9wJ34XN-rWfWlmmlhf-F0",
      "alg": "ES256"
    }
  ]
}

クライアント設定の追加

Authlete サービスに、クライアントから受信したリクエストオブジェクトの署名を検証させるためには、そのクライアントの設定として公開鍵を登録し、さらに署名アルゴリズムを指定する必要があります。まず、クライアント設定の「キーマネジメント > JWKセット」を開き、以下を設定して「変更を保存」をクリックします。

項目	値
JWKセットの内容	`es256_keyset_pub.txt` の内容をペースト

クライアント設定の「JWKセットの内容」 次に、クライアント設定の「エンドポイント > 認可 > リクエストオブジェクト」を開き、以下を設定して「変更を保存」をクリックします。

項目	値
リクエストオブジェクトの署名アルゴリズム	`ES256`

クライアント設定の「リクエストオブジェクト」 上記の設定により、リクエストオブジェクトの署名検証の準備が整いました。

リクエストオブジェクトの生成

ここではリクエストオブジェクトを作成し、認可リクエストを組み立てます。まず、以下のペイロードを準備します。client_id, nbf, exp の値は適宜変更します。 payload.txt

{
"redirect_uri":"https://client.example.org/cb/example.com",
"response_type":"code id_token",
"client_id":"<クライアント ID> 例: 591205987816490",
"scope":"openid payment",
"nbf": <現在時刻の Unix time> 例: 1613373232,
"exp": <nbf に 3600 を加えた値> 例: 1613376832,
"aud":"https://as.example.com",
"nonce":"n-0S6_WzA2Mj"
}

以下は nbf と exp の値の生成例です。

nbf クレーム: date +%s などを実行して現在時刻の Unix time を取得し、それを nbf クレームの値としてペイロードに追加します。たとえば date +%s の結果が 1613373232 である場合には、payload.txt に追加する行は "nbf":1613373232, です。
exp クレーム: nbf に 3600 を加えた値を、exp に指定します。たとえば "nbf":1613373232 である場合には、1613373232 + 3600 = 1613376832 となり、payload.txt の当該行の修正は "exp":1613376832, です。

秘密鍵を用いて Signed JWT を作成します。以下は mkjose を用いて作成する例です。各項目を入力・選択し、「生成する」ボタンを押下すると、「結果」の欄に Signed JWT が出力されます。

項目	値
ペイロード	`payload.txt` の内容をペースト
署名アルゴリズム	`EC256` を選択
署名鍵	`es256_keyset.txt` の内容から、先頭 2 行（`"keys":`, `[`）と末尾 2 行（`]`, `}`）を削除してペースト（JWK セットではなく JWK にする必要があるため）

mkjose を用いた Signed JWT の生成 また、step CLI を用いて作成する場合には以下の例のようになります。

cat payload.txt | \
step crypto jws sign --jwks=es256_keyset.txt --kid=1

以下は実行結果の例です。この文字列を、認可リクエストの request パラメーターの値として用います。

eyJhbGciOiJFUzI1NiIsImtpZCI6IjEifQ.ewoicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9jbGllbnQuZXhhbXBsZS5vcmcvY2IvZXhhbXBsZS5jb20iLAoicmVzcG9uc2VfdHlwZSI6ImNvZGUgaWRfdG9rZW4iLAoiY2xpZW50X2lkIjoiNTkxMjA1OTg3ODE2NDkwIiwKInNjb3BlIjoib3BlbmlkIHBheW1lbnQiLAoiZXhwIjoxNTU0OTczMDAwMCwKImF1ZCI6Imh0dHBzOi8vYXMuZXhhbXBsZS5jb20iLAoibm9uY2UiOiJuLTBTNl9XekEyTWoiCn0K.q_MbfV5qN-gnB93JaQGVrEXu8WvhDuUzWx6DwC50J8AiQGjXDEpw9satUAMN18rrgnGNciiFztoEFJuJjrJoyA

動作確認

認可サーバーが認可リクエストをクライアントから受信したと仮定し、 Authlete の /auth/authorization API に対して以下のリクエストを送信します。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"parameters": "redirect_uri=https://client.example.org/cb/example.com&scope=openid+payment&response_type=code+id_token&client_id={クライアント ID}&nonce=n-0S6_WzA2Mj&request=eyJhbGciOiJFUzI1NiIsImtpZCI6IjEifQ.ewoicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9jbGllbnQuZXhhbXBsZS5vcmcvY2IvZXhhbXBsZS5jb20iLAoicmVzcG9uc2VfdHlwZSI6ImNvZGUgaWRfdG9rZW4iLAoiY2xpZW50X2lkIjoiNTkxMjA1OTg3ODE2NDkwIiwKInNjb3BlIjoib3BlbmlkIHBheW1lbnQiLAoiZXhwIjoxNTU0OTczMDAwMCwKImF1ZCI6Imh0dHBzOi8vYXMuZXhhbXBsZS5jb20iLAoibm9uY2UiOiJuLTBTNl9XekEyTWoiCn0K.q_MbfV5qN-gnB93JaQGVrEXu8WvhDuUzWx6DwC50J8AiQGjXDEpw9satUAMN18rrgnGNciiFztoEFJuJjrJoyA"}' | jq

すると、以下のようなレスポンス（一部折り返しています）が返却されます。

{
  "resultCode": "A004001",
  "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service
   (API Key = 174381609020) for the authorization request from the client
   (ID = 591205987816490). [response_type=code id_token, openid=true]",
[...]
  "ticket": "rjasCNvemUwamKP0G1h9Fh5Uo_3fgBfQsTF1PU4-GiE"
[...]

resultMessage の記述から、リクエストが受理されたことがわかります。そして期待した通り、ticket が返却されています。認可サーバーはこの ticket の値をログインセッションに格納し、ユーザー認証と同意確認を行い、そして Authlete の /auth/authorization/issue API を呼び出し、認可レスポンスの生成を要求することになります。本ドキュメントの手順では、認可リクエストに response_type=code id_token と指定しています。よって認可レスポンスは、認可コード code と ID トークン id_token を、フラグメントとして含むものになります。

/auth/authorization/issue API 認可サーバーがユーザー認証と同意確認を行い、その結果決定したユーザー識別子（subject）が testuser01 であったと仮定し、 /auth/authorization/issue API にリクエストを送信してみましょう。この subject と、上記の ticket が、API リクエストの引数となります。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization/issue \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"subject":"testuser01","ticket":"rjasCNvemUwamKP0G1h9Fh5Uo_3fgBfQsTF1PU4-GiE"}' | jq

すると、以下のようなレスポンス（一部折り返しています）が返却されます。

{
  "resultCode": "A151301",
  "resultMessage": "[A151301] The algorithm
   ('HS256' for 'id_token_signed_response_alg')
    to sign the ID token is not allowed.",
[...]

resultMessage の記述から、現在設定されている（Authlete の既定値である）HS256 が、ID トークンの署名アルゴリズムとして許可されていないことがわかります。これは FAPI の 8.6. Algorithm considerations に

shall use PS256 or ES256 algorithms;

とある通り、クライアントと認可サーバーは JWS アルゴリズムとして ES256 もしくは PS256 のどちらかを用いなければならないからです。本ドキュメントでは、認可サーバーが ID トークンの署名アルゴリズムとして ES256 を用いるように、Authlete を設定してみます。

認可レスポンスの FAPI 対応

ID トークンの署名アルゴリズムの変更

ID トークンの署名鍵の追加

ES256 の鍵セットを生成し、ID トークンの署名に用いる鍵としてサービスに登録するとともに、クライアント設定として ID トークンの署名アルゴリズムに ES256 を指定します。手順の詳細は ID トークンの署名鍵の変更を参照してください。

このセクションにて生成する鍵セットは、認可サーバーが ID トークンの署名に用いるためのものです。一方、先の「リクエストオブジェクトの署名鍵の設定」において生成・登録した鍵セットは、クライアントから受け取ったリクエストオブジェクトの署名を認可サーバーが検証するためのものです。両者を混同しないようにご注意ください。

本ドキュメントでは、以下のパラメーターを選択・入力します。

項目	値
タブ	`EC` (楕円曲線)
曲線	`P-256`
鍵の用途	`Signing`
アルゴリズム	`ES256 (ECDSA using P-256 and SHA-256)`
鍵の ID	任意の値（例: `1`）

生成された鍵セット（“Keypair set”）を、まずサービスに登録します。サービス設定の「キーマネジメント > JWKセット > 認可サーバー」を開き、以下を設定して「変更を保存」をクリックします。

項目	値
JWKセットの内容	生成した Keypair set をペースト
IDトークン署名キーID	この Keypair set の `kid` の値（上記の例では `1`）

サービス設定の「JWKセットの内容」「IDトークン署名キーID」 次に、クライアント設定の「トークン&クレーム > IDトークン」を開き、「IDトークンアルゴリズム」の「署名アルゴリズムを選択」で ES256 を選択して「変更を保存」をクリックします。この設定により Authlete は、このクライアントに対して ID トークンを発行する際の署名アルゴリズムとして ES256 を用いるようになります。

クライアント設定の「IDトークンアルゴリズム」

動作確認

変更後、ticket 生成から再度動作確認を行います。まず /auth/authorization API を実行します。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"parameters": "redirect_uri=https://client.example.org/cb/example.com&scope=openid+payment&response_type=code+id_token&client_id={クライアント ID}&nonce=n-0S6_WzA2Mj&request=<リクエストオブジェクト>"}' \
| jq | grep ticket

この処理結果（一部折り返しています）として ticket が返却されます。

{
[...]
  "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service
   (API Key = 174381609020) for the authorization request from the client
   (ID = 591205987816490). [response_type=code id_token, openid=true]",
  "ticket": "3TzdZO2t8qXaQXIEUA5LLN106uVk5fpwL8_UDGlcwUQ"
[...]

返却された ticket と subject の値を用いて、/auth/authorization/issue API にリクエストを行います。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization/issue \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"subject":"testuser01","ticket":"3TzdZO2t8qXaQXIEUA5LLN106uVk5fpwL8_UDGlcwUQ"}' | jq

すると、以下のようなレスポンス（一部折り返しています）が返却されます。

{
  "resultCode": "A040001",
  "resultMessage": "[A040001] The authorization request was processed successfully.",
  "accessTokenDuration": 0,
  "accessTokenExpiresAt": 0,
  "action": "LOCATION",
  "authorizationCode": "TSRAvPIp6V3RgPOs2O7FpPG1_7t6Xpc_kcIramz8gBQ",
  "idToken": "eyJraWQiOiIxIiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJ0ZXN0dXNlcjAxIiwiYXVkIjpbIjU5MTIwN
   Tk4NzgxNjQ5MCJdLCJjX2hhc2giOiJZQjloU01CWkJLdnFobnFaWWRWTXJnIiwiaXNzIjoiaHR0cHM6L
   y9hcy5leGFtcGxlLmNvbSIsImV4cCI6MTU3MjQxMDUyNiwiaWF0IjoxNTcyMzI0MTI2LCJub25jZSI6I
   m4tMFM2X1d6QTJNaiJ9.ZY5XK4TqAfcnLsMhkigNRpyM6CvwD7SdX-f9TQ18pwMUdh7eoGc6ijlfEnc4
   I3l0jYhlm22yuEeffV6XZhdL0A",
  "responseContent": "https://client.example.org/cb/example.com#
   code=TSRAvPIp6V3RgPOs2O7FpPG1_7t6Xpc_kcIramz8gBQ&
   id_token=eyJraWQiOiIxIiwiYWxnIjoiRVMyNTYifQ..."
}

resultMessage の記述から、認可リクエストの処理に成功したことがわかります。また idToken, authorizationCode にそれぞれ値が返却されています。そして responseContent として、認可サーバーがクライアントに返却する HTTP レスポンスが生成されており、レスポンスのフラグメント部に ID トークンと認可コードが含まれていることがわかります。この後クライアントは ID トークンを検証し、さらにその中に含まれる c_hash クレームを用いて認可コードを検証したのちに、認可サーバーにトークンリクエストを送信することになります。そして認可サーバーはそのトークンリクエストを Authlete の /auth/token API に送信し、アクセストークンを含むトークンレスポンスの生成を要求します。

/auth/token API /auth/token API に対するリクエストは以下の通りです。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/token \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"clientId":"{クライアント ID}","clientSecret":"<クライアントシークレット>","parameters": "grant_type=authorization_code&redirect_uri=https://client.example.org/cb/example.com&code=TSRAvPIp6V3RgPOs2O7FpPG1_7t6Xpc_kcIramz8gBQ"}' | jq

すると、以下のようなレスポンス（一部折り返しています）が返却されます。

{
  "resultCode": "A157301",
  "resultMessage": "[A157301] The client type of the client is 'confidential'
   but the client authentication method is 'none'.",
  "action": "INVALID_CLIENT",
  "clientId": 591205987816490,
  "grantType": "AUTHORIZATION_CODE",
  "responseContent": "{\"error_description\":\"[A157301] The client type
   of the client is 'confidential' but the client authentication method is 'none'.\",
   \"error\":\"invalid_client\",\"error_uri\":\"https://docs.authlete.com/#A157301\"}"
}

resultMessage の記述から、コンフィデンシャルクライアントのクライアント認証として、 Authlete の既定値である none は許可されていないことがわかります。これは FAPI の 5.2 Read and write API security provisions / 5.2.2. Authorization server に

shall authenticate the confidential client using one of the following methods (this overrides FAPI Security Profile 1.0 - Part 1: Baseline clause 5.2.2-4):

tls_client_auth or self_signed_tls_client_auth as specified in section 2 of MTLS, or

private_key_jwt as specified in section 9 of OIDC;

とある通り、FAPI では RFC 8705 が定義する Mutual TLS for OAuth Client Authentication、もしくは OpenID Connect Core 1.0 が定義する private_key_jwt のどちらかを用いなくてはならないからです。つまり none や、コンフィデンシャルクライアントの場合に広く使われている client_secret_basic は禁止されている（認可サーバーはそのようなクライアント認証を行ってはならない）のです。本ドキュメントでは前者、かつ PKI Mutual-TLS Method (tls_client_auth) を用いるように Authlete を設定してみます。

private_key_jwt を用いる場合には private_key_jwt によるクライアント認証をご参照ください。なお、同クライアント認証手段を用いた場合にも、「Holder of Key」を実現するための TLS 双方向認証の設定は同時に必要となります。

トークンリクエストの FAPI 対応

TLS クライアント認証の設定

クライアント認証に「TLS クライアント認証」を用いるように、サービスおよびクライアントの設定を変更します。

サービス側の TLS クライアント認証設定

サービス設定の「エンドポイント > トークン」を開き、「サポート可能なクライアント認証方式」で以下を選択して「変更を保存」をクリックします。

項目	値
サポート可能なクライアント認証方式	`TLS_CLIENT_AUTH`

サービス設定の「サポート可能なクライアント認証方式」

クライアント側の TLS クライアント認証設定

クライアント設定の「エンドポイント > トークン > MTLS」を開き、以下を設定して「変更を保存」をクリックします。

項目	値
サブジェクト識別名	`CN=client.example.org, O=Client, L=Chiyoda-ku, ST=Tokyo, C=JP`

クライアント設定の「サブジェクト識別名」 続いてクライアント設定の「エンドポイント > トークン」を開き、以下を設定して「変更を保存」をクリックします。

項目	値
クライアント認証方式	`TLS_CLIENT_AUTH`

クライアント設定の「クライアント認証方式」 以上の設定により、Authlete サービスは TLS 双方向認証によるクライアント認証に対応し、かつ上記のクライアントからのトークンリクエストについて、その認証方式を適用することになります。また認証の際のクライアント識別名として CN=client.example.org, ... を用います。

自己署名証明書の生成

クライアントが自身の認証に用いる証明書を作成します。以下は openssl を用いて作成する例です。

秘密鍵の生成

openssl genrsa 2048 > private_key_nopass.pem

CSR の作成（Subject DN として CN=client.example.org, O=Client, L=Chiyoda-ku, ST=Tokyo, C=JP を指定）

openssl req -new -key private_key_nopass.pem -out server.csr

Country Name (2 letter code) []:JP
State or Province Name (full name) []:Tokyo
Locality Name (eg, city) []:Chiyoda-ku
Organization Name (eg, company) []:Client
Organizational Unit Name (eg, section) []:
Common Name (eg, fully qualified host name) []:client.example.org
Email Address []:

証明書の作成

openssl x509 -days 365 -req -signkey private_key_nopass.pem -in server.csr -out server.crt

curl コマンドを用いてリクエストを行う際には、生成された server.crt の内容を 1 行で表現したもの（改行を \n に置き換えたもの）を用います。

-----BEGIN CERTIFICATE-----\nMIIDPDCCAiQCCQDWNMOIuzwDfzANBgkqhkiG9w0BAQUFADBgMQswCQYDVQQGEwJK\n[...]\nSo6zun26vAUJTu1o9CIjxw==\n-----END CERTIFICATE-----\n

動作確認

サービス設定とクライアント設定をそれぞれ変更したのちに、以下の手順を実行します。

/auth/authorization API を実行し、レスポンスから ticket の値を取得
/auth/authorization/issue API を実行し、レスポンスから authorizationCode の値を取得
以下を変更の上、/auth/token API を実行
- clientCertificate パラメーターを追加し、値としてクライアント証明書を指定する
- clientSecret パラメーターを削除する（TLS 双方向認証を用いるため不要となります）

以下は /auth/token API に送信するリクエストの例です。

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/token \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"clientId":"{クライアント ID}","parameters": "grant_type=authorization_code&redirect_uri=https://client.example.org/cb/example.com&code=HVIza0dGG9nDKGStAzMObYH9GkXME0aRSaLEcToHEI8","clientCertificate":"-----BEGIN CERTIFICATE-----\n[...]\n-----END CERTIFICATE-----\n"}' | jq

すると、以下のようなレスポンス（一部折り返しています）が返却されます。

{
  "resultCode": "A152305",
  "resultMessage": "[A152305] The service and the client are not configured
   so that the required Holder of Key methods are performed.",
  "accessToken": "RCqjF4tlffJ7-n92sAEFQNIwrRm0syOUrBu0cNLAIJU",
  "action": "BAD_REQUEST",
  "clientId": 591205987816490,
  "grantType": "AUTHORIZATION_CODE",
  "responseContent": "{\"error_description\":\"[A152305] The service and the client are
   not configured so that the required Holder of Key methods are performed.\",
   \"error\":\"invalid_request\",\"error_uri\":\"https://docs.authlete.com/#A152305\"}"
}

resultMessage の記述から、アクセストークンは発行されたものの、未だ設定が不足しているために、 FAPI 仕様上必須である「Holder of Key」が行われなかったことがわかります。すなわち、ここまでの手順だけでは、 TLS クライアント証明書をひもづけたアクセストークン発行の処理が行われていないということです。

トークンレスポンスの FAPI 対応

Holder of Key の設定

サービス側のアクセストークン設定

サービス設定の「トークン&クレーム > アクセストークン」を開き、以下を設定して「変更を保存」をクリックします。

項目	値
相互TLSクライアント証明書バインディング	有効にする

サービス設定の「相互TLSクライアント証明書バインディング」

クライアント側のアクセストークン設定

クライアント設定の「トークン&クレーム > アクセストークン」を開き、以下を設定して「変更を保存」をクリックします。

項目	値
TLSクライアント証明書バインディング	有効にする

クライアント設定の「TLSクライアント証明書バインディング」 以上により、FAPI 準拠の認可サーバーの設定が完了しました。

設定完了後の実行例

FAPI 準拠のトークン授受・利用フロー（Authlete を利用） 変更後、先と同様の手順により /auth/authorization API、/auth/authorization/issue API、/auth/token API を実行します。さらに /auth/introspection API を実行して、最終的に API リクエストに用いられるアクセストークンが、クライアントの TLS クライアント証明書に紐づけられていることを確認します。

認可リクエスト

/auth/authorization API へのリクエスト

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"parameters": "redirect_uri=https://client.example.org/cb/example.com&scope=openid+payment&response_type=code+id_token&client_id={クライアント ID}&nonce=n-0S6_WzA2Mj&request=<リクエストオブジェクト>"}' | jq | grep ticket

レスポンス（一部折り返しています）

{
[...]
  "resultMessage": "[A004001] Authlete has successfully issued a ticket
   to the service (API Key = 174381609020) for the authorization request
  from the client (ID = 591205987816490). [response_type=code id_token, openid=true]",
  [...]
  "ticket": "b0JGD-ZkT8ElBGw2ck-T-t87Z033jXvhqC2omPT1bQ4"
  [...]

認可レスポンス

/auth/authorization/issue API へのリクエスト

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/authorization/issue \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"subject":"testuser01","ticket":"b0JGD-ZkT8ElBGw2ck-T-t87Z033jXvhqC2omPT1bQ4"}' | jq

レスポンス（一部折り返しています）

{
  "resultCode": "A040001",
  "resultMessage": "[A040001] The authorization request was processed successfully.",
  "action": "LOCATION",
  "authorizationCode": "DxiKC0cOc_46nzVjgr41RWBQtMDrAvc0BUbMJ_v7I70",
  "idToken": "eyJraWQiOiIxIiwiYWxnIjoiRVMyNTYifQ.eyJzdWIiOiJ0ZXN0dXNlcjAxIiwiYXVkIjpbIjU5MTIwN
  Tk4NzgxNjQ5MCJdLCJjX2hhc2giOiJqR2kyOElvYm5HcjNNQ3Y0UUVQRTNnIiwiaXNzIjoiaHR0cHM6L
  y9hcy5leGFtcGxlLmNvbSIsImV4cCI6MTU3MjQxMjY4MiwiaWF0IjoxNTcyMzI2MjgyLCJub25jZSI6I
  m4tMFM2X1d6QTJNaiJ9.1PFmc0gAsBWtLBriq3z9a4Tsi_ioEYlOqOYbicGEXWIS1WGX5ffGOyZNSzVB
  MamZbltZmSys0jlYmmYYLqgGsg",
  "responseContent": "https://client.example.org/cb/example.com#
  code=DxiKC0cOc_46nzVjgr41RWBQtMDrAvc0BUbMJ_v7I70&
  id_token=eyJraWQiOiIxIiwiYWxnIjoiRVMyNTYifQ..."
}

トークンリクエスト/レスポンス

/auth/token API へのリクエスト

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/token \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"clientId":"{クライアント ID}","parameters": "grant_type=authorization_code&redirect_uri=https://client.example.org/cb/example.com&code=DxiKC0cOc_46nzVjgr41RWBQtMDrAvc0BUbMJ_v7I70","clientCertificate":"-----BEGIN CERTIFICATE-----\n[...]\n-----END CERTIFICATE-----\n"}' | jq

レスポンス（一部折り返しています）

{
  "resultCode": "A050001",
  "resultMessage": "[A050001] The token request (grant_type=authorization_code)
   was processed successfully.",
  "accessToken": "SUtEVc3Tj3D3xOdysQtssQxe9egAhI4fimexNVMjRyU",
  "accessTokenDuration": 86400,
  "accessTokenExpiresAt": 1572412769390,
  "action": "OK",
  "clientId": 591205987816490,
  "grantType": "AUTHORIZATION_CODE",
  "refreshToken": "tXZjYfoK35I-djg9V3n6s58zsrVqRIzTNMXKIS_wkj8",
  "scopes": [
    "openid",
    "payment"
  ],
  "subject": "testuser01"
}

API リクエスト

上記手順の結果、アクセストークンとして SUtEVc3Tj3D3xOdysQtssQxe9egAhI4fimexNVMjRyU が生成されています。この値をリソースサーバーがクライアントから受信したと仮定し、/auth/introspection API を用いて、このアクセストークンの有効性と、関連する情報の取得を試みます。この際に、リソースサーバーがクライアントから同時に受け取るであろう、クライアント証明書も併せて API に送信します。

/auth/introspection API

/auth/introspection API へのリクエスト

curl -s -X POST https://us.authlete.com/api/{サービス ID}/auth/introspection \
-H 'Authorization: Bearer {サービスアクセストークン}' \
-H 'Content-Type: application/json' \
-d '{"token":"SUtEVc3Tj3D3xOdysQtssQxe9egAhI4fimexNVMjRyU","clientCertificate":"-----BEGIN CERTIFICATE-----\n[...]\n-----END CERTIFICATE-----\n"}' | jq

レスポンス（一部折り返しています）

{
  "resultCode": "A056001",
  "resultMessage": "[A056001] The access token is valid.",
  "action": "OK",
  "certificateThumbprint": "cBNP0zNH0fkcIQdVHdB8GDQAbaZyIjKXB0EVRTByJMU",
  "clientId": 591205987816490,
  "existent": true,
  "expiresAt": 1572412769000,
  "refreshable": true,
  "responseContent": "Bearer error=\"invalid_request\"",
  "scopes": [
    "openid",
    "payment"
  ],
  "subject": "testuser01",
  "sufficient": true,
  "usable": true
}

certificateThumbprint が返却されていることから、このアクセストークンがクライアント証明書にひもづけられていることがわかります。これによりリソースサーバーは、クライアントから受信したアクセストークンの有効性を確認し、そのトークンにひもづいている情報を取得することができました。

まとめ

本チュートリアルでは、FAPI に準拠したトークン授受・使用に対応した認可サーバーを構築するための、Authlete の設定を行いました。

​はじめに

​構成

​FAPI を用いた API クライアントと API サーバーとの間のやりとり

​1. 認可リクエスト (Authorization Request)

​2. 認可レスポンス (Authorization Response)

​3. トークンリクエスト (Token Request)

​4. トークンレスポンス (Token Response)

​5. API リクエスト (API Request)

​初期設定

​新規サービスとそのクライアントの追加

​サービスの追加と FAPI の有効化

​クライアントの追加と基本設定

​初期設定後の動作確認

​非 FAPI スコープに関する認可リクエスト

​FAPI スコープに関する認可リクエスト (1)

​FAPI スコープに関する認可リクエスト (2)

​認可リクエストの FAPI 対応

​リクエストオブジェクトの設定

​リクエストオブジェクトの署名鍵の設定

​クライアント設定の追加

​リクエストオブジェクトの生成

​動作確認

​認可レスポンスの FAPI 対応

​ID トークンの署名アルゴリズムの変更

​ID トークンの署名鍵の追加

​動作確認

​トークンリクエストの FAPI 対応

​TLS クライアント認証の設定

​サービス側の TLS クライアント認証設定

​クライアント側の TLS クライアント認証設定

​自己署名証明書の生成

​動作確認

​トークンレスポンスの FAPI 対応

​Holder of Key の設定

​サービス側のアクセストークン設定

​クライアント側のアクセストークン設定

​設定完了後の実行例

​認可リクエスト

​認可レスポンス

​トークンリクエスト/レスポンス

​API リクエスト

​まとめ

はじめに

構成

FAPI を用いた API クライアントと API サーバーとの間のやりとり

1. 認可リクエスト (Authorization Request)

2. 認可レスポンス (Authorization Response)

3. トークンリクエスト (Token Request)

4. トークンレスポンス (Token Response)

5. API リクエスト (API Request)

初期設定

新規サービスとそのクライアントの追加

サービスの追加と FAPI の有効化

クライアントの追加と基本設定

初期設定後の動作確認

非 FAPI スコープに関する認可リクエスト

FAPI スコープに関する認可リクエスト (1)

FAPI スコープに関する認可リクエスト (2)

認可リクエストの FAPI 対応

リクエストオブジェクトの設定

リクエストオブジェクトの署名鍵の設定

クライアント設定の追加

リクエストオブジェクトの生成

動作確認

認可レスポンスの FAPI 対応

ID トークンの署名アルゴリズムの変更

ID トークンの署名鍵の追加

動作確認

トークンリクエストの FAPI 対応

TLS クライアント認証の設定

サービス側の TLS クライアント認証設定

クライアント側の TLS クライアント認証設定

自己署名証明書の生成

動作確認

トークンレスポンスの FAPI 対応

Holder of Key の設定

サービス側のアクセストークン設定

クライアント側のアクセストークン設定

設定完了後の実行例

認可リクエスト

認可レスポンス

トークンリクエスト/レスポンス

API リクエスト

まとめ