PingOne Advanced Identity Cloud

Claims

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

A claim is a piece of information about the end user (user attribute) that the relying party or client uses to provide a service.

Consider a page that lets an end user register using their Google account information instead of providing the information themselves. The page requests a set of claims about the end user from Google and uses the information in those claims to set up the account without the user’s interaction.

If the user agrees to share access to their claims, OpenID providers can return them in two ways:

  • As key-value pairs in the ID token

  • By making them available at the userinfo endpoint

Part of implementing OIDC 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 aren’t related to user information directly, but that are relevant to the flow, the relying party, or the authorization server. These claims are similar to those contained in access tokens; for example, iss, aud, exp, and others.

For more information, refer to the following sections of the OIDC specification:

PingOne Advanced Identity Cloud supports Normal Claims, as specified in section 5.6 of the specification.

PingOne Advanced Identity Cloud doesn’t support the optional Aggregated Claims and Distributed Claims.

When PingOne Advanced Identity Cloud is configured as an authorization server, scopes don’t relate to data. For example, Facebook has an OAuth 2.0 scope named read_stream. PingOne Advanced Identity Cloud returns allowed scopes in the access token, but it doesn’t associate any data with them.

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

Because each claim represents an attribute from the user profile, PingOne Advanced Identity Cloud displays the actual data the relying party will receive if the end user consents to sharing it:

The OIDC consent page can show the values associated with the claims that make up the requested scopes.
Figure 1. OIDC consent page

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

Table 1. OIDC scope default claim mappings
Claim User profile attribute

given_name

givenname

zoneinfo

preferredtimezone

family_name

sn

locale

preferredlocale

name

cn

After a successful flow, the OpenID provider returns an ID token with the relevant claims. For security reasons, PingOne Advanced 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 must satisfy before being redirected to particular resources.

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

  • To configure the provider to return all scope-derived claims in the ID token, go to Native Consoles > Access Management > Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect and enable Always Return Claims in ID Tokens.

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

  • To configure the provider to include specific scope-derived claims in the ID token, go to Native Consoles > Access Management > Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect and enable Enable "claims_parameter_supported". Specify the required 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 the claims that are necessary to ensure a good end user experience.

    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 the claims that are useful but not required to provide services to the end user.

For more information, refer to Demonstrate authentication requirements.

Clients can 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 PingOne Advanced Identity Cloud presents the claims in the consent screen. By default, the UI doesn’t display scope-derived claims in the consent screen. You can configure the claims to display.

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

You can enter claims as simple strings or pipe-separated strings representing the internal claim name, locale, and localized description. For example: name|en|Your full name.

If you omit the description, the claim doesn’t display in the consent page. This may be useful when the client requires claims that aren’t meaningful to the end user.

Client-level configuration overrides the configuration set at the provider level.