OpenID Connect Claims


OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 RFC 6749 to specify what access privileges are being requested for Access Tokens. The scope associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints.

For OpenID Connect, scope can be used to request that specific sets of information be made available as OpenID Connect Claims Values. This document describes only the scope values used by OpenID Connect.

OpenID Connect allows additional scope values to be defined and used. Scope values used that are not understood by an implementation SHOULD be ignored.

OpenID Connect Claims requested by the following scope are treated by Authorization Servers as Voluntary Claims.

OpenID Connect defines the following OpenID Connect Scope values:

Multiple scope values MAY be used by creating a space delimited, case-sensitive list of ASCII scope values.

OpenID Connect Standard Claims#

The OpenID Connect specification defines a set of OpenID Connect Claims, referred to as "OpenID Connect Standard Claims" that can be requested to be returned either in the Userinfo_endpoint or in the Identity Token.

Requesting Claims using the "claims" Authorization Request Parameter[2]#

The claims Authentication Request parameter requests that specific Claims be returned from the userinfo_endpoint and/or in the id_token. It is represented as a JSON Object containing lists of Claims being requested from these locations.

Properties of the Claims being requested MAY also be specified.

Support for the claims parameter is OPTIONAL. Should an OP not support this parameter and an RP uses it, the OP SHOULD return a set of Claims to the RP that it believes would be useful to the RP and the End-User using whatever heuristics it believes are appropriate. The claims_parameter_supported Discovery result indicates whether the OP supports this parameter.

The claims parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON (which ends up being form-urlencoded when passed as an OAuth parameter). When used in a Request Object value, per Section 6.1, the JSON is used as the value of the claims member.

The top-level members of the OpenID Connect Claims request JSON Object are:

  • userinfo - OPTIONAL. Requests that the listed individual Claims be returned from the UserInfo Endpoint. If present, the listed Claims are being requested to be added to any OpenID Connect Claims that are being requested using scope values. If not present, the Claims being requested from the userinfo_endpoint are only those requested using scope values.
When the userinfo member is used, the request MUST also use a response_type value that results in an access_token being issued to the Client for use at the userinfo_endpoint.

Other members MAY be present. Any members used that are not understood MUST be ignored.

An example Claims request is as follows:

   "given_name": {"essential": true},
   "nickname": null,
   "email": {"essential": true},
   "email_verified": {"essential": true},
   "picture": null,
   "http://example.info/claims/groups": null
   "auth_time": {"essential": true},
   "acr": {"values": ["urn:mace:incommon:iap:silver"] }

Note that a Claim that is not in the OpenID Connect Standard Claims defined in Section 5.1, the (example) http://example.info/claims/groups Claim, is being requested. Using the claims parameter is the only way to request Claims outside the OpenID Connect Standard Claims. It is also the only way to request specific combinations of the OpenID Connect Standard Claims that cannot be specified using scope values.

More Information#

There might be more information for this subject on one of the following: