Checking if an access token has particular scopes

Overview

Authlete’s /auth/introspection API has a feature that checks if an access token for introspection has particular token. You can specify the scopes as values of an array, in a request to the API.

Checking scopes associated with a token

Here we assume there is an “Order API” in a resource server. It checks an access token attached with a request to the API and processes the request at least when the token has a payment scope.

With Authlete’s /auth/introspection API, you have two implementation options:

1. The resource server sends only the access token to /auth/introspectionAPI, to get “a list of scopes associated with the token” and determine if it has the payment scope

2. The resource server sends “scopes that the token must have” along with the access token to /auth/introspection API, and gets a response that states if the token is valid

The latter option relatively reduces the complexity of resource server implementation as Authlete manages to check the existence of the scopes.

How to use

/auth/introspection API can accept “scopes” parameter. You can use it to check if an access token that is a value of “token” parameter covers particular scopes that are specified the “scopes” parameter.

The “scopes” parameter is an array. It includes each scope as a value. For example, you can check if an access token covers “account” and “payment” scopes by describing them as follows:

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

Note that the following example doesn’t work as expected.

"scopes": ["account payment"]

Authlete would recognize this value as a single scope, “account payment”, that doesn’t actually exist, and understand no values are specified for the scopes parameter:

"scopes": []

As a result, Authlete would do nothing in terms of checking scopes.

Examples

The following request/response examples show how to check if an access token (MhVD…) with three scopes (openid , profile , and payment ) has particular scopes. curl command is used for the examples. (folded for readability)

When it has particular scopes

• Request

The request is made to check if the token has openid and payment   scopes.

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

• Response

Authlete sends back a successful response as the token is valid.

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

When it doesn’t have particular scopes

• Request

The request is made to check if the token has openid and email   scopes.

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

• Response

Authlete sends back an error response as the token that doesn’t have the email scope is not valid.

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