private_key_jwt によるクライアント認証

For Authlete 2.x documentation, see 2.x version.

はじめに

private_key_jwt は、OpenID Connect Core 1.0, 9. Client Authentication で定義されているクライアント認証方式のひとつです。トークンリクエストにおいて、クライアントはデジタル署名された JWT アサーションを生成し、それをリクエストに含めます。認可サーバーは、そのアサーションの署名とペイロードを検証することでクライアントを認証します。 Authlete は、認可サーバーが private_key_jwt クライアント認証方式をサポートするための機能を提供しています。本記事では、この方式の概要と Authlete における設定手順を説明します。

private_key_jwt の要件

以下では、クライアント側と認可サーバー側の両方について詳細を説明します。

クライアント

private_key_jwt 方式を使用する場合、クライアントはトークンリクエストに次のパラメーターを含める必要があります。

パラメーター	説明
client_assertion_type	client_assertion の種別です。その値は “urn:ietf:params:oauth:client-assertion-type:jwt-bearer” である必要があります。
client_assertion	クライアント認証のための情報を含む JWT です。秘密鍵を用いてデジタル署名されている必要があります。詳細は以下を参照してください。

client_assertion の値は、その JWT ペイロードおよび JWT 署名について、以下の要件を満たす必要があります。JWT の例は「JWT アサーションの生成」のセクションを参照してください。

ペイロード

JWT アサーションには、以下に挙げる REQUIRED（必須）のクレームを含める必要があります。

クレーム	説明
iss	[REQUIRED] Issuer（発行者）。OAuth クライアントの client_id を含める必要があります。
sub	[REQUIRED] Subject（主体）。OAuth クライアントの client_id を含める必要があります。
aud	[REQUIRED] Audience（受け手）。想定される受け手として認可サーバーを識別する値です。認可サーバーは、自身がこのトークンの想定される受け手であることを検証する必要があります。この値は認可サーバーのトークンエンドポイントの URL とすべきです。
jti	[REQUIRED] JWT ID。トークンの一意な識別子であり、トークンの再利用を防ぐために使用できます。当事者間で再利用の条件が取り決められている場合を除き、これらのトークンは一度のみ使用しなければなりません。そのような取り決めは本仕様の範囲外です。
exp	[REQUIRED] 有効期限。この時刻以降、JWT は処理のために受理されてはなりません。
iat	[OPTIONAL] JWT が発行された時刻です。

署名

JWT アサーションは、非対称暗号の秘密鍵（例: RS256）を用いてデジタル署名されている必要があります。
この認証方式を使用するクライアントは、認可サーバーがアサーションを検証できるよう、あらかじめ自身の公開鍵を認可サーバーに登録しておく必要があります。

認可サーバー

認可サーバーは、以下に示す仕様に従ってトークンリクエストを処理する必要があります。これらの処理は認可サーバーから Authlete にオフロードできるため、ここでは詳細を省略します。

設定

このセクションでは、private_key_jwt 方式を有効化するための設定を説明します。この方式で認証を行うには、Authlete のサービスとそのクライアントの両方を設定する必要があります。

サービスの設定

Authlete の管理コンソールにログインし、「サービス設定」>「エンドポイント」>「トークン」に移動します。「サポート可能なクライアント認証方式」セクションで、PRIVATE_KEY_JWT のチェックボックスを有効にします。

クライアントの設定

タブ	項目	値
「基本設定」	「クライアントタイプ」	機密（CONFIDENTIAL）
「エンドポイント」>「トークン」	「クライアント認証方式」	PRIVATE_KEY_JWT
「エンドポイント」>「トークン」	「アサーション署名アルゴリズム」	RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 のいずれか
「キーマネジメント」>「JWKセット」	「JWKセットの内容」	クライアントの JWT アサーションを検証するために使用する公開鍵を含む JWK セット

「クライアント設定」>「エンドポイント」>「トークン」に移動します。「クライアント認証方式」セクションでドロップダウンメニューを開き、PRIVATE_KEY_JWT を選択します。さらに、「アサーション署名アルゴリズム」として ES256 を選択します。「変更を保存」をクリックして更新を適用します。

「キーマネジメント」>「JWK セット」に移動します。「JWK セットの内容」セクションに JWK セットを入力します。「変更を保存」をクリックして更新を適用します。

例

この例では、認可サーバーのトークンエンドポイントにおける private_key_jwt を用いたクライアント認証を示します。

JWT アサーションの生成

トークンリクエストの client_assertion の値として使用する JWT を生成してみましょう。

JWT ペイロードの準備

まず、JSON 形式のペイロードを作成し、“payload.json” として保存します。

{
    "jti": "myJWTId001",
    "sub": "38174623762",
    "iss": "38174623762",
    "aud": "http://localhost:4000/api/auth/token/direct/24523138205",
    "exp": 1536165540,
    "iat": 1536132708
}

JWK セットの準備

次に、署名と検証のための JWK セットを準備します。ここでは mkjwk.org を使って JWK セットを生成します。

以下の例は ES256 アルゴリズムを用いて生成したもので、「公開鍵と秘密鍵のペア」を “key_pair.jwk” というファイルに保存しています。後者の「公開鍵のみ」を Authlete に登録し、「クライアント認証方式」（PRIVATE_KEY_JWT）と Client Assertion Algorithm（ES256）を設定してください。これらは前のセクションで説明したとおりクライアント設定から行えます。

「公開鍵と秘密鍵のペア」

