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

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

概要

client_secret_jwt はクライアント認証方式のひとつです。OpenID Connect Core 1.0, 9. Client Authentication にて定義されています。

トークンリクエストにおいて、クライアントはメッセージ認証コード (MAC; Message Authentication Code) を署名部に含む JWT 形式のアサーションを生成し、リクエストに含めます。そして認可サーバーは、そのアサーションの署名とペイロードを検証し、クライアント認証を行います。

アサーションとして送信する JWT には署名・ペイロードに関していくつかの要件が定められており、認可サーバー側ではこの検証を行う必要があります。

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

client-secret-jwt_ja

本機能は Authlete 2.0 以降でのみ利用可能になります。

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 アサーションの生成」のセクションをご覧ください。

ペイロード

下記のうち、必須のクレームを含む必要があります。

クレーム 必須 説明
iss YES この JWT の発行者。値はクライアント ID に一致しなければならない。
sub YES この JWT のサブジェクト。値はクライアント ID に一致しなければならない。
aud YES この JWT の受け取り手。認可サーバーはこの値が適切なものかどうか検証しなければならない。また、この値はトークンエンドポイントの URI であるべきである。
jti YES この JWT の ID
exp YES この JWT の有効期限
iat NO この JWT の発行日時

署名

  • 署名は HMAC-SHA アルゴリズム   (HS256 など) を用いて計算すること
  • 署名計算時にはクライアントシークレット を共通鍵として利用すること

認可サーバー側の処理

認可サーバー側では、リクエストを下記仕様に従って適切に処理することになります。ただし認可サーバーはこれらの処理をすべて Authlete に委譲できる ため、ここでは詳細は割愛します。


 Authlete の設定

本セクションでは client_secret_jwt 方式に対応するための設定を説明します。Authlete サービスと、同方式によって認証されるクライアントの、両方の設定が必要です。

Authlete サービスの設定

管理者コンソールから以下のように設定してください。

タブ 項目 設定内容
認可 サポートするクライアント認証方式 CLIENT_SECRET_JWT を有効化
client-auth-client-secret-jwt_1
認可 タブ

クライアントの設定

クライアントアプリ開発者コンソールにアクセスし、以下のように設定してください。

タブ 項目 設定内容
基本情報 クライアントタイプ CONFIDENTIAL
認可 クライアント認証方式 CLIENT_SECRET_JWT
認可 アサーション署名アルゴリズム HS256 , HS384 , HS512 のいずれか
client-auth-client-secret-jwt_2
基本情報 タブ
client-auth-client-secret-jwt_3
認可 タブ

実行例

q 以下は、認可サーバーのトークンエンドポイントにおいて 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 ライブラリ を利用して JWT を生成する例ですが、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 に、このリクエストの内容を転送します。(見やすさを考慮し一部改行してあります)

$ curl -s -X POST https://api.authlete.com/api/auth/token \
-H 'Content-Type: application/json' \
-u '...:...' \
-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 に記述されているクライアント認証方式のほか、クライアントアサーションやクライアント証明書を用いるクライアント認証方式についても説明します。