Claims

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

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

Note

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

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

When AM 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, AM displays the actual data the relying party will receive if the end user consents to sharing it:

OpenID Connect Consent Page
OpenID Connect Consent Page

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

OpenID Connect Scope Default Claim Mappings
ClaimUser profile attribute

given_name

givenname

zoneinfo

preferredtimezone

family_name

sn

locale

preferredlocale

name

cn


The script is configured in the OAuth 2.0 provider. To configure a different script of the type OIDC Claims, go to Realms > Realm Name > Services > OAuth 2.0 Provider > OpenID Connect, and then select it in the OIDC Claims Script drop-down menu.

To examine the contents of the default OIDC claims script, go to Realms > Realm Name > Scripts, and then select the OIDC Claims Script. Use the following information to understand the example or write your own script:

Server-side scripts can access the OpenID Connect request through the following objects:

ObjectTypeDescription

scopes

Set<String>

Contains a set of the requested scopes. For example: 

[
  "profile",
  "openid"
]

identity

Class

Contains a representation of the identity of the resource owner.

For more details, see the com.sun.identity.idm.AMIdentity class in the ForgeRock Access Management Javadoc.

session

Class

Contains a representation of the user's session object if the request contained a session cookie.

For more details, see the com.iplanet.sso.SSOToken class in the ForgeRock Access Management Javadoc.

claims

Map<String, Object>

Contains a map of the claims the server provides by default. For example: 

{
  "sub": "248289761001",
  "updated_at": "1450368765"
}

requestedClaims

Map<String, Set<String>>

Contains requested claims if the claims query parameter is used in the request, and Enable "claims_parameter_supported" is checked in the OAuth2 provider service configuration; otherwise is empty.

For more information see "Requesting Claims using the "claims" Request Parameter" in the OpenID Connect Core 1.0 specification.

Example:

{
  "given_name": {
    "essential": true,
    "values": [
      "Demo User",
      "D User"
    ]
  },
  "nickname": null,
  "email": {
    "essential": true
  }
}

For more information about scripting in AM, see Getting Started with Scripting.

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

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

    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.

    For an example on requesting voluntary and essential claims, see "Requesting acr Claims Example".

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

Tip

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 AM presents the claims in the AM consent screen. By default, scope-derived claims are not configured to display in the consent screen. You can either disable the consent pages, or manually configure the claims for display.

Configure how claims appear in the consent screen by client or by realm (in the OAuth 2.0 provider service). For examples, see the Supported Claims field in the provider's "Advanced" reference section or the Claim(s) field in Core Properties.

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.

Read a different version of :