OAuth 2.0 doesn’t define a standard API for communication between the resource server and the authorization server. As a result, vendor-specific, proprietary APIs have crept in to couple the resource server to the authorization server. The Token Introspection profile for OAuth 2.0 fills this gap by proposing a standard API to be exposed by the authorization server, allowing the resource server to talk to it and retrieve token metadata.
OAuth 2.0 Token Introspection Internet draft is available at https://datatracker.ietf.org/doc/draft-richer-oauth-introspection/.
A token-introspection request can be generated by any party in possession of the access token. The introspection endpoint can be secured with HTTP Basic Authentication:
POST /introspection HTTP/1.1
Accept: application/x-www-form-urlencoded
Host: authz.server.com
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
token=X3241Affw.4233-99JXJ&token_type_hint=access_token&resource_id=http://my-resource
Let’s have a look at the definition of each parameter.
HTTP/1.1 200 OK
Content-Type: application/json Cache-Control: no-store
{
"active": true,
"client_id":"s6BhdRkqt3",
"scope": "read write dolphin",
"sub": "2309fj32kl",
"aud": " http://my-resource/*
}
Let’s have a look at the definition of each parameter.
While validating the response from the introspection endpoint, the resource server should first check whether the value of active is set to true. Then it should check whether the value of aud in the response matches the aud URI associated with the resource server or the resource. Finally, it can validate the scope. The required scope to access the resource should be a subset of the scope values returned in the introspection response. If the resource server wants to do further access control based on the client or the resource owner, it can do so with respect to the values of sub and client_id.
More details and the applications of the OAuth 2.0 Token Introspection Profile are covered in my book Advanced API Security.
OAuth 2.0 Token Introspection Internet draft is available at https://datatracker.ietf.org/doc/draft-richer-oauth-introspection/.
A token-introspection request can be generated by any party in possession of the access token. The introspection endpoint can be secured with HTTP Basic Authentication:
POST /introspection HTTP/1.1
Accept: application/x-www-form-urlencoded
Host: authz.server.com
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
token=X3241Affw.4233-99JXJ&token_type_hint=access_token&resource_id=http://my-resource
Let’s have a look at the definition of each parameter.
- token: The value of the access-token
- token_type_hint: The type of the token (either the access_token or the refresh_token)
- resource_id: An identifier that represents the corresponding resource for introspection
HTTP/1.1 200 OK
Content-Type: application/json Cache-Control: no-store
{
"active": true,
"client_id":"s6BhdRkqt3",
"scope": "read write dolphin",
"sub": "2309fj32kl",
"aud": " http://my-resource/*
}
Let’s have a look at the definition of each parameter.
- active: Indicates whether the token is active. To be active, the token should not be expired or revoked. The authorization server can define its own criteria for how to define active.
- client_id: The identifier of the client to which the token was issued.
- scope: Approved scopes associated with the token.
- sub: The subject identifier of the user who approved the authorization grant.
- aud: The allowed audience for the token.
While validating the response from the introspection endpoint, the resource server should first check whether the value of active is set to true. Then it should check whether the value of aud in the response matches the aud URI associated with the resource server or the resource. Finally, it can validate the scope. The required scope to access the resource should be a subset of the scope values returned in the introspection response. If the resource server wants to do further access control based on the client or the resource owner, it can do so with respect to the values of sub and client_id.
More details and the applications of the OAuth 2.0 Token Introspection Profile are covered in my book Advanced API Security.