OpenID Connect UserInfo 1.0 - draft 03

Abstract

This specification describes the schema and 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.3.  Errors
3.  Other Items for Consideration
4.  IANA Considerations
5.  Security Considerations
6.  References
    6.1.  Normative References
    6.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Document History
§  Authors' Addresses

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,” June 2011.) [OpenID.CC] for terminology used in this specification.

2.  UserInfo Endpoint

The UserInfo Endpoint returns claims for the authenticated user.

Claim objects contain members and member values which are the individual claims and claims values. A claim object is represented by a JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] object which contains a collection of name/value pairs for the claims.

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 complies with the OAuth2 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2.0] Bearer Token (Jones, M., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol: Bearer Tokens,” Jun 2011.) [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 format to support backwards compatibility. Custom scheme names and responses are out of scope for this specification.

id

RESERVED. This 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 (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.

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

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

3.  Other Items for Consideration

4.  IANA Considerations

This document makes no request of IANA.

5.  Security Considerations

6.  References

6.1. Normative References

6.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.

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

Chuck Mortimore (cmortimore@salesforce.com), Salesforce

David Recordon (dr@fb.com)<author>, Facebook

George Fletcher (george.fletcher@corp.aol.com), AOL

John Bradley (jbradely@mac.com) <author>, Protiviti Government Services

Edmund Jay (ejay@mgi1.com), MGI1

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

Nat Sakimura (n-sakimura@nri.co.jp) <author/editor>, Nomura Research Institute, Ltd.

Paul Tarjan (pt@fb.com), Facebook

Ryo Itou (ritou@yahoo-corp.jp), Yahoo! Japan

Appendix B.  Document History

[[ to be removed once the specification is approved ]]

-03

• Added text describing the UserInfo endpoint as an OAuth2 protected resource complying with the OAuth2.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 OAuth2 Bearer Token specification to the list of referenced specifications and corrected the referenced URL in the OAuth2.0 target.

-02

• 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 (Facebook, “Facebook Graph API - User,” June 2011.) [GraphAPI] fields.

-01

• Minor changes to prepare for publication at openid.net/specs/.

-00

• Initial draft incorporating consensus decisions reached at the Internet Identity Workshop (IIW) in May, 2011. The schema specified is based upon Portable Contacts (Smarr, J., “Portable Contacts 1.0 Draft C.,” August 2008.) [POCO].

Authors' Addresses