アクセストークンのスコープの照会

概要

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

トークンが持つスコープの照会

たとえば、あるリソースサーバーの「注文 API」では、その API に対するリクエストに付与されたアクセストークンが少なくとも payment スコープを持つ場合のみ、処理を進めるとしましょう。 Authlete の Process Introspection Request API を用いる場合、2 つの実現方法があります。

アクセストークンのみを API に送信し、そのレスポンスとして取得できる「トークンが持つスコープ一覧」をチェックし、payment スコープの有無を確認
アクセストークンとともに「そのトークンが持つべきスコープ」として payment スコープも併せて API に送信し、その上でトークンが有効かどうかをレスポンスとして取得

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

checking-scopes-associated-with-token_ja

利用方法

Process Introspection Request API を呼び出す際に scopes パラメーターを用いると、「token パラメーターで渡されたアクセストークン」が「scopes パラメーターで指定されたスコープ群」をカバーしているかどうかをチェックできます。 scopes パラメーターは配列であり、各スコープを値として記述します。たとえば account と payment の 2 つのスコープがカバーされているかどうかをチェックするためには以下のような表記になります。

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

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

"scopes": ["account payment"]

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

"scopes": []

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

実行例

以下は、あるアクセストークン (MhVD...) について、特定のスコープの有無を照会する例です。このアクセストークンは以下の 3 種類のスコープを持つとします。

openid
profile
payment

照会したスコープが指定されている場合

openid および payment スコープの有無を照会するには、以下の API リクエストを送信します。ここでは curl を用いてリクエスト・レスポンスを実行しています（読みやすさのため折り返しています）。

curl -s -X POST "https://us.authlete.com/api/${SERVICE_API_KEY}/auth/introspection" \
     -H "Authorization: Bearer ${SERVICE_ACCESS_TOKEN}" \
     -H 'Content-type: application/json' \
     -d '{
       "token":"MhVD...",
       "scopes": ["openid","payment"]
     }'

Authlete は、アクセストークンが有効であると判断し、以下の API レスポンスを返却します。

{
   "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 スコープの有無を照会するには、以下の API リクエストを送信します。

curl -s -X POST "https://us.authlete.com/api/${SERVICE_API_KEY}/auth/introspection" \
     -H "Authorization: Bearer ${SERVICE_ACCESS_TOKEN}" \
-H 'Content-type: application/json'  \
-d '{
  "token":"MhVD...",
  "scopes":["openid","email"]
}'

当該アクセストークンは email スコープを持ちません。そのため、Authlete はそのアクセストークンは有効ではないと判断し、エラーの API レスポンスを返却します。

{
  "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",
...
}

エンドポイント

トークン & クレーム

鍵管理

メタデータ

エラー処理とデバッグ

セキュリティ

クライアント管理

サービス設定

アクセストークンのスコープの照会

概要

トークンが持つスコープの照会

利用方法

実行例

照会したスコープが指定されている場合

照会したスコープが指定されていない場合

​概要

​トークンが持つスコープの照会

​利用方法

​実行例

​照会したスコープが指定されている場合

​照会したスコープが指定されていない場合

概要

トークンが持つスコープの照会

利用方法

実行例

照会したスコープが指定されている場合

照会したスコープが指定されていない場合