アクセストークンがカバーするスコープの確認

概要

Authlete の /auth/introspection API には、イントロスペクション対象のアクセストークンが特定のスコープを持つかどうかを確認する機能があります。確認する際には、同 API に対し、スコープを配列の値として指定します。

トークンが持つスコープのチェック

たとえば、あるリソースサーバーの「注文 API」では、その API に対するリクエストに付与されたアクセストークンをチェックし、少なくとも payment スコープを持つ場合のみ処理を進めるとしましょう。

Authlete の /auth/introspection API を用いる場合、2 つの実現方法があります。

1. /auth/introspection API にアクセストークンのみを送信し、そのレスポンスとして取得できる「トークンが持つスコープ一覧」をチェックし、payment スコープの有無を確認

2. /auth/introspection API に対し、アクセストークンとともに「そのトークンが持つべきスコープ」として payment スコープを指定して送信し、その上でトークンが有効かどうかをレスポンスとして取得

後者の方法では、スコープの有無を Authlete が判断するようになるため、リソースサーバーの実装を比較的シンプルにできます。

利用方法

/auth/introspection API を呼び出す際に scopes パラメーターを用いると、「token パラメーターで渡されたアクセストークン」が「scopes パラメーターで指定されたスコープ群」をカバーしているかどうかをチェックできます。

scopes パラメーターは配列であり、各スコープを値として記述します。たとえば account と payment の 2 つのスコープがカバーされているかどうかをチェックするためには以下のような表記になります。

"scopes": ["account","payment"]

なお、以下のような表記ではないことにご注意ください。

"scopes": ["account payment"]

もしこのように指定された場合、Authlete はこれを「“account payment”」という一つのスコープであると認識します。そして「“account payment”」は存在しないため、結果として以下と同等に解釈します。

"scopes": []

その結果、scopes リクエストパラメーターを指定していないのと同じような動作になり、スコープに関するチェックは行われません。

実行例

以下は、openid , profile , そして payment の 3 種類のスコープを持つアクセストークン (MhVD…) について、特定のスコープの有無を確認する例です。ここでは curl を用いてリクエスト・レスポンスを実行しています（読みやすさのため折り返しています）。

特定のスコープが付与されている場合

• リクエスト

openid および payment スコープの有無を確認します。

curl -s -X POST .../auth/introspection \
     -u $apiKey:$apiSecret \
     -H 'Content-type: application/json' \
     -d '{"token":"MhVD...","scopes": ["openid","payment"]
}'

• レスポンス

アクセストークンは有効であると判断し、成功レスポンスを返却します。

{
   "type": "introspectionResponse",
   "resultCode": "A056001",
   "resultMessage": "[A056001] The access token is valid.",
   "action": "OK",
   "clientId": ...,
   "expiresAt": ...,
   "responseContent": "Bearer error=\"invalid_request\"",
   "scopes": [
     "openid",
     "profile",
     "payment"
   ],
   "subject": "testuser01",
   ...
}

特定のスコープが付与されていない場合

• リクエスト

openid および email スコープの有無を確認します。

curl -s -X POST .../auth/introspection  -u $apiKey:$apiSecret  \
-H 'Content-type: application/json'  \
-d '{"token":"MhVD...","scopes":["openid","email"]
}'

• レスポンス

アクセストークンには email スコープが無いため、有効ではないと判断し、エラーレスポンスを返却します。

{
  "type": "introspectionResponse",
  "resultCode": "A064302",
  "resultMessage":
    "[A064302] The access token does not cover the required scope 'email'.",
  "action": "FORBIDDEN",
  "clientId": ...,
  "expiresAt": ...,
  "responseContent":
    "Bearer error=\"insufficient_scope\",
     error_description=\"[A064302] The access token does not cover
       the required scope 'email'.\",
     error_uri=\"https://docs.authlete.com/#A064302\",
     scope=\"openid email\"",
  "scopes": [
    "openid",
    "profile",
    "payment"
  ],
  "subject": "testuser01",
...
}