Resource access with token usage

Use Case Scenario

  • This scenario demonstrates the following use case:
  • A client accesses a resource and provides a valid access token
  • The resource inspects the access token

In this example, Airlock IAM acts as both an authorization and resource server.

The ordering of the steps in this example is incorrect, but to keep the request and response close to each other, the response to the resource access is shown immediately after the request instead of first inspecting the access token.

Step 1 – Resource access

For the purpose of this example, we use the resource's endpoint to retrieve a resource called rbac. This resource will return a JSON object containing the email and the user's roles. In a real-world example, this might be an ebanking server that is requested to return a list of accounts of the user identified in the access token.

To authorize the call, we must supply an access token as a bearer token in the Authorization header.

Resource access request

GET https://oidc.airlock.com/auth-login/rest/oauth2/authorization-servers/myAS/resources/rbac

This request will, after successful token introspection, receive the following response:

Resource access response

200 OK
 {
     "email": "john.doe@ergon.ch",
     "role": [
         "customer"
    ] 
} 

Step 2 – Token Introspection

Before returning the response to the resource access in Step 1, the resource will inspect the access token provided.

  • To this end, the resource will query the token introspection endpoint with a request:
  • The resource server uses its credentials when querying the token introspection endpoint.
  • The credentials of the resource server are supplied using basic_auth in the authorization header and are configured as part of the token introspection endpoint.
  • The resource server provides the access token to be inspected as an x-www-form-urlencoded value.

Token Introspection request

POST https://oidc.airlock.com/rest/oauth2/authorization-servers/myAS/introspect
 Content-Type: application/x-www-form-urlencoded
 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ

  token=eyJraWQiOiI...izyE7sDxw

This request will receive the following response if the access token supplied is valid.

  • The following elements in the response are noteworthy:
  • Token introspection will return the username in the sub-parameter.
  • Token introspection will return the scope, as it was granted after consent and applying the whitelist.
  • Token introspection will return the identifier of the client that obtained the access token from the authorization server.

Token introspection response

200 OK
 {
     "sub": "jdoe",
     "scope": "ebanking",
     "active": true,
     "exp": 1599502326,
     "iat": 1599484326,
     "client_id": "oidc-client"
 }