PingAM 7.5.0

/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

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:

  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 drop-down list.

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

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