The token_introspect endpoint is described in the OAuth2 specification:

OAuth 2.0 Token Introspection

While the OIDC specification defines the format for the OIDC ID Token (see also ID Token), the Access Token and Refresh Token are based on the OAuth2 specification.

In OAuth2 the contents of tokens are opaque to clients, and OIDC has not defined the token formats for these tokens the same way as it has done for the ID Token.

However, there is still a large amount of metadata that may be attached to a token, such as its current validity, approved scopes, and information about the context in which the token was issued. In fact, the OAuth2 specification opens up for tokens that carry information both by value and by reference.

Token introspection allows a protected resource to query this information regardless of whether or not it is carried in the token itself, allowing this method to be used along with or independently of structured token values.

The introspection endpoint is an endpoint that takes a parameter representing a token and returns a JSON document representing the meta information surrounding the token, including whether this token is currently active.

Endpoint URL

The token_introspect endpoint URL can be found by looking at the value of the "token_introspect_endpoint" key in the openid-configuration.

Typical format of the URL is:

Token Introspect Endpoint URL - Example format

https://auth.buypass.no/auth/realms/SECURITYDOMAIN/protocol/openid-connect/token/introspect

Introspection Request

The client calls the introspection endpoint using an HTTP POST request with parameters sent as "application/x-www-form-urlencoded".

Note that the endpoint requires client authentication.

Parameter

Required

Description

Example

token

yes

The string value of the token.

For access tokens, this is the "access_token" value returned from the token endpoint.

For refresh tokens, this is the "refresh_token" value returned from the token endpoint

ID Tokens are not supported as they are out of scope according to the spesification. Use the OIDC ID Token spesification for decoding.

token=eyJhbGciOiJSUzI1NiIsInR5...

token_type_hint

no

A hint about the type of the token submitted for introspection. Values according to Initial Registry Contents.

token_type_hint=access_token

Example request

Example request using curl

BASEURL="https://auth.buypass.no/auth/realms/SECURITYDOMAIN/protocol/openid-connect";
CLIENT_ID="oidc-client"
CLIENT_SECRET="mysecret"
BASIC_AUTH=`echo -n "${CLIENT_ID}:${CLIENT_SECRET}"| base64`
SCOPE="openid profile"

USERID="someuser"
USERPWD="somepassword" 
 
# Get the tokens using the Resource Owner Password Credentials Grant 
TOKENS_JSON=$(curl \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic ${BASIC_AUTH}" \
-X POST "${BASEURL}/token" \
-d "grant_type=password"\
"&username=${USERID}"\
"&password=${USERPWD}"\
"&scope=${SCOPE}" \
2>/dev/null)
 
# Get the Access Token (using the jq tool)
ACCESS_TOKEN=$(jq -r '.access_token' <<<"${TOKENS_JSON}")

# Introspect the Access Token
curl -i -w "\n" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic ${BASIC_AUTH}" \
-X POST "${BASEURL}/token/introspect" \
-d "token=${ACCESS_TOKEN}"\
"&token_type_hint=access_token"

# Get the Refresh Token (using the jq tool)
REFRESH_TOKEN=$(jq -r '.refresh_token' <<<"${TOKENS_JSON}")

# Introspect the Refresh Token
curl -i -w "\n" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic ${BASIC_AUTH}" \
-X POST "${BASEURL}/token/introspect" \
-d "token=${REFRESH_TOKEN}"\
"&token_type_hint=refresh_token"

Introspection Response

The OpenID Provider responds with a JSON object in "application/ json" format with some defined top-level members. See Introspection response.

Depending on the context, the Security Domain additional claims may be provided. The semantics and values may vary depending on the domain.

Example response

Introspect response example

{
  "jti": "4c64fccc-e06a-4613-a882-6a1fe57567c0",
  "exp": 1558702349,
  "nbf": 0,
  "iat": 1558702289,
  "iss": "https:\/\/auth.test.buypass.no\/auth\/realms\/SECURITYDOMAIN",
  "sub": "d6cccb1c-4390-41c1-b956-184ac9213a64",
  "typ": "Bearer",
  "azp": "oidc-client",
  "auth_time": 0,
  "session_state": "1b3b3efa-a26b-4599-8a49-ee1888402416",
  "preferred_username": "someuser",
  "acr": "1",
  "scope": "openid profile",
  "client_id": "oidc-client",
  "username": "someuser",
  "active": true
}

The following is a response for a token that has been revoked or is otherwise invalid.

Introspect response example

{
  "active":false
}