OpenID Connect - Part 3: Claims Framework 1.0 - draft 00

Abstract

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

OpenID Connect Claims Framework 1.0 defines a framework in which the client may obtain the claims about the End User. It can be done through the pre-defined scopes values or through more granular claims parameter. The claims can come from a single source or distributed sources as well.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
2.  Terminology
3.  Requesting Claims
    3.1.  Requesting Claims via Scope values
    3.2.  Requesting Claims via claims parameter
        3.2.1.  Individual Claims Requests
        3.2.2.  Languages and Scripts for Individual Claims
4.  Standard Claims
    4.1.  Address Claim
    4.2.  Claims Languages and Scripts
    4.3.  Claim Stability and Uniqueness
    4.4.  Additional Claims
    4.5.  new section
5.  Claim Types
    5.1.  Normal Claims
    5.2.  Aggregated and Distributed Claims
        5.2.1.  Example of Aggregated Claims
        5.2.2.  Example of Distributed Claims
6.  UserInfo Endpoint
    6.1.  UserInfo Request
    6.2.  UserInfo Response
    6.3.  UserInfo Response Validation
    6.4.  UserInfo Error Response
7.  Offline Access
8.  Security Considerations
9.  Privacy Considerations
10.  IANA Considerations
    10.1.  JSON Web Token Claims Registry
        10.1.1.  Registry Contents
    10.2.  OAuth Parameters Registry
        10.2.1.  Registry Contents
11.  References
    11.1.  Normative References
    11.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Notices
Appendix C.  Document History
§  Authors' Addresses

1.  Introduction

Once the Client obtained the Access Token through OpenID Connect Authentication, it MAY use it against a OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] Protected Resource called UserInfo Endpoint to obtain the information about the End-User.

1.1.  Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) .

Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value.

