PingAM

/oauth2/introspect

The /oauth2/introspect endpoint, defined in RFC 7662 OAuth 2.0 Token Introspection, lets a client (including resource servers) retrieve details about a token. These details include:

  • 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 client making the request must authenticate to this endpoint.

Specify the realm in the request URL. For example:

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

The default settings for this endpoint don’t 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

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

token_type_hint

A hint about the type of token to introspect. Valid values are access_token, refresh_token, and requesting_party_token.

No

Example

The following example demonstrates token introspection:

$ curl \
--request POST \
--user "myClient:mySecret" \
--data "token=<access-token>" \
"https://am.example.com:8443/am/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://am.example.com:8443/am/oauth2/realms/root/realms/alpha",
  "auth_level": 0,
  "authGrantId": "sReMmkL05mN4xtDMQdVrpjXB_go",
  "auditTrackingId": "1d7a3317-03a9-4461-9d12-745f886019c2-5860187",
  "expires_in": 3575
}

Introspection requirements

A client can only introspect a token if it meets one of the following requirements:

  • Has a special scope

    The client has a special introspection scope (am-introspect-all-tokens or am-introspect-all-tokens-any-realm) specified in its client profile.

  • Token was issued to the client (server-side tokens)

    For server-side tokens, AM compares the clientID field stored in the token against the client_id of the client. If they match, the client can introspect the token.

    By default, the clientID field is set to the client that originally requested the token.

  • Token audience includes the client (client-side tokens)

    For client-side tokens, AM checks if the client_id of the client is present in the aud (audience) claim. If there’s a match, the client can introspect the token.

    By default, the aud claim is set to the client that originally requested the token.

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.

PingAM also supports signed JWT (JSON Web Token) or signed and encrypted JWT introspection responses, as defined in RFC 9701: JWT Response for OAuth Token Introspection.

Regardless of the configured response format, a client can request a signed JWT response by adding one of the following headers to the introspection request:

  • Accept:application/jwt (default, for compatibility with older clients)

  • Accept: application/token-introspection+jwt (for compatibility with RFC 9701)

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

  1. 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 list.

  2. If you need to configure signing and encryption algorithms, set 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

  3. Save your work.

Requests for plain JSON now return errors.

RFC 9701 token_introspection claim

By default, PingAM returns a flat JWT introspection response for backwards compatibility with older clients. To comply with RFC 9701, enable the Use token_introspection claim for JWT setting.

To enable the token_introspection claim, you can configure it at two levels:

  • Realm level: In the AM admin UI, go to Realms > realm name > Services > OAuth2 Provider > Advanced, and select Use token_introspection claim for JWT.

  • Client level: In the AM admin UI, go to Realms > realm name > Applications > OAuth 2.0 > client ID > OAuth2 Provider Overrides. Enable OAuth2 Provider Overrides, then select Use token_introspection claim for JWT.

When enabled, PingAM wraps the introspected token’s claims inside a token_introspection claim in the JWT. This separates the JWT’s own top-level claims (such as iss, aud, and iat for the introspection response itself) from the introspected token’s claims:

{
  "iss": "<authorization-server-issuer>",
  "aud": "<resource-server-client-id>",
  "iat": 1234567890,
  "token_introspection": {
    "active": true,
    "scope": "profile",
    "client_id": "myClient",
    "aud": ["myClient", "api.example.com"],
    "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
    "exp": 1675703376
  }
}

When enabled, the aud claim of the introspected token is always included in the response, including for stateless (client-side) tokens.

When disabled, the aud claim is omitted from the response, and a flat JWT structure is used.

This setting is disabled by default to preserve existing behavior after upgrades. Enable it for new deployments or when your resource servers are ready to consume RFC 9701-compliant responses.

Response content

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

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

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

For client-side tokens, PingAM 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. Indicates 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. Indicates the subject is a user/identity.

For example, (usr!bjensen), 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.