/oauth2/idtokeninfo

AM-specific endpoint that lets relying parties validate unencrypted ID tokens and to retrieve claims within the token.

AM validates the tokens based on rules 1-10 in section 3.1.3.7 of the OpenID Connect Core. During token validation, AM performs the following steps:

Extracts the first aud (audience) claim from the ID token. The client_id, which is passed in as an authentication of the request, will be used as the client and validated against the aud claim.
Extracts the realm claim, if present, defaults to the root realm if the token was not issued by AM.
Looks up the client in the given realm, producing an error if it does not exist.
Verifies the signature of the ID token, according to the ID Token Signing Algorithm and Public key selector settings in the client profile.
Verifies the issuer, audience, expiry, not-before, and issued-at claims as per the specification.

Tip

By default, the ID token information endpoint requires client authentication. You can configure it by navigating to Realms > Realm Name Services > OAuth2 Provider > Advanced OpenID Connect and disabling the Idtokeninfo Endpoint Requires Client Authentication switch.

The ID token information endpoint supports the following parameters:

id_token

Specifies the ID token to validate.

Required: Yes.

client_id

Specifies the client ID unique to the application making the request.

Required: Yes, when client authentication is enabled.

client_assertion

Specifies the signed JWT that the client uses as a credential when using the JWT bearer client authentication method.

Required: A form of password or credentials is required for confidential clients when client authentication is enabled. However, the use of the client_assertion parameter depends on the client authentication method used. For more information, see OAuth 2.0 Client Authentication

client_assertion_type

Specifies the type of assertion when the client is authenticating to the authorization server using JWT bearer client authentication.

Set it to urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer.

Required: A form of password or credentials is required for confidential clients when client authentication is enabled. However, the use of the client_assertion_type parameter depends on the client authentication method used. For more information, see OAuth 2.0 Client Authentication

client_secret

Specifies the secret of the client making the request.

Required: A form of password or credentials is required for confidential clients when client authentication is enabled. However, the use of the client_secret parameter depends on the client authentication method used. For more information, see OAuth 2.0 Client Authentication

claims

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

Required: No.

The endpoint is always accessed from the root realm. For example, https://openam.example.com:8443/openam/oauth2/idtokeninfo.

The following example shows AM returning ID token information:

$ curl \
--request POST \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
--data "id_token=eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg" \
"https://openam.example.com:8443/openam/oauth2/idtokeninfo"
{
   "at_hash":"AvJ0dXLQgFxHn-qnqP9xmQ",
   "sub":"(usr!demo)",
   "auditTrackingId":"b3f48c69-de7f-4afc-ab78-582733e5f025-156621",
   "iss":"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha",
   "tokenName":"id_token",
   "nonce":"123abc",
   "sid": "I0GdWDfy1qhahDl1PpEA0v5LDspul+qW70biBhetUCk=",
   "aud":"myClient",
   "c_hash":"jMXGi-FCjUad2VQukJRcLQ",
   "acr":"0",
   "s_hash":"bKE9UspwyIPg8LsQHkJaiQ",
   "azp":"myClient",
   "auth_time":1553077105,
   "realm":"/myRealm",
   "exp":1553080707,
   "tokenType":"JWTToken",
   "iat":1553077107
}

If the ID token validates successfully, the endpoint unpacks the claims from the ID token and returns them as JSON. You can also use an optional claims parameter in the request to return specific claims.

For example, you can run the following command to retrieve specific claims:

$ curl \
--request POST \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
--data "id_token=eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg" \
--data "claims=sub,exp,realm" \
"https://openam.example.com:8443/openam/oauth2/idtokeninfo"
{
   "sub":"(usr!demo)",
   "exp":1553080707,
   "realm":"/myRealm"
}

If a requested claim does not exist, no error occurs; AM will simply not present it in the response.

About the Subject and the Subname 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 matches the value of the subject portion of the sub claim.

The subname claim is not included in the OIDC Claims Script. Therefore, AM does not add it to ID tokens by default.

Note

The ID token information endpoint does not check if a token has been revoked using the /oauth2/endSession endpoint.