PingOne Advanced Identity Cloud

/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://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/introspect

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://<tenant-env-fqdn>/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://<tenant-env-fqdn>/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, Advanced Identity Cloud 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, Advanced Identity Cloud 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.

Response signing and encryption

The default introspection response is a plain JSON object.

Advanced Identity Cloud 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 Advanced Identity Cloud admin console, go to Applications > Client ID > Sign On > General Settings > Show advanced settings > Endpoint Response Formats and select the response type in the Token Inspection Response Format list.

  2. Save your work.

  3. If you need to configure signing and encryption, go to Native Consoles > Access Management > Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > Signing and Encryption and 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

  4. Save your work.

Requests for plain JSON now return errors.

RFC 9701 token_introspection claim

By default, Advanced Identity Cloud 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: Under Native Consoles > Access Management, go to Realms > realm name > Services > OAuth2 Provider > Advanced, and select Use token_introspection claim for JWT.

  • Client level: Under Native Consoles > Access Management, 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, Advanced Identity Cloud 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.

For backwards compatibility, this setting is disabled by default. Enable it 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 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 Advanced Identity Cloud.

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

For client-side tokens, Advanced Identity Cloud 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.

scope

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

sub

The subject of the access token.

This can use the format (type!subject), where:

  • subject is the principal’s ID.

  • type can be one of the following:

    age

    The subject is an OAuth 2.0 or OpenID Connect client, a Remote Consent Service agent, or a Web or Java Agent internal client.

    usr

    The subject is a user, device, or similar identity.

Examples: (usr!bjensen), (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.