client_secret_jwt メソッドを使用したクライアント認証

client_secret_jwt メソッドを使用したクライアント認証

序文

client_secret_jwtOpenID Connect Core 1.0, 9. Client Authentication で定義されているクライアント認証方法の1つです。

トークンリクエストでは、クライアントがメッセージ認証コード(MAC)を含む JWT アサーションを作成し、それをリクエストに含めます。その後、認可サーバーがアサーションの署名およびペイロードを検証することでクライアントを認証します。

Authlete は client_secret_jwt をクライアント認証方法としてサポートしており、認可サーバーでこの方法を有効化することができます。本記事では、この方法の概要と Authlete を使用した設定手順について説明します。

client-secret-jwt

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 アサーションには、以下に示す必須のクレームが含まれている必要があります。

クレーム 説明
iss [必須] 発行者。この値は OAuth クライアントの client_id を含む必要があります。
sub [必須] 主体。この値は OAuth クライアントの client_id を含む必要があります。
aud [必須] 対象者。認可サーバーを対象者として識別する値。この値は、トークンの対象者として認可サーバーであることを認証する必要があります。対象者には認可サーバーのトークンエンドポイントの URL を指定します。
jti [必須] JWT ID。トークンの一意の識別子であり、トークンの再利用を防ぐために使用されます。これらのトークンは、当事者間で再利用条件が合意された場合を除き、一度だけ使用されるべきです。
exp [必須] トークンが処理されるべきではない期限時刻。この時刻以降、JWT は受け入れられません。
iat [任意] JWT が発行された時刻。

署名

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

認可サーバー

認可サーバーは、以下にリストされた仕様に従ってトークンリクエストを処理する必要があります。これらの操作は Authlete に委任することが可能 なのでここでは省略します。

設定手順

このセクションでは、client_secret_jwt メソッドを有効化するための設定手順を説明します。Authlete のサービスと、この方法で認証されるクライアントの両方を設定する必要があります。

サービス設定

Service Owner Console で次の設定を行います。

タブ キー
サービス設定 > エンドポイント > トークン サポートされるクライアント認証方法 CLIENT_SECRET_JWT ” を有効にする

Authlete のサービス設定を構成する手順:

  1. Authlete Management Console にログインします。
  2. 組織名をクリックして、サービスを選択します。
  3. サービス設定 > エンドポイント > トークン に移動します。
  4. サポートされるクライアント認証方法 セクションで CLIENT_SECRET_JWT チェックボックスを選択します。
  5. 「変更を保存」をクリックして、サービス設定を更新します。
client-secret-jwt_1

クライアント設定

Authlete Management Console で次の設定を行います。

タブ キー
基本設定 クライアントタイプ CONFIDENTIAL
エンドポイント > トークン クライアント認証方法 CLIENT_SECRET_JWT
エンドポイント > トークン アサーション署名アルゴリズム HS256 , HS384 または HS512

基本設定の構成手順:

  1. クライアント設定 > 基本設定 > 一般 に移動します。
  2. クライアントタイプで 機密 ラジオボタンを選択します。
  3. 「変更を保存」をクリックして更新を適用します。
client-secret-jwt_2

エンドポイント設定の構成手順:

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

このセクションでは、認可サーバーのトークンエンドポイントで client_secret_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
}

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 の値として機能し、クライアントがトークンリクエストを行う際に含められます。

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

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

JWT アサーションを含むクライアントが、以下のようなトークンリクエストを認可サーバーに送信します。(可読性のため一部折りたたみ)

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 レスポンスを認可サーバーに送信します。(可読性のため一部折りたたみ)

{
    "type": "tokenResponse",
    "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” の値を抽出し、クライアントにトークンレスポンスとして送信します。(詳細は省略)


関連リンク

本記事では、Authlete のクライアント認証設定の基本を説明します。

認可サーバーは、private_key_jwt 方式を用いたクライアント認証の処理を、Authlete に移管することができます。本記事ではこの方式の概要と、Authlete の設定手順について説明します。

この記事では、OAuth 2.0 の『クライアント認証 』について説明します。
RFC 6749 に記述されているクライアント認証方式のほか、クライアントアサーションやクライアント証明書を用いるクライアント認証方式についても説明します。