ユーザーがクライアントに付与した認可の取得・変更・取り消し

Table of Contents

ユーザーがクライアントに付与した認可の取得・変更・取り消し

はじめに

本記事では、ユーザーがクライアントに付与した認可の、取得・変更・取り消しを行う API の実行例を紹介します。 これらはたとえば以下の場合に有用です。

  • ユーザー本人が API 事業者（認可サーバー）のサイトにログインし、自分がどのクライアントを認可しているかを確認する
  • API 事業者がユーザーからの依頼に基づいて、特定のクライアントに発行したトークンを削除する
user-centric-token-management_ja

1. ユーザーが認可を付与した（トークンが発行された）クライアント一覧の取得

/client/authorization/get/list API は、ある特定のユーザーが、どのクライアントに対して認可しているか（トークンを発行しているか）を、リストとして取得する APIです。

リクエスト

GET もしくは POST にてリクエストを行います。

GET /api/client/authorization/get/list/<subject>

GET /api/client/authorization/get/list?subject=<subject>

POST /api/client/authorization/get/list
application/x-www-form-urlencoded

POST /api/client/authorization/get/list
application/json

リクエストパラメーターは以下の通りです。

項目 説明
subject ユーザー一意識別子 \*必須
start 検索結果の開始インデックス（デフォルト: 0）
end 検索結果の終了インデックス （デフォルト: 5）
developer 開発者識別子（デフォルト: null）

レスポンス

成功レスポンス

ステータスコード 200 にて、以下のパラメーターを含む JSON が返却されます。

項目 説明
subject ユーザー一意識別子
start 検索結果の開始インデックス
end 検索結果の終了インデックス
developer 開発者識別子
totalCount 該当するクライアントの総数
clients クライアント情報の配列（クライアント情報のフォーマットは /client/get API 等の他の API レスポンスに含まれるクライアント情報と同一）

失敗レスポンス

ステータスコード 400, 403, 500 などにて、以下の JSON が返却されます。

application/json
{
  "resultCode": ...,
  "resultMessage": ...
}

実行例

  • リクエスト

以下はユーザー "testuser01" が認可を付与したクライアント一覧を取得するリクエストの例です。

curl -s -X POST $AL_API/client/authorization/get/list \
-u ...:... \
-H 'Content-type: application/json' \
-d '{"subject":"testuser01"}'
  • レスポンス

clients にクライアント一覧を含むレスポンスが返却されます。

{
   "type": "authorizedClientListResponse",
"clients": [
      {
         "clientId": 17566160603766,
         "clientIdAliasEnabled": false,
         "clientName": "FAPI Client",
         "developer": "authlete_14500880170338"
      }
   ],
   "end": 5,
   "start": 0,
   "totalCount": 1,
   "subject": "testuser01"
}

2. クライアントに付与した認可の範囲（トークンのスコープ）の変更

/client/authorization/update API は、特定のクライアントに発行されているトークンのうち、あるユーザーが認可を付与したものについて、それらのトークンの認可範囲（スコープ）を変更する API です。

リクエスト

POST にてリクエストを行います。URL の一部にクライアント ID (clientId) を指定します。

POST /api/client/authorization/update/<clientId>
application/x-www-form-urlencoded

POST /api/client/authorization/update/<clientId>
application/json

リクエストパラメーターは以下の通りです。

項目 説明
subject ユーザー一意識別子 \*必須
scopes 新しいスコープ群の配列
  • null でない値が指定された場合、それが新しいスコープ群として既存のアクセストークン群にセットされる
  • Content-Type: application/x-www-form-urlencoded でリクエストする場合、scopes の値はスコープ名をスペース区切りで列挙したもの (フォームエンコード後は ‘+’ での区切りとなる) |

レスポンス

ステータスコード 200, 400, 403, 500 などにて、以下の JSON が返却されます。

application/json
{
  "resultCode": ...,
  "resultMessage": ...
}

実行例

  • リクエスト

以下は、クライアント "17566160603766" に発行されているトークンのうち、
ユーザー "testuser01" が認可を付与したものについて、それらのトークンの認可範囲（スコープ）を "payment" に変更するリクエストの例です。

curl -s -X POST $AL_API/client/authorization/update/17566160603766
 \
-u ...:... \
-H 'Content-type: application/json' \
-d '{
    "subject":"testuser01", "scopes":"payment"
   }'
  • レスポンス

アクセストークンが更新されたことを示すレスポンスが返却されます。

{
    "resultCode": "A138001",
    "resultMessage": "[A138001] Updated 4 access token(s)
 issued to the client (ID = 17566160603766) of the service (API Key = ...)."
}

3. クライアントに付与した認可の取消（発行したトークンの削除）

/client/authorization/delete API は、特定のクライアントに発行されているトークンのうち、あるユーザーが認可を付与したものについて、それらのトークンを削除する API です。

リクエスト

DELETE もしくは POST にてリクエストを行います。URL の一部にクライアント ID (clientId) を指定します。

DELETE /api/client/authorization/delete/<clientId>/<subject>

DELETE /api/client/authorization/delete/<clientId>?subject=<subject>

POST /api/client/authorization/delete/<clientId>
application/x-www-form-urlencoded

POST /api/client/authorization/delete/<clientId>
application/json

リクエストパラメーターは以下の通りです。

項目 説明
subject ユーザー一意識別子 \*必須

レスポンス

ステータスコード 200, 400, 403, 500 などにて、以下の JSON が返却されます。

application/json
{
  "resultCode": ...,
  "resultMessage": ...
}

実行例

  • リクエスト

以下は、クライアント "17566160603766" に発行されているトークンのうち、
ユーザー "testuser01" が認可を付与したものについて、それらを削除するリクエストの例です。

curl -s -X POST $AL_API/client/authorization/delete/17566160603766
 \
-u ...:... \
-H 'Content-type: application/json' \
-d '{
    "subject":"testuser01"
   }'
  • レスポンス

アクセストークンが削除されたことを示すレスポンスが返却されます。

{
   "resultCode": "A137001",
   "resultMessage": "[A137001] Deleted 4 access token(s)
 issued to the client (ID = 17566160603766) of the service (API Key = ...)."
}