All uses of JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] and JSON Web Encryption (JWE) (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.

2.  Terminology

This specification strives to make itself readable without constantly referring to the term definitions. Defined terms are shown with its first letters capitalized. When in doubt, refer to OpenID Connect Messages 1.0 for the authoritative definition of the defined terms.

3.  Requesting Claims

In addition to obtaining the authentication event information about the End-User, the Client often wants to obtain other Claims about the user. To request such, the Client sends the request through either scope values or claims parameter as defined in Claims Request (Requesting Claims via claims parameter).

3.1.  Requesting Claims via Scope values

OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. For OpenID Connect, scopes can be used to request that specific sets of information be made available as Claim Values. This specification 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.

Claims requested by the following scopes are treated by Authorization Servers as Voluntary Claims.

OpenID Connect defines the following scope values:

openid

REQUIRED. Informs the Authorization Server that the Client is making an OpenID Connect request. If the openid scope value is not present, the behavior is entirely unspecified.

profile

OPTIONAL. This scope value requests access to the End-User's default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.

email

OPTIONAL. This scope value requests access to the email and email_verified Claims.

address

OPTIONAL. This scope value requests access to the address Claim.

phone

OPTIONAL. This scope value requests access to the phone_number and phone_number_verified Claims.

offline_access

OPTIONAL. This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the End-User is not present (not logged in).

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

The Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo Endpoint, when a response_type value is used that results in an Access Token being issued. However, when the response_type value used is id_token (which issues no Access Token), the resulting Claims are returned in the ID Token.

In some cases, the End-User will be given the option to have the OpenID Provider decline to provide some or all information requested by Clients. To minimize the amount of information that the End-User is being asked to disclose, a Client can elect to only request a subset of the information available from the UserInfo Endpoint.

The following is a non-normative example of a scope Request.

  https://server.example.com/op/authorize?
    response_type=code
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &scope=openid%20profile%20email%20phone
    &nonce=n-0S6_WzA2Mj
    &state=af0ifjsldkj

3.2.  Requesting Claims via claims parameter

As a way to request a more granular set of claims, this specification defines the following request parameter to the Authorization Endpoint.

claims

OPTIONAL. This parameter is used to request that specific Claims be returned. The value is a JSON object, as specified in Section 3.2 (Requesting Claims via claims parameter).

claims_locales

End-User's preferred languages and scripts for Claims being returned, represented as a space-separated list of BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tag values, ordered by preference. An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.

The claims 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, the JSON is used as the value of the claims member.

The top-level members of the 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 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 use at the UserInfo Endpoint.

id_token

OPTIONAL. Requests that the listed individual Claims be returned in the ID Token. If present, the listed Claims are being requested to be added to the default Claims in the ID Token. If not present, the default ID Token Claims are requested.

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

An example Claims request is as follows:

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

3.2.1.  Individual Claims Requests

The userinfo and id_token members of the claims request both are JSON objects with the names of the individual Claims being requested as the member names. The member values MUST be one of the following:

null

Indicates that this Claim is being requested in the default manner. In particular, this is a Voluntary Claim. For instance, the Claim request:

  "given_name": null

requests the given_name Claim in the default manner.

JSON Object

Used to provide additional information about the Claim being requested. This specification defines the following members:

essential

OPTIONAL. Indicates whether the Claim being requested is an Essential Claim. If the value is true, this indicates that the Claim is an Essential Claim. For instance, the Claim request:

  "auth_time": {"essential": true}

can be used to specify that it is Essential to return an auth_time Claim Value.

If the value is false, it indicates that it is a Voluntary Claim. The default is false.

By requesting Claims as Essential Claims the Client indicates to the End-User that releasing these Claims will ensure a smooth authorization for the specific task requested by the End-User. Note that even if the Claims are not available because the End-User did not authorize their release or they are not present, the Authorization Server MUST NOT generate an error when Claims are not returned, whether they are Essential or Voluntary.

value

OPTIONAL. Requests that the Claim be returned with a particular value. For instance the Claim request:

  "sub": {"value": "248289761001"}

can be used to specify that the request apply to the End-User with subject identifier 248289761001.

The value of the value member MUST be a valid value for the Claim being requested. Definitions of individual Claims can include requirements on how and whether the value qualifier is to be used when requesting that Claim.

values

OPTIONAL. Requests that the Claim be returned with one of a set of values, with the values appearing in order of preference. For instance the Claim request:

  "acr": {"essential": true,
          "values": ["urn:mace:incommon:iap:silver",
                     "urn:mace:incommon:iap:bronze"]}

specifies that it is Essential that the acr Claim be returned with either the value urn:mace:incommon:iap:silver or urn:mace:incommon:iap:bronze.

The values in the values member array MUST be valid values for the Claim being requested. Definitions of individual Claims can include requirements on how and whether the values qualifier is to be used when requesting that Claim.

Other members MAY be defined to provide additional information about the requested Claims. Any members used that are not understood MUST be ignored.

Note that when the claims request parameter is supported, the scope values that request Claims, as defined in Section 3.1 (Requesting Claims via Scope values), are effectively shorthand methods for requesting sets of individual Claims. For example, using the scope value openid email and a response_type that returns an Access Token is equivalent to using the scope value openid and the following request for individual Claims.

Equivalent of using the email scope value:

  {
   "userinfo":
    {
     "email": null,
     "email_verified": null
    }
  }

3.2.2.  Languages and Scripts for Individual Claims

As described in Section 4.2 (Claims Languages and Scripts), human-readable Claims values and Claim Values that reference human-readable values MAY be represented in multiple languages and scripts. Within a request for individual Claims, requested languages and scripts for particular Claims MAY be requested by including Claim Names that contain #-separated BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tags in the Claims request, using the Claim Name syntax specified in Section 4.2 (Claims Languages and Scripts). For example, a Family Name in Katakana in Japanese can be requested using the Claim Name family_name#ja-Kana-JP and a Kanji representation of the Family Name in Japanese can be requested using the Claim Name family_name#ja-Hani-JP. A German-language Web site can be requested with the Claim Name website#de.

If an OP receives a request for human-readable Claims in a language and script that it doesn't have, any versions of those Claims returned that don't use the requested language and script SHOULD use a language tag in the Claim Name.

4.  Standard Claims

This specification defines a set of standard Claims. They can be requested to be returned either in the UserInfo Response or in the ID Token.

For privacy reasons, OpenID Providers MAY elect to not return values for some requested Claims.

The sub (subject) Claim in the UserInfo Endpoint response MUST exactly match the sub Claim in the ID Token, before using additional UserInfo Endpoint Claims.

The UserInfo Endpoint MUST return Claims in JSON format unless a different format was specified during Registration [OpenID.Registration] (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” July 2013.). The UserInfo Endpoint MAY return Claims in JWT format, which can be signed and/or encrypted. The UserInfo Endpoint MUST return a content-type header to indicate which format is being returned. The following are accepted content types:

The following is a non-normative example of such a response:

  {
   "sub": "248289761001",
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "preferred_username": "j.doe",
   "email": "janedoe@example.com",
   "picture": "http://example.com/janedoe/me.jpg"
  }

4.1.  Address Claim

The Address Claim represents a physical mailing address. Implementations MAY return only a subset of the fields of an address, depending upon the information available and the End-User's privacy preferences. For example, the country and region might be returned without returning more fine-grained address information.

Implementations MAY return just the full address as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields are combined.

formatted

Full mailing address, formatted for display or use on a mailing label. This field MAY contain multiple lines, separated by newline characters.

street_address

Full street address component, which MAY include house number, street name, Post Office Box, and multi-line extended street address information. This field MAY contain multiple lines, separated by newline characters.

locality

City or locality component.

region

State, province, prefecture or region component.

postal_code

Zip code or postal code component.

country

Country name component.

4.2.  Claims Languages and Scripts

Human-readable Claim Values and Claim Values that reference human-readable values MAY be represented in multiple languages and scripts. To specify the languages and scripts, BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tags are added to member names, delimited by a # character. For example, family_name#ja-Kana-JP expresses the Family Name in Katakana in Japanese, which is commonly used to index and represent the phonetics of the Kanji representation of the same represented as family_name#ja-Hani-JP. As another example, both website and website#de Claim Values might be returned, referencing a Web site in an unspecified language and a Web site in German.

Since Claim Names are case sensitive, it is strongly RECOMMENDED that language tag values used in Claim Names be spelled using the character case with which they are registered in the IANA Language Subtag Registry (Internet Assigned Numbers Authority (IANA), “Language Subtag Registry,” 2005.) [IANA.Language]. In particular, normally language names are spelled with lowercase characters, region names are spelled with uppercase characters, and scripts are spelled with mixed case characters. However, since BCP47 language tag values are case insensitive, implementations SHOULD interpret the language tag values supplied in a case insensitive manner.

Per the recommendations in BCP47, language tag values for Claims SHOULD only be as specific as necessary. For instance, using fr might be sufficient in many contexts, rather than fr-CA or fr-FR. Where possible, OPs SHOULD try to match requested Claim locales with Claims it has. For instance, if the Client asks for a Claim with a de (German) language tag and the OP has a value tagged with de-CH (Swiss German) and no generic German value, it would be appropriate for the OP to return the Swiss German value to the Client. (This intentionally moves as much of the complexity of language tag matching to the OP as possible, to simplify Clients.)

A claims_locales request can be used to specify the preferred languages and scripts to use for the returned Claims. Section 3.2.2 (Languages and Scripts for Individual Claims) describes how to request that specific Claims use particular languages and scripts.

When the OP determines, either through the claims_locales parameter, or by other means, that the End-User and Client are requesting Claims in only one set of languages and scripts, it is RECOMMENDED that OPs return Claims without language tags when they employ this language and script. It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims using language tags.

4.3.  Claim Stability and Uniqueness

The sub (subject) and iss (issuer) Claims are the only Claims that a Client can rely upon as a stable identifier for the End-User, since the sub Claim MUST be locally unique and never reassigned within the Issuer for a particular End-User, as described in [OpenID.Messages] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” July 2013.). Therefore, the only guaranteed unique identifier for a given End-User is the combination of the iss Claim and the sub Claim.

