Claims
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 a set of claims about the end user from Google 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:
|
AM supports Normal Claims, as specified in section 5.6 of the specification. AM does not support the optional Aggregated Claims and Distributed Claims representations. |
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:
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:
| Claim | User profile attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
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.
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 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
claimsparameter.
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.
For an example on 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 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 configure clients to use implied consent, or manually configure the claims to display. How to configure claims in the AM consent screenConfigure 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, 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: 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. |