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

概要


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






client_secret_jwt とは


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

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

アサーションとして送信する 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 を有効化

クライアントの設定


クライアントアプリ開発者コンソールにアクセスし、以下のように設定してください。
タブ
項目
設定内容
基本情報
クライアントタイプ
CONFIDENTIAL
認可
クライアント認証方式
CLIENT_SECRET_JWT
認可
アサーション署名アルゴリズム
HS256, HS384, HS512 のいずれか
基本情報 タブ


認可 タブ

実行例


以下は、認可サーバーのトークンエンドポイントにおいて 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
に記述されているクライアント認証方式のほか、クライアントアサーションやクライアント証明書を用いるクライアント認証方式についても説明します。
How did we do with this article?