All other Claims carry no such guarantees across different issuers in terms of stability over time or uniqueness across users, and Issuers are permitted to apply local restrictions and policies. For instance, an Issuer MAY re-use an email Claim value across different End-Users at different points in time, and the claimed email address for a given End-User MAY change over time. Therefore, other Claims such as email, phone_number, and preferred_username and MUST NOT be used as unique identifiers for the End-User.

4.4.  Additional Claims

While this specification defines only small set of Claims as standard Claims, other Claims MAY be used in conjunction with the standard Claims. When using such Claims, it is RECOMMENDED that collision resistant names be used for the Claim Names, as described in Section 4.2 (Public Claim Names) of the JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] specification. Alternatively, Private Claim Names can be safely used when naming conflicts are unlikely to arise, as described in 4.3 of the JWT specification. Or, if specific additional Claims will have broad and general applicability, they can be registered with Reserved Claim Names, per Sections 4.1 and 9.1 of the JWT specification.

4.5.  new section

5.  Claim Types

The UserInfo Endpoint MAY return the following three types of Claims:

Normal Claims

Claims that are directly asserted by the OpenID Provider.

Aggregated Claims

Claims that are asserted by a Claims Provider other than the OpenID Provider but are returned by OpenID Provider.

Distributed Claims

Claims that are asserted by a Claims Provider other than the OpenID Provider but are returned as references by the OpenID Provider.

