クライアント ID の「別名」の利用

Table of Contents

クライアント ID の「別名」の利用

概要

Authlete の「クライアント ID 別名 (Client ID Alias)」機能を利用すると、各クライアントに対し、自動生成された値とは別のクライアント ID を割り当てることが可能です。既存の認可システムを Authlete に移行する際の、クライアントやリソースサーバーの改修の最小化に有用です。

Authlete におけるクライアント ID

Authlete では、クライアントの「クライアント ID (client_id)」の値は、Authlete がランダムな数値を自動生成し、クライアント情報として登録します。そしてクライアントはその値（以下「新 ID」）を、認可サーバーへのリクエストパラメーターのひとつとして用いることになります。

一方、たとえば既存の認可サーバーがあり、クライアント ID の値（以下「旧 ID」）が登録済みである環境では、認可サーバーをAuthlete ベースに移行する際、クライアント側でも「旧 ID」から「新 ID」への入れ替えが必要となります。この作業は、クライアント数や種類によっては煩雑となるかもしれません。

また、リソースサーバーが既存認可サーバーの「旧 ID」の体系に依存している環境では、移行後に Authlete のアクセストークンから導出される「新 ID」を「旧 ID」に変換するしくみが必要となるかもしれません。

クライアント ID 別名

前述の課題を解決するのが「クライアント ID 別名 (Client ID Alias)」機能です。同機能を有効化すると、クライアントに対し、任意の文字列から成る「旧 ID」を、自動生成された「新 ID」とは別に割り当てられるようになります。

「クライアント ID 別名」機能は、クライアントからは透過的に動作します。クライアントは、認可リクエストやトークンリクエストの client_id リクエストパラメーター、あるいはトークンリクエストの Authorization ヘッダーに埋め込む値など、クライアント ID を用いるさまざまな場面で、「旧 ID」をそのまま使用できます。

またリソースサーバーは、トークンイントロスペクションの結果として、Authlete から「旧 ID」を取得できます。これにより、「旧 ID」の体系に基づく処理が可能となります。

client-id-alias_ja

設定方法

この設定を有効にするためには、サービス、クライアントの双方で『有効』を選択する必要があります。サ―ビス側またはクライアント側のどちらか一方でもこの設定項目が無効になっている場合、クライアント ID の別名は認識されないので注意してください。

Authlete サービスの設定

「基本情報」タブの「Client ID の別名有効化」にて、「有効」を選択します。

client-id-alias_2

クライアントの設定

「基本情報」タブの「Client ID の別名有効化」にて、「有効」を選択します。また同じく「Client ID の別名」にて、クライアント ID の別名として割り当てる値を入力します。

client-id-alias_3

実行例

認可リクエスト

以下は、本来のクライアント ID (1720…) ではなく、クライアント ID 別名 (“clientapp01”) を含む認可リクエストを、curl を用いて Authlete の /auth/authorization API に送信する例です。Authlete が、クライアントの指定したクライアント ID 別名を受け入れ、リクエストを処理したことがわかります。（読みやすさのために一部折り返しています）

  • リクエスト
curl -s -X POST .../auth/authorization
 -u $apiKey:$apiSecret
 -H 'Content-type: application/json'
 -d '{"parameters":
        "redirect_uri=https://client.example.org/cb/example.com
　　　   &client_id=clientapp01
        &scope=payment
        &response_type=code"}'
  • レスポンス
{
  "type": "authorizationResponse",
  "resultCode": "A004001",
  "resultMessage":
    "[A004001] Authlete has successfully issued a ticket
     to the service (API Key = 1415...) for the
     authorization request from the client (ID = 1720...).
     [response_type=code, openid=false]",
  "action": "INTERACTION",
  "client": {
    "clientId": 1720...,
    "clientIdAlias": "clientapp01",
    "clientIdAliasEnabled": true,
...

トークンリクエスト

以下は、本来のクライアント ID (1720…) ではなく、クライアント ID 別名 (“clientapp01”) を Authorization ヘッダーに含むトークンリクエストを、curl を用いて Authlete の /auth/token API に送信する例です。（読みやすさのために一部折り返しています）

  • リクエスト
curl -s -X POST .../auth/token  -u $apiKey:$apiSecret
-H 'Content-type: application/json'
-d '{"clientId":"clientapp01",
    "clientSecret":"...",
    "parameters":
        "redirect_uri=https://client.example.org/cb/example.com
        &grant_type=authorization_code
        &code=6GXV..."}'
  • レスポンス
{
  "type": "tokenResponse",
  "resultCode": "A050001",
  "resultMessage":
    "[A050001] The token request (grant_type=authorization_code)
     was processed successfully.",
  "accessToken": "55Sp...",
  "action": "OK",
  "clientId": 17201083166161,
  "clientIdAlias": "clientapp01",
  "clientIdAliasUsed": true,
  "refreshToken": "xDcV...",
  "responseContent":
    "{\"access_token\":\"55Sp...\",
      \"refresh_token\":\"xDcV...\",
      \"scope\":\"payment\",
      \"token_type\":\"Bearer\",
      \"expires_in\":300}",
  "scopes": [
    "payment"
  ],
  "subject": "testuser01"
}

なお JWT ベースのアクセストークン を有効化した場合には、アクセストークンのペイロード部に、「クライアント ID 別名」が以下のような形式にて含まれます。

{
    "sub": "testuser01",
    "scope": "payment",
    "iss": "https://authlete.com",
    "exp": 1594...,
    "iat": 1594...,
    "client_id": "clientapp01",
    "jti": "IRBq..."
}

トークンイントロスペクション

以下は、トークンの状態チェックおよび関連情報の取得を、curl を用いて Authlete の /auth/introspection API に送信する例です。Authlete が、アクセストークンにひもづくクライアント ID 別名を返却しています。（読みやすさのために一部折り返しています）

  • リクエスト
curl -s -X POST .../auth/introspection \
  -u $apiKey:$apiSecret \
  -H 'Content-type: application/json' \
  -d '{"token":"55Sp..."}'
  • レスポンス
{
  "type": "introspectionResponse",
  "resultCode": "A056001",
  "resultMessage": "[A056001] The access token is valid.",
  "action": "OK",
  "clientId": 1720...,
  "clientIdAlias": "clientapp01",
  "clientIdAliasUsed": true,
  "existent": true,
  "expiresAt": 1594632489000,
  "refreshable": true,
  "responseContent": "Bearer error=\"invalid_request\"",
  "scopes": [
    "payment"
  ],
  "subject": "testuser01",
  "sufficient": true,
  "usable": true
}