{
    "kty": "EC",
    "d": "ukQKQexNI8PtEv7SKpqUDnbZ-WkN6HaQqcVrVV8ZWRQ",
    "use": "sig",
    "crv": "P-256",
    "x": "9Yxd2TvwBbgmupZh3bpg3umKihM_FNAk2_uI_-Edv_Q",
    "y": "BOUFuyvWoBZ9-RVSeHJLF-L4I3ORv0xbaM1CKCFJr54",
    "alg": "ES256"
}

「公開鍵」（クライアント設定として Authlete に登録するもの）

{
    "kty": "EC",
    "use": "sig",
    "crv": "P-256",
    "x": "9Yxd2TvwBbgmupZh3bpg3umKihM_FNAk2_uI_-Edv_Q",
    "y": "BOUFuyvWoBZ9-RVSeHJLF-L4I3ORv0xbaM1CKCFJr54",
    "alg": "ES256"
}

JWT の生成

ペイロードを含み、秘密鍵で署名した JWT アサーションを生成します。以下の例は authlete-jose library を使った手順です。または mkjose.org のウェブサイトを使って行うこともできます。

bin/jose-generator \
--payload-file payload.json \
--sign \
--signing-alg ES256 \
--jwk-signing-alg-file key_pair.jwk

生成される JWT は次のようになります（表示のための改行のみ挿入しています）。

eyJhbGciOiJFUzI1NiJ9.
ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiL
AogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbG
hvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAo
gICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
YB4gdhWUGRjWEsEbKDs7-G2WFH2oYz7bAEP5AtegHXInkY9ncA2V3IoA6O_HV
QuFxyCRIklrxsMk32MfNF_ABA

この JWT が client_assertion の値となり、クライアントがトークンリクエストを行う際に使用します。

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

クライアントから認可サーバーへのトークンリクエスト

アサーションを持つクライアントが認可サーバーへトークンリクエストを行うとします。（可読性のため折り返しています）

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=Gw30fMKJBHkcOBSde5awLrMm4ahvgCNM2cFSTUOUflY&
redirect_uri=https://example.com/redirection&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJFUzI1NiJ9.ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.YB4gdhWUGRjWEsEbKDs7-G2WFH2oYz7bAEP5AtegHXInkY9ncA2V3IoA6O_HVQuFxyCRIklrxsMk32MfNF_ABA

認可サーバーから Authlete への API リクエスト

認可サーバーは、リクエストの内容を Authlete の /auth/token に転送します。（可読性のため折り返しています）

$ curl -s -X POST https://us.authlete.com/api/<Service ID e.g., 21653835348762>/auth/token \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <SERVICE ACCESS TOKEN>' \
-d '{
  "parameters":"grant_type=authorization_code&code=Gw30fMKJBHkcOBSde5awLrMm4ahvgCNM2cFSTUOUflY&redirect_uri=https://example.com/redirection&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJhbGciOiJFUzI1NiJ9.ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.YB4gdhWUGRjWEsEbKDs7-G2WFH2oYz7bAEP5AtegHXInkY9ncA2V3IoA6O_HVQuFxyCRIklrxsMk32MfNF_ABA"
}'

Authlete から認可サーバーへの API レスポンス

Authlete はリクエストを処理し、次のような API レスポンスを認可サーバーに返します。（可読性のため折り返しています）

{
   "resultCode": "A050001",
   "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
   "accessToken": "ni6uDszfkeR5GH96k3cUjt3R7MHG9-xRbMDObaKGY2A",
   "responseContent": {
      "access_token": "ni6uDszfkeR5GH96k3cUjt3R7MHG9-xRbMDObaKGY2A",
      "refresh_token": "dyzc8D96hSdrCmaPaB75uFiqjWTIWHXq-_OjVN17gAk",
      "scope": null,
      "token_type": "Bearer",
      "expires_in": 3600
   },
   ...
}

認可サーバーからクライアントへのトークンレスポンス

認可サーバーは “responseContent” の値を取り出し、トークンレスポンスとしてクライアントに返します（詳細は省略）。

エンドポイント

トークン & クレーム

鍵管理

メタデータ

Error Handling & Debugging

セキュリティ

クライアント管理

サービス設定

private_key_jwt によるクライアント認証

はじめに

private_key_jwt の要件

クライアント

ペイロード

署名

認可サーバー

設定

サービスの設定

クライアントの設定

例

JWT アサーションの生成

JWT ペイロードの準備

JWK セットの準備

JWT の生成

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

クライアントから認可サーバーへのトークンリクエスト

認可サーバーから Authlete への API リクエスト

Authlete から認可サーバーへの API レスポンス

認可サーバーからクライアントへのトークンレスポンス

関連情報

​はじめに

​private_key_jwt の要件

​クライアント

​ペイロード

​署名

​認可サーバー

​設定

​サービスの設定

​クライアントの設定

​例

​JWT アサーションの生成

​JWT ペイロードの準備

​JWK セットの準備

​JWT の生成

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

​クライアントから認可サーバーへのトークンリクエスト

​認可サーバーから Authlete への API リクエスト

​Authlete から認可サーバーへの API レスポンス

​認可サーバーからクライアントへのトークンレスポンス

​関連情報

はじめに

private_key_jwt の要件

クライアント

ペイロード

署名

認可サーバー

設定

サービスの設定

クライアントの設定

例

JWT アサーションの生成

JWT ペイロードの準備

JWK セットの準備

JWT の生成

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

クライアントから認可サーバーへのトークンリクエスト

認可サーバーから Authlete への API リクエスト

Authlete から認可サーバーへの API レスポンス

認可サーバーからクライアントへのトークンレスポンス

関連情報