Table of Contents

クライアント認証の設定

はじめに

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

Authlete におけるクライアント認証のしくみ

Authlete では、事前設定する情報と、実行時に得られる情報に基づき、トークンリクエスト処理 (/auth/token API ) におけるクライアント認証を行います。

事前設定する情報

事前設定は、Authlete サービス（認可サーバーのバックエンドとして機能する API インスタンス）と、そのサービス内のクライアントの双方に対して行います。

Authlete サービス

認可サーバーが、どのクライアント認証方式をサポートするかを設定します。複数の方式を同時に有効化できます。

クライアント

サービスに登録されている（認可サーバーに接続する）クライアントが、どのクライアント認証方式を用いるかを指定します。また場合により、その認証に必要な情報（クライアントの公開鍵や、クライアント証明書のサブジェクト名など）も同時に設定します。

実行時に得られる情報

クライアントからトークンリクエストを受け取った認可サーバーは、そのリクエストの内容を Authlete の /auth/token API に渡し、処理を移管します。Authlete はその内容から、リクエストの送信元であるクライアントを判別し、どの認証方式を用いるかを確定して、クライアント認証を行います。

認証方式によっては、クライアントから認可サーバーへの、HTTP リクエストに含まれる Authorization ヘッダーの値や、両者間の相互 TLS 接続におけるクライアント証明書などが、クライアント認証処理に必要となります。認可サーバーはこれらの情報を HTTP リクエストや相互 TLS 接続から抽出し、トークンリクエストの内容とともに Authlete へ送信します。

設定例

以下は、あるクライアント (クライアント ID: 1257... ) に対して、クライアント認証方式として CLIENT_SECRET_BASIC を設定し、トークンリクエストを処理する例です。

client-authentication-client-secret-basic_ja

事前設定 (ステップ 0 ) では以下の設定を行います。

まずサービス管理者は管理者コンソールにログインし、対象の Authlete サービス (この場合 “Service A”) の「サポートするクライアント認証方式」において、CLIENT_SECRET_BASIC のサポートを有効にします。
一方のクライアント担当者は開発者コンソールにログインし、対象のクライアントについて、クライアント認証方式として CLIENT SECRET_BASIC を指定します。
CLIENT_SECRET_BASIC の場合、クライアントが認証を受けるために必要な情報はクライアント ID とクライアントシークレットのみです。Authlete では、これらの情報は自動的に生成されます（本例ではそれぞれ “1257... ”、“gTyu... ” となっています）。クライアント担当者はそれらの自動生成された値をクライアントに設定します。

トークンリクエストの処理 (ステップ 1~4) は以下のように行われます。

ステップ 1

クライアントは認可サーバーへトークンリクエストを送信します。このとき、クライアント認証に必要なクライアント ID (1257... ) とクライアントシークレット (gTyu... ) を、HTTP リクエストの Authorization ヘッダーにセットします。

POST /token HTTP/1.1
Authorization: Basic base64(1257...: gTyu...)
Host: as.example.com
...
grant_type=authorization_code&
code=...&
redirect_uri=...

ステップ 2

認可サーバーはリクエストのボディから、トークンリクエストの実質的な内容を取得します。同時に HTTP ヘッダーの Authorization ヘッダーから、クライアント ID とクライアントシークレットの値を抽出します。

Item	Value
Content of token request	grant_type=authorization_code& code=…& redirect_uri=…
Client ID	1257…
Client secret	gTyu…

ステップ 3

認可サーバーは Authlete の /auth/token API にリクエストを送信します。このときリクエストには、ステップ 2 で取得した情報である、トークンリクエストの内容、クライアント ID、クライアントシークレットを、それぞれ “parameters”, “clientId”, “clientSecret” パラメーターとして含めます。

POST /api/auth/token HTTP/1.1
Host: api.authlete.com
...

{
  "clientId":"1257...",
  "clientSecret":"gTyu...",
  "parameters":
    "grant_type=authorization_code
     &code=...&redirect_uri=..."
}

ステップ 4

Authlete は API リクエストに含まれるクライアント ID から、トークンリクエストの送信元のクライアントを特定します。

そして、そのクライアントに指定されているクライアント認証方式が CLIENT_SECRET_BASIC であることを認識し、クライアントシークレットの値を確認して、クライアント認証の成否が決定されることになります。

主なクライアント認証方式の設定のポイント

Authlete サービスのクライアント情報として事前に設定が必要な情報、およびトークンリクエストを受信した認可サーバーの処理内容は、クライアント認証方式によって異なります。ここでは主要な方式について、設定のポイントを紹介します。

CLIENT_SECRET_BASIC

前述の通り、クライアント ID とクライアントシークレットを、クライアントがトークンリクエストの Authorization ヘッダーに指定して送信する方式です。

Authlete の設定
- このクライアント認証方式に必要となるクライアント ID とクライアントシークレットは、Authlete が自動的に生成・管理するため、Authlete への追加設定は不要です。
認可サーバーの設定
- Authorization ヘッダーからこれらの情報を抽出し、/auth/token API へのリクエストのパラメーターとして別途指定します。

CLIENT_SECRET_POST

クライアント ID とクライアントシークレットを、クライアントがトークンリクエストのパラメーターとして付加し送信する方式です。

Authlete の設定
- CLIENT_SECRET_BASIC の場合と同じく、Authlete への追加設定は不要です。
認可サーバーの設定
- クライアント ID とクライアントシークレットがトークンリクエスト自体に含まれるため、これらの情報に関する処理は不要です。

CLIENT_SECRET_JWT

クライアントが、クライアントシークレットをもとにしたメッセージ認証コード (MAC) を含む「JWT アサーション」を生成し、それをトークンリクエストのパラメーターとして付加し送信する方式です。

Authlete の設定
- クライアントシークレットは Authlete が自動的に生成・管理しますが、別途新たに指定する必要がある Authlete のクライアント情報として、JWT アサーションの「アサーション署名アルゴリズム」があります。
認可サーバーの設定
- JWT アサーションがトークンリクエスト自体に含まれるため、これらの情報に関する処理は不要です。

詳細は記事「client_secret_jwt によるクライアント認証」をご参照ください。

PRIVATE_KEY_JWT

公開鍵暗号方式による署名を含む「JWT アサーション」を生成し、トークンリクエストのパラメーターとしてクライアントが指定する方式です。

Authlete の設定
- Authlete のクライアント情報として、クライアントが送信する JWT の「アサーション署名アルゴリズム」を指定し、またクライアントの公開鍵を事前に登録する必要があります。
認可サーバーの設定
- JWT アサーションがトークンリクエスト自体に含まれるため、これらの情報に関する処理は不要です。

詳細は記事「private_key_jwt によるクライアント認証」をご参照ください。

TLS_CLIENT_AUTH

クライアントと認可サーバーとの間に相互 TLS 接続を確立し、その接続から取得したクライアント証明書をもとに、クライアント認証を行う方式です。

Authlete の設定
- Authlete のクライアント情報として、クライアント証明書の「サブジェクト名」を事前に登録する必要があります。
認可サーバーの設定
- 相互 TLS 接続からクライアント証明書を抽出し、/auth/token API へのリクエストのパラメーターとして別途指定します。

詳細は記事「tls_client_auth によるクライアント認証」をご参照ください。