Identity Cloud


OpenID Connect relies on claims to provide information about the end user to the relying parties.

What are claims?

A claim is a piece of information about the end user that the relying party or client can use to provide them a service.

Consider a page that lets the end user register using their Google account information instead of providing the information themselves. The page requests Google a set of claims about the end user, and uses the information on the claims to set up the account without user interaction.

If the end user agrees to share access to their claims, OpenID providers can return them in two ways: either as key pairs in the ID token, or by making them available at the userinfo endpoint. Part of implementing OpenID Connect in your environment is deciding which claims are safe to travel in the ID token, and which ones require the client to access the endpoint.

ID tokens contain additional claims that are not related to user information directly, but that are relevant to the flow, the relying party, or the authorization server. These are similar to those contained in access tokens; for example, iss, aud, exp, and others.

Read more:

  • Section 2 of the OpenID Connect specification

  • Section 5 of the OpenID Connect specification

Identity Cloud supports Normal Claims, as specified in section 5.6 of the specification. The optional Aggregated Claims and Distributed Claims representations are not supported by Identity Cloud.

When Identity Cloud is configured as an authorization server, a scope is a concept. For example, Facebook has an OAuth 2.0 scope named read_stream. Identity Cloud returns allowed scopes in the access token, but it does not associate any data with them.

When Identity Cloud is configured as an OpenID provider, scopes can relate to data in a user profile by making use of one or more claims.

As each claim represents a piece of information from the user profile, Identity Cloud displays the actual data the relying party will receive if the end user consents to sharing it:

Identity Cloud maps scopes and profile data to claims using a script configured in the OAuth2 provider service. By default, the script maps several user profile attributes to the profile scope:

Table 1. OpenID Connect Scope Default Claim Mappings
Claim User profile attribute











After a successful flow, the OpenID provider returns an ID token with the relevant claims. However, for security reasons, Identity Cloud does not return scope-derived claims in the ID token by default.

Request claims in ID tokens

Sometimes you may need the provider to return scope-derived claims in the ID token. For example, when claims are related to authentication conditions or rules the end user needs to satisfy before being redirected to particular resources.

You can configure Identity Cloud to either return all scope-derived claims in the ID token, or just the ones specified in the request:

  • To configure the provider to always return scope-derived claims in the ID token, enable Always Return Claims in ID Tokens (Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect).

    This option is disabled by default because of the security concerns of returning claims that may contain sensitive user information.

  • To request that the provider only include certain scope-derived claims in the ID token, enable the property Enable "claims_parameter_supported" (Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect) and request said claims in the claims parameter.

Voluntary and essential claims in the claims parameter

Claims specified using the claims parameter can be voluntary or essential:

  • Essential. The relying party specifies a number of claims that are necessary to ensure a good experience to the end user.

    For example, to provide personalized services, the relying party may require the end user’s phone number to send them an SMS.

  • Voluntary. The relying party specifies a number of claims that are useful but not required to provide services to the end user.

To try requesting voluntary and essential claims, refer to Demonstrate authentication requirements.

Clients can still retrieve additional claims from the /oauth2/userinfo endpoint.

The OAuth 2.0 provider’s Supported Claims field restricts the claims that can be granted in ID tokens, but not the claims a client can register with during dynamic client registration.

You can also use this field to configure how Identity Cloud presents the claims in the Identity Cloud consent screen. By default, the UI does not display scope-derived claims in the consent screen. You can configure the claims to display.

How to configure claims in the Identity Cloud consent screen

Configure how claims appear in the consent screen as described in Manage consent.

Claims may be entered as simple strings or pipe-separated strings representing the internal claim name, locale, and localized description. For example: name|en|Your full name.

If the description is omitted, the claim is not displayed in the consent page. This may be useful when the client requires claims that are not meaningful for the end user.

Client-level configuration overrides that at provider level.

Copyright © 2010-2023 ForgeRock, all rights reserved.