/oauth2/introspect

Endpoint defined in RFC7662 - OAuth 2.0 Token Introspection, used to retrieve metadata about a token, such as, approved scopes, the user that authorized the token, the expiry time, the UMA RPT, or the proof-of-possession JWK.

As opposed to the /oauth2/tokeninfo endpoint, the /oauth2/introspect endpoint requires the client to authenticate to the authorization server.

Tip

To introspect macaroon access tokens containing third-party caveats, use the X-Discharge-Macaroon header to pass the discharge macaroon.

The token introspection endpoint supports the following parameters:

token

Specifies the token ID.

Required: Yes.

client_id

Specifies the client ID unique to the application making the request.

Required: A form of credentials is required for confidential clients. However, the use of the client_id parameter depends on the client authentication method used. For more information, see OAuth 2.0 Client Authentication.

client_secret

Specifies the secret of the client making the request.

Required: A form of password or credentials is required for confidential clients. However, the use of the client_secret parameter depends on the client authentication method used. For more information, see OAuth 2.0 Client Authentication.

client_assertion

Specifies the signed JWT that the client uses as a credential when using the JWT bearer client authentication method.

For more information, see OAuth 2.0 Client Authentication.

Required: Yes, when using the JWT bearer client authentication method.

client_assertion_type

Specifies the type of assertion when the client is authenticating to the authorization server using JWT bearer client authentication. Do not use with other client authentication methods.

Set it to urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer.

For more information, see OAuth 2.0 Client Authentication.

Required: Yes, when using the JWT bearer client authentication method.

You must compose the path to the introspect endpoint addressing the specific realm where the token was issued. For example, https://openam.example.com:8443/openam/oauth2/realms/root/realms/subrealm1/introspect.

By default, and for security reasons, clients can only introspect their own tokens. To let a client introspect access tokens issued to other clients, see "Special Scopes".

The following example shows AM returning token information:

$ curl \
--request POST \
--header "Authorization: Basic ZGVtbzpDaDRuZzMxdA==" \
--data "token=f9063e26-3a29-41ec-86de-1d0d68aa85e9" \
"https://openam.example.com:8443/openam/oauth2/introspect"
{
    "active": true,
    "scope": "write",
    "client_id": "myClient",
    "user_id": "demo",
    "username": "demo",
    "token_type": "Bearer",
    "exp": 1419356238,
    "sub": "demo",
    "iss": "https://openam.example.com:8443/openam/oauth2"
    "cnf": {
        "jwk": {
            "alg": "RS512",
            "e": "AQAB",
            "n": "k7qLlj...G2oucQ",
            "kty": "RSA",
            "use": "sig",
            "kid": "myJWK"
        },
    "auth_level": 0
    }
}

The introspection response, as specified in RFC7662, is a plain JSON object. However, AM also supports the JWT Response for OAuth Token Introspection Internet Draft, which adds signed JWT or signed then encrypted JWT responses.

To configure the response type, perform the following steps:

Navigate to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > Signing and Encryption.
In the Token introspection response format drop-down list, select the type of response required by the client.
Configure the signing and/or encryption settings AM should use when returning introspection responses to this particular client in the following properties:
- Token introspection response signing algorithm
- Token introspection response encryption algorithm
- Token introspection encrypted response encryption algorithm
For more information about these properties, see Signing and Encryption Properties.

Tip

Even if the client has configured the response to be JSON-formatted, it can request a signed JWT by adding the "Accept: application/jwt" header to the request. For example:

$ curl \
--request POST \
--header "Accept: application/jwt" \
--header "Authorization: Basic ZGVtbzpDaDRuZzMxdA==" \
--data "token=f9063e26-3a29-41ec-86de-1d0d68aa85e9" \
"https://openam.example.com:8443/openam/oauth2/introspect"

However, when a client that is configured to use either of the JWT-formatted responses requests a JSON response, AM returns an error.

The following is a list of the objects commonly returned by the token introspect endpoint:

active

Specifies whether the token is active (true) or not (false).

scope

Specifies a space-separated list of the scopes associated with the token.

client_id

Specifies the client that requested the token.

user_id

(Deprecated, defined in a previous draft of the spec) Specifies the user that authorized the token.

username

Specifies the user that authorized the token.

token_type

Specifies the type of token.

exp

Specifies the token expiration time in seconds since January 1 1970 UTC.

sub

Specifies the subject of the token.

iss

Specifies the issuer of the token.

cnf

Specifies the confirmation key claim containing one of the following key types:

jwk, which contains the decoded JSON web key (JWK) associated with the access token. For more information, see the "JWK-Based Proof-of-Possession" flow.
x5t#S256, which contains the base64-encoded SHA-256 hash of the DER-encoding of a full X.509 certificate associated with the access token. For more information, see the "Certificate-Bound Proof-of-Possession" flow.

macaroon

Specifies the macaroon validated by the token, including any caveats appended to the macaroon.

auth_level

(AM-specific extension property) Specifies the authentication level of the resource owner that authenticated to authorize the token.

permissions

(UMA only). Specifies an array that contains the RPT token expiration time (exp), the resource scopes of the token, and the resource ID.