The UserInfo Endpoint MUST support Normal Claims.

Aggregated and Distributed Claims support is OPTIONAL.

5.1.  Normal Claims

Normal Claims are represented as members in a JSON object. The Claim Name is the member name and the Claim Value is the member value.

The following is a non-normative response containing Normal Claims:

  {
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "email": "janedoe@example.com",
   "picture": "http://example.com/janedoe/me.jpg"
  }

5.2.  Aggregated and Distributed Claims

Aggregated and distributed Claims are represented by using special _claim_names and _claim_sources members of the JSON object containing the Claims.

_claim_names

JSON object whose member names are the Claim Names for the Aggregated and Distributed Claims. The member values are references to the member names in the _claim_sources member from which the actual Claim Values can be retrieved.

_claim_sources

JSON object whose member names are referenced by the member values of the _claim_names member. The member values contain sets of Aggregated Claims or reference locations for Distributed Claims. The member values can have one of the following formats depending on whether it is providing Aggregated or Distributed Claims:

Aggregated Claims

JSON object that MUST contain the JWT member whose value is a JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] that MUST contain all the Claims in the _claim_names object that references the corresponding _claim_sources member. Other members MAY be present. Any members used that are not understood MUST be ignored.

JWT

REQUIRED. JWT containing Claim Values.

The JWT SHOULD NOT contain a sub (subject) Claim unless its value is an identifier for the End-User at the Claims Provider (and not for the OpenID Provider or another party); this typically means that a sub Claim SHOULD NOT be provided.

Distributed Claims

JSON object that contains the following members and values:

endpoint

REQUIRED. OAuth 2.0 resource endpoint from which the associated Claim can be retrieved. The endpoint URL MUST return the Claim as a JWT.

access_token

OPTIONAL. Access Token enabling retrieval of the Claims from the endpoint URL by using the OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] protocol. Claims SHOULD be requested using the Authorization Request header field and Claims Providers MUST support this method. If the Access Token is not available, Clients MAY need to retrieve the Access Token out of band or use an a priori Access Token that was negotiated between the Claims Provider and Client, or the Claims Provider MAY reauthenticate the End-User and/or reauthorize the Client.

A sub (subject) Claim SHOULD NOT be returned from the Claims Provider unless its value is an identifier for the End-User at the Claims Provider (and not for the OpenID Provider or another party); this typically means that a sub Claim SHOULD NOT be provided.

5.2.1.  Example of Aggregated Claims

In this non-normative example, Claims from Claims Provider A are combined with other Claims held by the OpenID provider, with the Claims from Claims Provider A being returned as Aggregated Claims.

In this example, these Claims about Jane Doe have been issued by Claims Provider A:

  {
   "address": {
     "street_address": "1234 Hollywood Blvd.",
     "locality": "Los Angeles",
     "region": "CA",
     "postal_code": "90210",
     "country": "US"},
   "phone_number": "+1 (310) 123-4567"
  }

Claims Provider A signs the JSON Claims, representing them in a signed JWT: jwt_header.jwt_part2.jwt_part3. It is this JWT that is used by the OpenID Provider.

In this example, this JWT containing Jane Doe's Aggregated Claims from Claims Provider A is combined with other Normal Claims, and returned as the following set of Claims:

  {
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "birthdate": "0000-03-22",
   "eye_color": "blue",
   "email": "janedoe@example.com",
   "_claim_names": {
     "address": "src1",
     "phone_number": "src1"
   },
   "_claim_sources": {
     "src1": {"JWT": "jwt_header.jwt_part2.jwt_part3"}
   }
  }

5.2.2.  Example of Distributed Claims

In this non-normative example, the OpenID Provider combines Normal Claims that it holds with references to Claims held by two different Claims Providers, B and C, incorporating references to some of the Claims held by B and C as Distributed Claims.

