PingOne Advanced Identity Cloud

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

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

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

Example

The following example demonstrates token introspection:

$ curl \
--request POST \
--user "myClient:forgerock" \
--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
}

Response signing and encryption

The default introspection response is a plain JSON object.

PingOne Advanced Identity Cloud 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:

  1. In the Advanced Identity Cloud admin UI, 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 drop-down 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.

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 PingOne Advanced Identity Cloud.

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

For client-side tokens, PingOne 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!demo), (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.