Resource access with access token

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.

 
Example

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:

 
Example

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.
 
Example

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.
 
Example

Token introspection response

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