Draft N. Sakimura, Ed. NRI J. Bradley Protiviti M. Jones Microsoft E. Jay MGI1 G. George AOL July 28, 2011 OpenID Connect UserInfo 1.0 - draft 06 Abstract This specification describes both the data schema and message format returned by the UserInfo endpoint of OpenID Connect. Sakimura, et al. [Page 1] OpenID Connect UserInfo 1.0 - draft 06 July 2011 Requirements Language 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 RFC 2119 [RFC2119]. Table of Contents 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. UserInfo Endpoint . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2.1. Example Responses . . . . . . . . . . . . . . . . . . 7 2.3. Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.1. Normative References . . . . . . . . . . . . . . . . . . . 11 5.2. Informative References . . . . . . . . . . . . . . . . . . 12 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 13 Appendix B. Document History . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 Sakimura, et al. [Page 2] OpenID Connect UserInfo 1.0 - draft 06 July 2011 1. Terminology See OpenID Connect Core [OpenID.Core] for terminology used in this specification. In addition to the terms defined in the Core specification, the following terms are defined: Schema Defines both the structure and the set of claims returned by the UserInfo endpoint. This specification defines the "openid" schema. Format The message format of the UserInfo endpoint response. By default, the format is a plain text JSON object. Sakimura, et al. [Page 3] OpenID Connect UserInfo 1.0 - draft 06 July 2011 2. UserInfo Endpoint The UserInfo endpoint returns a set of claims for the authenticated user. 2.1. Requests Clients MAY send requests with the following parameters to the UserInfo endpoint to obtain further information about the user. The UserInfo endpoint is an OAuth 2.0 [OAuth.2.0] protected resource that complies with the Bearer Token [OAuth.2.0.Bearer] specification. As such, the access token SHOULD be specified via the HTTP Authorization header. access_token REQUIRED. The access_token obtained from an OpenID Connect authorization request. This parameter MUST only be sent using one method through either HTTP Authorization header or query string. schema OPTIONAL. The schema in which the data is to be returned. The only predefined value is "openid". If this parameter is not included, the response may be a proprietary schema to support backwards compatibility. A URL MAY be passed to define custom schemes not specified by short names. Custom schema names and responses are out of scope for this specification. id This identifier is reserved for backwards compatibility. It MUST be ignored by the endpoint if the "openid" schema is used. 2.2. Responses If the requested schema is "openid", the response MUST return a plain text JSON object that contains a set of claims that are a subset of those defined below. Additional claims (not specified below) MAY also be returned. The claims may be represented in multiple languages and scripts. To specify the languages and scripts, BCP47 [RFC5646] language tags MUST be added to each claims delimited by a "#". e.g., "familyName#ja-Kana-JP" for expressing 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 "familyName#ja-Hani-JP". Sakimura, et al. [Page 4] OpenID Connect UserInfo 1.0 - draft 06 July 2011 +--------------+---------+------------------------------------------+ | Claim | Type | Description | +--------------+---------+------------------------------------------+ | id | string | Identifier for the user at the issuer. | | | | | | name | string | User's full name in displayable form | | | | including all name parts, ordered | | | | according to user's locale and | | | | preferences. | | | | | | given_name | string | Given name or first name of the user. | | | | | | family_name | string | Surname or last name of the user. | | | | | | middle_name | string | Middle name of the user. | | | | | | nickname | string | Casual name of the user that may or may | | | | not be the same as the "given_name". | | | | For instance, a "nickname" value of | | | | "Mike" might be returned alongside a | | | | "given_name" value of "Michael". | | | | | | profile | string | URL of user's profile page. | | | | | | picture | string | URL of the user's profile picture. | | | | | | website | string | URL of user's web page or blog. | | | | | | email | string | The user's preferred e-mail address. | | | | | | verified | boolean | True if the user's e-mail address has | | | | been verified; otherwise false. | | | | | | gender | string | The user's gender: "female" or "male". | | | | | | birthday | string | The user's birthday, represented as a | | | | date string in MM/DD/YYYY format. The | | | | year MAY be "0000", indicating that it | | | | is omitted. | | | | | | zoneinfo | string | String from zoneinfo [zoneinfo] timezone | | | | database. For example, "Europe/Paris" | | | | or "America/Los_Angeles". | | | | | Sakimura, et al. [Page 5] OpenID Connect UserInfo 1.0 - draft 06 July 2011 | locale | string | The user's locale, represented as an RFC | | | | 5646 [RFC5646] language tag. This is | | | | typically an ISO 639-1 Alpha-2 | | | | [ISO639-1] language code in lowercase | | | | and an ISO 3166-1 Alpha-2 [ISO3166-1] | | | | country code in uppercase, separated by | | | | a dash. For example, "en-US" or | | | | "fr-CA". As a compatibility note, some | | | | implementations have used an underscore | | | | as the separator rather than a dash, for | | | | example, "en_US"; Implementations MAY | | | | choose to accept this locale syntax as | | | | well. | | | | | | phone_number | string | The user's preferred telephone number. | | | | For example, "+1 (425) 555-1212" or "+56 | | | | (2) 687 2400". | | | | | | address | JSON | The user's preferred address. The value | | | object | of the "address" claim is a JSON | | | | structure containing some or all of | | | | these string-valued fields: "formatted", | | | | "street_address", "locality", "region", | | | | "postal_code", and "country". The | | | | "street_address" field MAY contain | | | | multiple lines if the address | | | | representation requires it. | | | | Implementations MAY return only a subset | | | | of the fields of an "address", depending | | | | upon the information available and the | | | | user's privacy preferences. For | | | | example, the "country" and "region" | | | | might be returned without returning more | | | | fine-grained address information. | | | | | | updated_time | string | Time the user's information was last | | | | updated, represented as a RFC 3339 | | | | [RFC3339] datetime. For example, | | | | "2011-01-03T23:58:42+0000". | +--------------+---------+------------------------------------------+ Table 1: Reserved Claim Definitions For privacy reasons, OpenID providers may elect to not provide values for some schema elements as part of the "openid" scope. The UserInfo endpoint will return claims in JSON format unless a request for a different format is made by the RP in the Authorization Sakimura, et al. [Page 6] OpenID Connect UserInfo 1.0 - draft 06 July 2011 request. See the OpenID Connect Framework [OpenID.Framework] specification on how to request a different format. The UserInfo endpoint MUST return a content-type header to indicate which format is being returned. The following are accepted content types: +------------------+------------------------+ | Content-Type | Format Returned | +------------------+------------------------+ | application/json | plain text JSON object | +------------------+------------------------+ | application/jwt | A JWT [JWT] | +------------------+------------------------+ 2.2.1. Example Responses The following is a non-normative normal claims response: { "id": "90125", "name": "Jonathan Q. Doe" "given_name": "Jonathan", "middle_name": "Q.", "family_name": "Doe", "nickname": "John", "email": "johndoe@example.com", "verified": true, "profile": "http://example.com/johndoe/", "picture": "http://example.com/johndoe/me.jpg", "website": "http://john.doe.blogs.example.net/", "gender": "male", "birthday": "05/02/0000", "zoneinfo": "America/Los_Angeles" "locale": "en_US", "phone_number": "+1 (425) 555-1212", "address": { "region": "WA", "country": "United States" }, "last_updated": "2011-06-29T21:10:22+0000" } 2.3. Errors In addition to the standard OAuth 2.0 [OAuth.2.0] errors, the UserInfo endpoint may return the following errors: The Authorization Server includes one of the following error codes with the error response: Sakimura, et al. [Page 7] OpenID Connect UserInfo 1.0 - draft 06 July 2011 unsupported_schema The requested schema is unsupported. Sakimura, et al. [Page 8] OpenID Connect UserInfo 1.0 - draft 06 July 2011 3. IANA Considerations This document makes no request of IANA. Sakimura, et al. [Page 9] OpenID Connect UserInfo 1.0 - draft 06 July 2011 4. Security Considerations Sakimura, et al. [Page 10] OpenID Connect UserInfo 1.0 - draft 06 July 2011 5. References 5.1. Normative References [ISO3166-1] International Organization for Standardization, "ISO 3166- 1:1997. Codes for the representation of names of countries and their subdivisions -- Part 1: Country codes", 1997. [ISO639-1] International Organization for Standardization, "ISO 639- 1:2002. Codes for the representation of names of languages -- Part 1: Alpha-2 code", 2002. [JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, "JSON Web Token", July 2011. [OAuth.2.0] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "OAuth 2.0 Authorization Protocol", July 2011. [OAuth.2.0.Bearer] Jones, M., Ed., Hardt, D., and D. Recordon, "The OAuth 2.0 Protocol: Bearer Tokens", July 2011. [OpenID.Core] Recordon, D., Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, "OpenID Connect Core 1.0", July 2011. [OpenID.Framework] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect Framework 1.0", July 2011. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009. [zoneinfo] Public Domain, "The tz database", June 2011. Sakimura, et al. [Page 11] OpenID Connect UserInfo 1.0 - draft 06 July 2011 5.2. Informative References [GraphAPI] Facebook, "Facebook Graph API - User", June 2011. [POCO] Smarr, J., "Portable Contacts 1.0 Draft C.", August 2008. Sakimura, et al. [Page 12] OpenID Connect UserInfo 1.0 - draft 06 July 2011 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. Breno de Medeiros (breno@gmail.com), Google Chuck Mortimore (cmortimore@salesforce.com), Salesforce David Recordon (dr@fb.com), Facebook George Fletcher (george.fletcher@corp.aol.com), AOL John Bradley (jbradely@mac.com), Protiviti Government Services Edmund Jay (ejay@mgi1.com), MGI1 Michael B. Jones (mbj@microsoft.com), Microsoft Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd. Paul Tarjan (pt@fb.com), Facebook Ryo Itou (ritou@yahoo-corp.jp), Yahoo! Japan Sakimura, et al. [Page 13] OpenID Connect UserInfo 1.0 - draft 06 July 2011 Appendix B. Document History [[ To be removed from the final specification ]] -06 o Clarified Section 2.1 based on Andrew Arnott's text. -05 o Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call. -04 o Consistency and cleanup pass, including removing unused references. -03 o Added text describing the UserInfo endpoint as an OAuth 2.0 protected resource complying with the OAuth 2.0 Bearer Token specification. Also changed the response text to require the returned JSON object to comply with the specified schema if the schema parameter is "openid". Changed SHOULD to MUST. Added the OAuth 2.0 Bearer Token specification to the list of referenced specifications and corrected the referenced URL in the OAuth 2.0 target. -02 o Converted from Portable Contacts identifiers using camelCase to Facebook-style identifiers using lowercase_separated_by_underscores. Also simplified a number of the fields that used to be structures or arrays so that they are now simple values. Where the same names are used, they are intended to be compatible their usage as Facebook Graph API User [GraphAPI] fields. -01 o Minor changes to prepare for publication at openid.net/specs/. -00 o Initial draft incorporating consensus decisions reached at the Internet Identity Workshop (IIW) in May, 2011. The schema specified is based upon Portable Contacts [POCO]. Sakimura, et al. [Page 14] OpenID Connect UserInfo 1.0 - draft 06 July 2011 Authors' Addresses Nat Sakimura (editor) Nomura Research Institute, Ltd. Email: n-sakimura@nri.co.jp John Bradley Protiviti Government Services Email: jbradley@mac.com Michael B. Jones Microsoft Corporation Email: mbj@microsoft.com Edmund Jay MGI1 Email: ejay@mgi1.com George Fletcher AOL Email: george.fletcher@teamaol.com Sakimura, et al. [Page 15]