> ## 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.
# private_key_jwt によるクライアント認証
> クライアント認証における private_key_jwt の処理と Authlete の設定手順について紹介します。
For **Authlete 2.x** documentation, see [2.x version](/ja/v2/configuration-reference/endpoints/client-authentication-using-private-key-jwt-method).
## はじめに
**private\_key\_jwt** は、[OpenID Connect Core 1.0, 9. Client Authentication](http://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
で定義されているクライアント認証方式のひとつです。
トークンリクエストにおいて、クライアントはデジタル署名された 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-アサーションの生成)
」のセクションを参照してください。
### ペイロード
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 にオフロードできる**ため、ここでは詳細を省略します。
* [JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC7523)](https://tools.ietf.org/html/rfc7523)
* [Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants (RFC7521)](https://tools.ietf.org/html/rfc7521)
***
## 設定
このセクションでは、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" として保存します。
```json theme={null}
{
"jti": "myJWTId001",
"sub": "38174623762",
"iss": "38174623762",
"aud": "http://localhost:4000/api/auth/token/direct/24523138205",
"exp": 1536165540,
"iat": 1536132708
}
```
### JWK セットの準備
次に、署名と検証のための JWK セットを準備します。ここでは [mkjwk.org](https://mkjwk.org/)
を使って JWK セットを生成します。
以下の例は `ES256` アルゴリズムを用いて生成したもので、「公開鍵と秘密鍵のペア」を "key\_pair.jwk" というファイルに保存しています。
後者の「公開鍵のみ」を Authlete に登録し、「クライアント認証方式」（PRIVATE\_KEY\_JWT）と Client Assertion Algorithm（ES256）を設定してください。これらは前のセクションで説明したとおりクライアント設定から行えます。
* 「公開鍵と秘密鍵のペア」
```json theme={null}
{
"kty": "EC",
"d": "ukQKQexNI8PtEv7SKpqUDnbZ-WkN6HaQqcVrVV8ZWRQ",
"use": "sig",
"crv": "P-256",
"x": "9Yxd2TvwBbgmupZh3bpg3umKihM_FNAk2_uI_-Edv_Q",
"y": "BOUFuyvWoBZ9-RVSeHJLF-L4I3ORv0xbaM1CKCFJr54",
"alg": "ES256"
}
```
* 「公開鍵」（クライアント設定として Authlete に登録するもの）
```json theme={null}
{
"kty": "EC",
"use": "sig",
"crv": "P-256",
"x": "9Yxd2TvwBbgmupZh3bpg3umKihM_FNAk2_uI_-Edv_Q",
"y": "BOUFuyvWoBZ9-RVSeHJLF-L4I3ORv0xbaM1CKCFJr54",
"alg": "ES256"
}
```
### JWT の生成
ペイロードを含み、秘密鍵で署名した JWT アサーションを生成します。以下の例は [authlete-jose library](https://github.com/authlete/authlete-jose)
を使った手順です。または [mkjose.org](https://mkjose.org/)
のウェブサイトを使って行うこともできます。
```bash theme={null}
bin/jose-generator \
--payload-file payload.json \
--sign \
--signing-alg ES256 \
--jwk-signing-alg-file key_pair.jwk
```
生成される JWT は次のようになります（表示のための改行のみ挿入しています）。
```plaintext theme={null}
eyJhbGciOiJFUzI1NiJ9.
ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiL
AogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbG
hvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAo
gICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
YB4gdhWUGRjWEsEbKDs7-G2WFH2oYz7bAEP5AtegHXInkY9ncA2V3IoA6O_HV
QuFxyCRIklrxsMk32MfNF_ABA
```
この JWT が `client_assertion` の値となり、クライアントがトークンリクエストを行う際に使用します。
## トークンリクエストとレスポンス
### クライアントから認可サーバーへのトークンリクエスト
アサーションを持つクライアントが認可サーバーへトークンリクエストを行うとします。（可読性のため折り返しています）
```plaintext theme={null}
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](/api-reference/token-endpoint/process-token-request) に転送します。（可読性のため折り返しています）
```bash theme={null}
$ curl -s -X POST https://us.authlete.com/api//auth/token \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-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 レスポンスを認可サーバーに返します。（可読性のため折り返しています）
```json theme={null}
{
"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" の値を取り出し、トークンレスポンスとしてクライアントに返します（詳細は省略）。
## 関連情報
* [クライアント認証の設定](/ja/configuration-reference/endpoints/configuring-client-authentication)
> この記事では、Authlete におけるクライアント認証設定の基本を説明しています。
* [client\_secret\_jwt によるクライアント認証](/ja/configuration-reference/endpoints/client-authentication-using-client-secret-jwt-method)
> Authlete は、認可サーバーが有効化できるよう、**client\_secret\_jwt** をクライアント認証方式としてサポートしています。この記事では、この方式の概要と Authlete における設定手順を説明します。
* [OAuth 2.0 Client Authentication - Takahiko Kawasaki - Medium](https://medium.com/@darutk/oauth-2-0-client-authentication-4b5f929305d4)
> この記事では「**OAuth 2.0 のクライアント認証**」について解説しています。[RFC 6749](https://tools.ietf.org/html/rfc6749)
> で説明されているクライアント認証方式に加えて、client assertion と client certificate を利用する方式についても解説しています。