In this example, these Claims about Jane Doe are held by Claims Provider B (Jane Doe's bank):

  {
   "shipping_address": {
     "street_address": "1234 Hollywood Blvd.",
     "locality": "Los Angeles",
     "region": "CA",
     "postal_code": "90210",
     "country": "US"},
   "payment_info": "Some_Card 1234 5678 9012 3456",
   "phone_number": "+1 (310) 123-4567"
  }

Also in this example, this Claim about Jane Doe is held by Claims Provider C (a credit agency):

  {
   "credit_score": 650
  }

The OpenID Provider returns Jane Doe's Claims along with references to the Distributed Claims from Claims Provider B and Claims Provider C by sending the Access Tokens and URLs of locations from which the Distributed Claims can be retrieved:

  {
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "email": "janedoe@example.com",
   "birthdate": "0000-03-22",
   "eye_color": "blue",
   "_claim_names": {
     "payment_info": "src1",
     "shipping_address": "src1",
     "credit_score": "src2"
    },
   "_claim_sources": {
     "src1": {"endpoint":
                "https://bank.example.com/claim_source"},
     "src2": {"endpoint":
                "https://creditagency.example.com/claims_here",
              "access_token": "ksj3n283dke"}
   }
  }

6.  UserInfo Endpoint

The UserInfo Endpoint is an OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] Protected Resource that returns Claims about the authenticated End-User. To obtain the requested Claims about the End-User, the Client makes a GET or POST request to the UserInfo Endpoint as stated below.

Communication between the Client and the UserInfo Endpoint MUST utilize TLS. See TLS Requirements in OpenID Connect Messages for more information on using TLS.

The UserInfo Endpoint MUST support the use of the HTTP GET and HTTP POST methods defined in RFC 2616 (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616] at the UserInfo Endpoint.

The UserInfo Endpoint MUST accept Access Tokens as OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750].

The UserInfo Endpoint SHOULD support the use of Cross Origin Resource Sharing (CORS) (Opera Software ASA, “Cross-Origin Resource Sharing,” July 2010.) [CORS] and or other methods as appropriate to enable Java Script Clients to access the endpoint.

6.1.  UserInfo Request

Clients sends either an HTTPS GET or POST request to the UserInfo Endpoint to obtain Claims about the End-User request as specified in section 2 of the OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] specification. The Access Token that is sent MUST be the one obtained from OpenID Connect Authentication.

It is RECOMMENDED that the Client use the Authorization header field method for all requests and that they use the GET method.

The following is a non-normative example of a UserInfo request:

  GET /userinfo HTTP/1.1
  Host: server.example.com
  Authorization: Bearer SlAV32hkKG

6.2.  UserInfo Response

The UserInfo Claims MUST be returned as the members of a JSON object unless a signed or encrypted response was requested during Client Registration. The Standard Claims defined in OpenID Connect Messages (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” July 2013.) [OpenID.Messages] can be returned, as can additional Claims not specified there. It MUST be returned in the HTTP response body unless a different format was specified during Registration [OpenID.Registration] (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” July 2013.). The content-type of the HTTP response MUST be set to application/json if the response body is a text JSON structure; the response body SHOULD be encoded using UTF-8. If the JSON response is signed or encrypted, then the content-type MUST be set to application/jwt.

If a Claim is not returned, that Claim Name SHOULD be omitted from the JSON object representing the Claims; it SHOULD NOT be present with a null or empty string value.

The sub (subject) Claim MUST always be returned in the UserInfo Response.

NOTE: The UserInfo Endpoint response is not guaranteed to be about the End-User identified by the sub (subject) element of the ID Token. The sub Claim in the UserInfo Endpoint response MUST be verified to exactly match the sub Claim in the ID Token before using additional UserInfo Endpoint Claims.

Upon receipt of the UserInfo Response, the Client MUST verify the response in accordance with Section 6.3 (UserInfo Response Validation).

Following is a non-normative example of such response:

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
   "sub": "248289761001",
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "email": "janedoe@example.com",
   "picture": "http://example.com/janedoe/me.jpg"
  }

6.3.  UserInfo Response Validation

To validate the UserInfo Response, the Client MUST do the following:

