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

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

はじめに

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

client_secret_jwt の要件

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

クライアント

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

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

client_assertion の値は、その JWT ペイロードと JWT 署名について以下の要件を満たす必要があります。JWT の例は「JWT アサーションの生成」のセクションで確認できます。

ペイロード

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

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

署名

JWT の署名は HMAC-SHA アルゴリズム（例: HS256）を用いて計算する必要があります。
署名の計算には、共有鍵としてクライアントシークレットを使用する必要があります。

認可サーバー

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

設定

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

サービスの設定

Authlete 管理コンソールで以下の設定を行います。

タブ	項目	値
「サービス設定」>「エンドポイント」>「トークン」	「サポート可能なクライアント認証方式」	“CLIENT_SECRET_JWT” を有効化

Authlete のサービス設定を行うには、以下の手順を実施します。

Authlete 管理コンソールにログインします。
組織名をクリックし、対象のサービスを選択します。
「サービス設定」>「エンドポイント」>「トークン」に移動します。
「サポート可能なクライアント認証方式」セクションで、CLIENT_SECRET_JWT のチェックボックスを選択します。
「変更を保存」をクリックしてサービス設定を更新します。

クライアントの設定

Authlete 管理コンソールで以下の設定を行います。

タブ	項目	値
「基本設定」	「クライアントタイプ」	機密（CONFIDENTIAL）
「エンドポイント」>「トークン」	「クライアント認証方式」	CLIENT_SECRET_JWT
「エンドポイント」>「トークン」	「アサーション署名アルゴリズム」	HS256、HS384、HS512 のいずれか

基本設定を行います。

「クライアント設定」>「基本設定」>「一般」に移動します。
「クライアントタイプ」で「機密」（CONFIDENTIAL）のラジオボタンを選択します。
「変更を保存」をクリックして更新を適用します。

エンドポイントの設定を行います。

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

例

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

JWT アサーションの生成

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

JWT ペイロードの準備

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

{
   "jti": "myJWTId001",
   "sub": "38174623762",
   "iss": "38174623762",
   "aud": "https://as.example.com/token",
   "exp": 1536165540,
   "iat": 1536132708
}

JWT の生成

ペイロードと、クライアントの共有鍵（クライアントシークレット）を用いた MAC を含む JWT アサーションを生成します。以下の例は authlete-jose ライブラリを使用した手順です。あるいは mkjose.org のウェブサイトを利用しても生成できます。

$ bin/jose-generator \
  --payload-file payload.json \
  --sign \
  --signing-alg HS256 \
  --signing-alg-key TzPTZDtcw9ek41H1VmofRoXQddP5cWCXPWidZHSA2spU6gZN9eIFUiXaHD7OfxtBhTxJsg_I1tdFI_CkKl8t8Q

生成される JWT は次のようになります（改行は表示用のものです）。

eyJhbGciOiJIUzI1NiJ9.
ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogIC
Jpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAw
MC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1Mz
YxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
Vin3IxRPMLQ0SKNJ8Ba_59dYHBGLb4Ft-JLbJVKFd3E

この 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=
 eyJhbGciOiJIUzI1NiJ9.
 ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogIC
 Jpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAw
 MC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1Mz
 YxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
 Vin3IxRPMLQ0SKNJ8Ba_59dYHBGLb4Ft-JLbJVKFd3E

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

認可サーバーは、リクエストの内容を Authlete の /auth/token API に転送します。トークンリクエスト内の <Service ID> が、ご自身の Authlete サービス ID と一致していることを確認してください。（可読性のため折り返しています）

curl -v -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 e.g., Xg6jVpJCvsaXvy2ks8R5WzjdMYlvQqOym3slDX0wNhQ>' \
-d '{
  "parameters":"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=
     eyJhbGciOiJIUzI1NiJ9.
     ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogIC
     Jpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAw
     MC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1Mz
     YxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
     Vin3IxRPMLQ0SKNJ8Ba_59dYHBGLb4Ft-JLbJVKFd3E}'

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

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

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

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

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

エンドポイント

トークン & クレーム

鍵管理

メタデータ

Error Handling & Debugging

セキュリティ

クライアント管理

サービス設定

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

はじめに

client_secret_jwt の要件

クライアント

ペイロード

署名

認可サーバー

設定

サービスの設定

クライアントの設定

例

JWT アサーションの生成

JWT ペイロードの準備

JWT の生成

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

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

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

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

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

関連情報

​はじめに

​client_secret_jwt の要件

​クライアント

​ペイロード

​署名

​認可サーバー

​設定

​サービスの設定

​クライアントの設定

​例

​JWT アサーションの生成

​JWT ペイロードの準備

​JWT の生成

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

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

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

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

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

​関連情報

はじめに

client_secret_jwt の要件

クライアント

ペイロード

署名

認可サーバー

設定

サービスの設定

クライアントの設定

例

JWT アサーションの生成

JWT ペイロードの準備

JWT の生成

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

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

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

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

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

関連情報