/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 resource server to authenticate to the authorization server.

Introspecting macaroon and UMA RPT tokens

To introspect macaroon access tokens containing third-party caveats, use the X-Discharge-Macaroon header to pass the discharge macaroon.
To introspect UMA RPT tokens, use the PAT of the resource owner in an authorization: Bearer header to authenticate to the endpoint.

Important

From AM 7.1.3 onwards, HTTP GET requests are disallowed on the /oauth2/introspect endpoint by default. Using token as a query parameter on this endpoint is also disallowed. To change this behavior to suit existing clients, use the org.forgerock.openam.introspect.token.query.param.allowed advanced server property.

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/alpha/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/realms/root/realms/alpha/introspect"
{
    "active": true,
    "scope": "write",
    "client_id": "myClient",
    "user_id": "demo",
    "token_type": "Bearer",
    "exp": 1419356238,
    "sub": "(usr!demo)",
    "subname" : "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/realms/root/realms/alpha/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.

token_type

Specifies the type of token.

exp

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

expires_in

Specifies the time, in seconds, that the token is valid for. This value is set at token creation time, and it depends on the configuration of the OAuth2 Provider Service.

During the introspection call, AM calculates the amount of seconds the token is still valid for and returns it in the expires_in object. Therefore, repeated calls to the endpoints return different values for the object.

However, the actual value of the expires_in object in the token does not change. Inspecting the token without using AM will show the value set at token creation time.

AM only returns this object for client-based tokens issued to a client configured in the same realm than that of the resource owner.

sub

Specifies the identifier of the identity or the OAuth 2.0/OpenID Connect client, that is the subject of the access token.

The subject claim is in the format (type!subject), where:

subject is the identifier of the user/identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.
type can be one of the following:
- age. Specifies that the subject is an OAuth 2.0/OpenID Connect-related user-agent or client. For example, an OAuth 2.0 client, a Remote Consent Service agent, and a Web and Java Agent internal client.
- usr. Specifies that the subject is a user/identity.

For example, (usr!demo), or (age!myOAuth2Client).

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.