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

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

  2. Extracts the realm claim, if present, defaults to the root realm if the token was not issued by AM.

  3. Looks up the client in the given realm, producing an error if it does not exist.

  4. Verifies the signature of the ID token, according to the ID Token Signing Algorithm and Public key selector settings in the client profile.

  5. 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":"demo",
   "auditTrackingId":"b3f48c69-de7f-4afc-ab78-582733e5f025-156621",
   "iss":"https://openam.example.com:8443/openam/oauth2",
   "tokenName":"id_token",
   "nonce":"123abc",
   "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":"demo",
   "exp":1553080707,
   "realm":"/myRealm"
}

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

Note

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

Read a different version of :