PingAM 7.5.0

/oauth2/idtokeninfo

The /oauth2/idtokeninfo endpoint is an AM-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://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/idtokeninfo

Supported parameters

The ID token information endpoint supports the following parameters:

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

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

Token validation

AM validates the tokens based on rules in the OpenID Connect Core specification. Token validation includes the following steps:

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

  2. Extract the realm claim, if present, and use it to look up the client profile.

    Validation returns an error if no client profile exists.

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

  4. 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:mySecret \
--data 'id_token=id-token' \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/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://openam.example.com:8443/openam/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:mySecret \
--data 'id_token=id-token' \
--data 'claims=sub,exp,realm' \
"https://openam.example.com:8443/openam/oauth2/idtokeninfo"
{
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "exp": 1676364398,
  "realm": "/alpha"
}

If you request a claim that does not exist, no error occurs; AM omits the claim from the response.

Subject claims

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

The value of the subname claim, when provided, matches the value of the subject portion of the sub claim.