/oauth2/idtokeninfo

The /oauth2/idtokeninfo endpoint is an PingOne Advanced Identity Cloud-specific endpoint.

Use this endpoint to validate unencrypted ID tokens and to retrieve claims in the token.

Specify the realm in the request URL; for example:

https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/idtokeninfo

Supported parameters

The ID token information endpoint supports the following parameters:

Parameter Description Required

Parameter	Description	Required
`claims`	Comma-separated list of claims to return from the ID token.	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, when authentication is required (default)
`client_secret`	The password for a confidential client.	Yes, when authenticating with Form parameters (HTTP POST)
`id_token`	The ID token to validate.	Yes

claims

Comma-separated list of claims to return from the ID token.

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, when authentication is required (default)

client_secret

The password for a confidential client.

Yes, when authenticating with Form parameters (HTTP POST)

id_token

The ID token to validate.

Yes

By default, the client must authenticate to use the endpoint. Optionally disable this in the OAuth 2.0 provider configuration. Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect and disable Idtokeninfo Endpoint Requires Client Authentication.

Token validation

PingOne Advanced Identity Cloud validates the tokens based on rules in the OpenID Connect Core specification. Token validation includes the following steps:

Extract the first aud (audience) claim from the ID token.

This step depends on the client_id parameter to identify the client and validate the aud claim.
Extract the realm claim, if present, and use it to look up the client profile.

Validation returns an error if no client profile exists.
Verify the signature of the ID token.

This validation step depends on these client profile settings:

ID Token Signing Algorithm (default: RS256)
Public key selector (default: JWKs_URI)
Verify the following claims:

aud (audience)
exp (expiration)
iat (issued at)
iss (issuer)
nbf (not before, if set)

This endpoint does not check whether the ID token was revoked with the /oauth2/connect/endSession endpoint.

Examples

The following example returns all ID token claims:

$ curl \
--request POST \
--user myClient:forgerock \
--data 'id_token=id-token' \
"https://<tenant-env-fqdn>/am/oauth2/idtokeninfo"
{
  "at_hash": "PZg5xZsIlFtRSfg8MAWhWg",
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "auditTrackingId": "2e5c7611-4a61-4001-8739-f714d43e9da2-881454",
  "subname": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "iss": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha",
  "tokenName": "id_token",
  "given_name": "Babs",
  "sid": "+buKyDp+Fbc0/Rkd0OqsfdKy7ZY0nWvcsEetikX+eTc=",
  "aud": "myClient",
  "c_hash": "FP5Nj162jgycmtEeRjVQ-A",
  "acr": "0",
  "org.forgerock.openidconnect.ops": "gkQOcZ1F3ZFdYPd6TiGIgr6scH0",
  "s_hash": "bKE9UspwyIPg8LsQHkJaiQ",
  "azp": "myClient",
  "auth_time": 1676360741,
  "name": "Babs Jensen",
  "realm": "/alpha",
  "exp": 1676364398,
  "tokenType": "JWTToken",
  "iat": 1676360798,
  "family_name": "Jensen"
}

Use the optional claims parameter to return specific claims as in the following example:

$ curl \
--request POST \
--user myClient:forgerock \
--data 'id_token=id-token' \
--data 'claims=sub,exp,realm' \
"https://<tenant-env-fqdn>/am/oauth2/idtokeninfo"
{
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "exp": 1676364398,
  "realm": "/alpha"
}

If you request a claim that does not exist, no error occurs; PingOne Advanced Identity Cloud omits the claim from the response.