/oauth2/introspect

The /oauth2/introspect endpoint is defined in RFC 7662 OAuth 2.0 Token Introspection.

A resource server uses this endpoint to retrieve details about a token, such as:

The approved scopes
The user who authorized the client to obtain the token
The expiry time
The proof-of-possession JSON Web Key (JWK)

The resource server must authenticate to access this endpoint.

Specify the realm in the request URL; for example:

https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/introspect

The default settings for this endpoint do not allow:

HTTP GET requests
Use of token as a query parameter

To change this behavior for compatibility, use the org.forgerock.openam.introspect.token.query.param.allowed advanced server property.

The token introspection endpoint supports the following parameters:

Parameter Description Required

Parameter	Description	Required
`client_assertion`	A signed JSON Web Token (JWT) to use as client credentials.	Yes, for JWT profile authentication
`client_assertion_type`	The type of assertion, `client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer`.	Yes, for JWT profile authentication
`client_id`	Uniquely identifies the application making the request.	Yes
`client_secret`	The password for a confidential client.	Yes, when authenticating with Form parameters (HTTP POST)
`token`	The token to introspect.	Yes

client_assertion

A signed JSON Web Token (JWT) to use as client credentials.

Yes, for JWT profile authentication

client_assertion_type

The type of assertion, client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer.

Yes, for JWT profile authentication

client_id

Uniquely identifies the application making the request.

Yes

client_secret

The password for a confidential client.

Yes, when authenticating with Form parameters (HTTP POST)

token

The token to introspect.

Yes

Example

The following example demonstrates token introspection:

$ curl \
--request POST \
--user "myClient:forgerock" \
--data "token=<access-token>" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/introspect"
{
  "active": true,
  "scope": "profile",
  "realm": "/alpha",
  "client_id": "myClient",
  "user_id": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "username": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "token_type": "Bearer",
  "exp": 1675703376,
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "subname": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "iss": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha",
  "auth_level": 0,
  "authGrantId": "sReMmkL05mN4xtDMQdVrpjXB_go",
  "auditTrackingId": "1d7a3317-03a9-4461-9d12-745f886019c2-5860187",
  "expires_in": 3575
}

Introspect special 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.

Response signing and encryption

The default introspection response is a plain JSON object.

AM also supports the JWT Response for OAuth Token Introspection Internet-Draft, which adds signed JWT or signed and encrypted JWT responses.

A client application can request a signed JWT by adding an Accept: application/jwt header to the request.

To enable signing and encryption for all requests, follow these steps:

In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Client ID > Advanced and select the response type in the Token introspection response format drop-down list.
If necessary to configure signing and encryption, configure the following properties:

Token introspection response signing algorithm

Default: RS256

Token introspection response encryption algorithm

Default: RSA-OAEP-256

Token introspection encrypted response encryption algorithm

Default: A128CBC-HS256
Save your work.

Requests for plain JSON now return errors.

Response content

The following table describes fields you may find in the introspection response:

Field Description

Field	Description
`active`	Whether the token is active (`true`) or not (`false`).
`auth_level`	The AM authentication level for the resource owner who granted access to the token.
`client_id`	The client the token was issued to.
`cnf`	The confirmation key claim. The `jwk` type contains the decoded JWK for the access token in the JWK-based proof-of-possession flow.
`exp`	Expiration time in seconds since January 1, 1970 UTC.
`expires_in`	Expiration time in seconds from now; the value decreases with every request to AM. Unlike the calculated value, the expiration time stored in the token does not change. For client-side tokens, AM only returns this to a client in the same realm as the resource owner.
`iss`	The token issuer.
`macaroon`	The macaroon the token validates, including any caveats.
`permissions`	(UMA only) An array containing the following: RPT token expiration time (`exp`) Resource scopes of the token Resource ID
`scope`	The space-separated list of the scopes associated with the token.
`sub`	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)`.
`token_type`	The type of token.
`user_id`	Deprecated form of `username`.
`username`	The user who authorized the client to obtain the token.

active

Whether the token is active (true) or not (false).

auth_level

The AM authentication level for the resource owner who granted access to the token.

client_id

The client the token was issued to.

cnf

The confirmation key claim.

The jwk type contains the decoded JWK for the access token in the JWK-based proof-of-possession flow.

exp

Expiration time in seconds since January 1, 1970 UTC.

expires_in

Expiration time in seconds from now; the value decreases with every request to AM.

Unlike the calculated value, the expiration time stored in the token does not change.

For client-side tokens, AM only returns this to a client in the same realm as the resource owner.

iss

The token issuer.

macaroon

The macaroon the token validates, including any caveats.

permissions

(UMA only) An array containing the following:

RPT token expiration time (exp)
Resource scopes of the token
Resource ID

scope

The space-separated list of the scopes associated with the token.

sub

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).

token_type

The type of token.

user_id

Deprecated form of username.

username

The user who authorized the client to obtain the token.

PingAM 7.5.0

/oauth2/introspect

Example

Introspect special tokens

Response signing and encryption

Response content