Token Introspection

The OAuth 2.0 Authorization Framework extends its scope with many other speficications. One of these is the OAuth 2.0 Token Introspection (RFC 7662) which defines a protocol that allows authorized protected resources to query the authorization server to determine the set of metadata for a given token that was presented to them by an OAuth 2.0 client.

Client Setup

In order to enable this feature, some configurations must be performed in the Client.

The scope key:token_introspection must be added to the client’s scope.

If OIDC_INTROSPECTION_VALIDATE_AUDIENCE_SCOPE is set to True then:

The client_id must be added to the client’s scope.

Introspection Endpoint

The introspection endpoint (/introspect) is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON document representing the meta information surrounding the token.

The introspection endpoint its called using an HTTP POST request with parameters sent as “application/x-www-form-urlencoded” and Basic authentication (base64(client_id:client_secret).

Parameters:

token
REQUIRED. The string value of an access_token previously issued.

Example request:

curl -X POST \
http://localhost:8000/introspect \
-H 'Authorization: Basic NDgwNTQ2OmIxOGIyODVmY2E5N2Fm' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d token=6dd4b859706944848183d26f2fcb99c6

Example Response:

{
    "aud": "480546",
    "sub": "1",
    "exp": 1538971676,
    "iat": 1538971076,
    "iss": "http://localhost:8000",
    "active": true,
    "client_id": "480546"
}

Introspection Endpoint Errors

In case of error, the Introspection Endpoint will return a JSON document with the key active: false

Example Error Response:

{
    "active": "false"
}