TOC 
DraftN. Sakimura, Ed.
 NRI
 J. Bradley
 Protiviti
 M. Jones
 Microsoft
 E. Jay
 MGI1
 G. George
 AOL
 July 11, 2011


OpenID Connect UserInfo 1.0 - draft 05

Abstract

This specification describes both the data schema and message format returned by the UserInfo endpoint of OpenID Connect.

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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].



Table of Contents

1.  Terminology
2.  UserInfo Endpoint
    2.1.  Requests
    2.2.  Responses
        2.2.1.  Example Responses
    2.3.  Errors
3.  IANA Considerations
4.  Security Considerations
5.  References
    5.1.  Normative References
    5.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Document History
§  Authors' Addresses




 TOC 

1.  Terminology

See OpenID Connect Core (Recordon, D., Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Core 1.0,” July 2011.) [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.



 TOC 

2.  UserInfo Endpoint

The UserInfo endpoint returns a set of claims for the authenticated user.



 TOC 

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 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth.2.0] protected resource that complies with the Bearer Token (Jones, M., Ed., Hardt, D., and D. Recordon, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 2011.) [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 NOT be sent if the access token is sent in the HTTP Authorization header.
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.


 TOC 

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 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [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.



ClaimTypeDescription
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] (Public Domain, “The tz database,” June 2011.) timezone database. For example, "Europe/Paris" or "America/Los_Angeles".
locale string The user's locale, represented as an RFC 5646 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 (International Organization for Standardization, “ISO 639-1:2002. Codes for the representation of names of languages -- Part 1: Alpha-2 code,” 2002.) [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 (International Organization for Standardization, “ISO 3166-1:1997. Codes for the representation of names of countries and their subdivisions -- Part 1: Country codes,” 1997.) [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 object The user's preferred address. The value 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 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [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 request. See the OpenID Connect Framework (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Framework 1.0,” July 2011.) [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-TypeFormat Returned
application/json plain text JSON object
application/jwt A JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” March 2011.) [JWT]



 TOC 

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"
}



 TOC 

2.3.  Errors

In addition to the standard OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [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:

unsupported_schema
The requested schema is unsupported.


 TOC 

3.  IANA Considerations

This document makes no request of IANA.



 TOC 

4.  Security Considerations



 TOC 

5.  References



 TOC 

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,” March 2011.
[OAuth.2.0] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.
[OAuth.2.0.Bearer] Jones, M., Ed., Hardt, D., and D. Recordon, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 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 (TXT, HTML, XML).
[RFC3339] Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML).
[RFC5646] Phillips, A. and M. Davis, “Tags for Identifying Languages,” BCP 47, RFC 5646, September 2009 (TXT).
[zoneinfo] Public Domain, “The tz database,” June 2011.


 TOC 

5.2. Informative References

[GraphAPI] Facebook, “Facebook Graph API - User,” June 2011.
[POCO] Smarr, J., “Portable Contacts 1.0 Draft C.,” August 2008.


 TOC 

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



 TOC 

Appendix B.  Document History

[[ To be removed from the final specification ]]

-05

-04

-03

-02

-01

-00



 TOC 

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