1. If the Client has provided a userinfo_encrypted_response_alg parameter during Registration, decrypt the UserInfo Response using the key pair specified during Registration.
2. If the response was signed, the Client SHOULD validate the signature according to JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS].
3. Check that the OP that responded was the intended OP through a TLS server certificate check, per RFC 6125 (Saint-Andre, P. and J. Hodges, “Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS),” March 2011.) [RFC6125].

6.4.  UserInfo Error Response

When an error condition occurs, the UserInfo Endpoint returns an Error Response as defined in Section 3 of the OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] specification utilizing an error code as specified in Section 2.3.3 of OpenID Connect Messages 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” July 2013.) [OpenID.Messages].

Following is a non-normative example of an error response:

  HTTP/1.1 401 Unauthorized
  WWW-Authenticate: Bearer realm="example.com",
                       error="invalid_token",
                       error_description="The Access Token expired"

7.  Offline Access

The offline_access scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the End-User is not present (not logged in). When offline access is requested, a prompt parameter value of consent MUST be used unless other conditions for processing permitting offline access to the requested resources are in place. The OP MUST always obtain consent to returning a Refresh Token that enables offline access to the requested resources. A previously saved user consent is not always sufficient to grant offline access.

Upon receipt of a scope parameter containing the offline_access value, the Authorization Server:

• MUST ensure that the prompt parameter contains consent unless other conditions for processing permitting offline access to the requested resources are in place; unless one or both of these conditions are fulfilled, then it MUST ignore the offline_access request,
• MUST ignore the offline_access request unless the Client is using a response_type value that would result in an Authorization Code being returned,
• MUST explicitly receive or have consent for all Clients when the registered application_type is web,
• SHOULD explicitly receive or have consent for all Clients when the registered application_type is native.

The use of Refresh Tokens is not exclusive to the offline_access use case. The Authorization Server MAY grant Refresh Tokens in other contexts that are beyond the scope of this specification.

8.  Security Considerations

For Security Considerations, refer to [OpenID.Messages] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” July 2013.).

9.  Privacy Considerations

For Privacy Considerations, refer to [OpenID.Messages] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” July 2013.).

10.  IANA Considerations

10.1.  JSON Web Token Claims Registry

This specification registers the Claims defined in Section 4 (Standard Claims) in the IANA JSON Web Token Claims registry defined in [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).

10.1.1.  Registry Contents

• Claim Name: name
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: given_name
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: family_name
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: middle_name
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: nickname
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: preferred_username
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: profile
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: picture
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: website
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: email
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: email_verified
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: gender
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: birthdate
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: zoneinfo
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: locale
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: phone_number
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: address
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

• Claim Name: updated_at
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4 (Standard Claims) of this document

10.2.  OAuth Parameters Registry

This specification registers the following parameters in the IANA OAuth Parameters registry defined in RFC 6749 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

10.2.1.  Registry Contents

• Parameter name: claims
• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.2 (Requesting Claims via claims parameter) of this document
• Related information: None

• Parameter name: claims_locales

• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.2 (Requesting Claims via claims parameter) of this document
• Related information: None

11.  References

11.1. Normative References

11.2. Informative References

Appendix A.  Acknowledgements

The OpenID Community would like to thank the following people for the work they've done in the drafting and editing of this specification.

Naveen Agarwal (naa@google.com), Google

Amanda Anganes (aanganes@mitre.org), Mitre

John Bradley (ve7jtb@ve7jtb.com), Ping Identity

Tim Bray (tbray@textuality.com), Google

Brian Campbell (bcampbell@pingidentity.com), Ping Identity

Blaine Cook (romeda@gmail.com), Independent

Breno de Medeiros (breno@gmail.com), Google

Vladimir Dzhuvinov (vladimir@nimbusds.com), Nimbus Directory Services

George Fletcher (gffletch@aol.com), AOL

Roland Hedberg (roland.hedberg@adm.umu.se), University of Umea

Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc.

Michael B. Jones (mbj@microsoft.com), Microsoft

Torsten Lodderstedt (t.lodderstedt@telecom.de), Deutsche Telekom

Hideki Nara (hdknr@ic-tact.co.jp), Tact Communications

Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom

Justin Richer (jricher@mitre.org), Mitre

Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.

Appendix B.  Notices

Copyright (c) 2013 The OpenID Foundation.

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.

Appendix C.  Document History

[[ To be removed from the final specification ]]

00-

• Initial Refactored version.

Authors' Addresses