TOC |
|
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 RESTful manner.
OpenID Connect Basic Client Profile is a profile of the OpenID Connect Standard 1.0 Specification that is designed to be easy to read and implement for basic web-based Relying Parties using the OAuth code grant type. OpenID Providers should consult the Standard specification. This profile omits implementation and security considerations for OpenID Providers.
1.
Introduction
1.1.
Requirements Notation and Conventions
1.2.
Terminology
2.
Protocol Flows
2.1.
OpenID Connect Scopes
2.2.
Code Flow
2.2.1.
Client Prepares an Authorization Request
2.2.2.
Client sends a request to the Authorization Server
2.2.3.
Authorization Server Authenticates the End-User
2.2.4.
Authorization Server Obtains the End-User Consent/Authorization
2.2.5.
Authorization Server Sends the End-User Back to the Client
2.2.5.1.
End-User Grants Authorization
2.2.5.2.
End-User Denies Authorization or Invalid Request
2.2.6.
Client obtains ID Token and Access Token
2.2.6.1.
Client sends the code
2.2.6.2.
Client receives tokens
2.3.
ID Token
2.4.
ID Token Verification
2.5.
UserInfo Endpoint
2.5.1.
UserInfo Request
2.5.2.
UserInfo Response
2.5.2.1.
Address Claim
2.5.2.2.
Claim Stability and Uniqueness
2.5.3.
UserInfo Error Response
3.
Discovery and Registration
4.
Query String Serialization
5.
Form Serialization
6.
String Operations
7.
Security Considerations
8.
Privacy Considerations
9.
IANA Considerations
10.
References
10.1.
Normative References
10.2.
Informative References
Appendix A.
Acknowledgements
Appendix B.
Notices
Appendix C.
Document History
§
Authors' Addresses
TOC |
OpenID Connect Basic Client Profile is a profile of the OpenID Connect Standard 1.0 Specification (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” June 2012.) [OpenID.Standard] that is designed to be easy to read and implement for basic web-based Relying Parties using the OAuth code grant type. See the OpenID Connect Implicit Client Profile (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Implicit Client Profile 1.0,” June 2012.) [OpenID.Implicit] specification for a related profile for basic web-based Relying Parties using the OAuth implicit grant type. OpenID Providers and non web-based applications should consult the Standard specification. This profile omits implementation and security considerations for OpenID Providers.
TOC |
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.
TOC |
This specification uses the terms "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", and "Token Endpoint" defined by OAuth 2.0 (Hammer, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Framework,” June 2012.) [OAuth2.0]. This specification also defines the following terms:
- Relying Party (RP)
- Application requiring Claims from an OpenID Provider
- OpenID Provider (OP)
- Service capable of providing Claims to a Relying Party
- Claim
- Piece of information about an Entity that a Claims Provider asserts about that Entity
- Claims Provider
- Server that can return Claims about an Entity
- End-User
- Human Resource Owner
- Entity
- Something that has a separate and distinct existence and that can be identified in a context. An End-User is one example of an Entity
- Personally Identifiable Information (PII)
- Information that (a) can be used to identify the natural person to whom such information relates, or (b) is or might be directly or indirectly linked to a natural person to whom such information relates.
- Pairwise Pseudonymous Identifier (PPID)
- Identifier that identifies the Entity to a Relying Party that cannot be correlated with the Entity's PPID at another Relying Party
- ID Token
- JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” May 2012.) [JWT] that contains Claims about the authentication event
- Issuer
- Entity that issues a set of Claims.
- Issuer Identifier
- HTTPS URL that acts as a verifiable identifier for an Issuer
- UserInfo Endpoint
- Protected resource that, when presented with an Access Token by the Client, returns authorized information about the End-User represented by the corresponding Authorization Grant
TOC |
Authorization Requests can follow one of two paths; the Implicit Flow or the Authorization Code Flow. The Authorization Code Flow is suitable for Clients that can securely maintain a Client Secret between themselves and the Authorization Server whereas, the Implicit Flow is suitable for Clients that cannot. Clients that do not support TLS MUST use the Authorization Code Flow to prevent the interception of Access Tokens.
The OpenID Connect Basic Client profile only documents Clients using the Code Flow. OpenID Providers MUST support both flows. OpenID Providers should consult the OpenID Connect Standard 1.0 Specification (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” June 2012.) [OpenID.Standard].
TOC |
OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 (Hammer, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Framework,” June 2012.) [OAuth2.0] to specify what access privileges are 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 from the UserInfo Endpoint, and to request an ID Token. OAuth 2.0 allows additional scope values to be specified, as extensions. This specification describes only the scope values used by OpenID Connect.
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 request MUST NOT be treated as an OpenID Connect request. This scope value requests access to the user_id Claim at the UserInfo Endpoint.
- profile
- OPTIONAL. This scope value requests that access to the End-User's default profile Claims (Reserved Member Definitions) at the UserInfo Endpoint be granted by the issued Access Token. These claims are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthday, zoneinfo, locale, and updated_time.
- OPTIONAL. This scope value requests that access to the email and email_verified Claims at the UserInfo Endpoint be granted by the issued Access Token.
- address
- OPTIONAL. This scope value requests that access to the address Claim at the UserInfo Endpoint be granted by the issued Access Token.
- phone
- OPTIONAL. This scope value requests that access to the phone_number Claim at the UserInfo Endpoint be granted by the issued Access Token.
Multiple scopes MAY be requested by creating a space delimited, case sensitive list of ASCII scope values.
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 increase new account activation, a Client may 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.
scope=openid profile email phone
TOC |
The Code Flow consists of the following steps:
TOC |
When the Client wishes to access a Protected Resource, and the End-User Authorization has not yet been obtained, the Client prepares an Authorization Request to the Authorization Endpoint.
The scheme used in the Authorization Endpoint URL MUST be HTTPS.
Clients MAY construct the request using the HTTP GET or the HTTP POST method as 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].
If using the HTTP GET method, the parameters are serialized using Query String Serialization (Query String Serialization). If using the HTTP POST method, the request parameters are added to the HTTP request entity-body using the application/x-www-form-urlencoded format as defined by [W3C.REC‑html401‑19991224] (Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” December 1999.).
This profile further constrains the following request parameters:
- response_type
- It MUST be code. This requests that both an Access Token and an ID Token be returned from the Token Endpoint in exchange to code.
Other REQUIRED parameters in the request include the following:
- client_id
- The OAuth 2.0 Client Identifier.
- scope
- It MUST include openid as one of the space delimited ASCII strings. OPTIONAL scope strings of profile, email, address, and phone are also supported.
- redirect_uri
- A redirection URI where the response will be sent. This MUST be pre-registered with the provider.
The request MAY contain the following OPTIONAL parameters:
- state
- RECOMMENDED. An opaque value used to maintain state between the request and the callback; serves as a protection against XSRF attacks.
- display
- An ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User. The following values are supported:
- page
- The Authorization Server SHOULD display authentication and consent UI consistent with a full user-agent page view. If the display parameter is not specified this is the default display mode.
- popup
- The Authorization Server SHOULD display authentication and consent UI consistent with a popup user-agent window. The popup user-agent window SHOULD be 450 pixels wide and 500 pixels tall.
- touch
- The Authorization Server SHOULD display authentication and consent UI consistent with a device that leverages a touch interface. The Authorization Server MAY attempt to detect the touch device and further customize the interface.
- wap
- The Authorization Server SHOULD display authentication and consent UI consistent with a "feature phone" type display.
- prompt
- A space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The possible values are:
The prompt parameter can be used by the Client to make sure that the End-User is still present for the current session or to bring attention to the request. If this parameter contains none with any other value, an error is returned.
- none
- This value informs the Authorization Server that it MUST NOT display any authentication or consent user interface pages. An error is returned if the End-User is not already authenticated or the Client does not have pre-configured consent for the requested scopes. This can be used as a method to check for existing authentication and/or consent.
- login
- The Authorization Server MUST prompt the End-User for reauthentication.
- consent
- The Authorization Server MUST prompt the End-User for consent before returning information to the Client.
- select_account
- The Authorization Server MUST prompt the End-User to select a user account. This allows a user who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they may have current sessions for.
The following is a non-normative example of an Authorization Request URL (with line wraps for display purposes only):
https://server.example.com/authorize? response_type=code &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb &scope=openid%20profile &state=af0ifjsldkj
TOC |
Having constructed the Authorization Request, the Client sends it to the Authorization Endpoint. This MAY happen via HTTPS redirect, hyperlinking, or any other secure means of directing the User-Agent to the URL.
Following is a non-normative example using HTTP redirect (with line wraps for display purposes only):
HTTP/1.1 302 Found Location: https://server.example.com/authorize? response_type=code &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb &scope=openid%20profile &state=af0ifjsldkj
TOC |
The authorization server authenticates the resource owner to make sure that the consent is obtained from the right party. The exact method of how the authentication is performed is out of scope of this specification.
TOC |
The Authorization Server obtains an authorization decision, for the requested scopes. This can done by presenting the End-User with a dialogue that allows the End-User to recognize what he is consenting to and obtain his consent or by establishing consent via other means (for example, via previous administrative consent).
The openid scope grants the RP access to the user identifier of the authenticated End-User of the session.
All other scopes are optional. It is up to the OpenID Provider to determine if an error should be returned in the case of the End-User declining to authorize scopes other than openid.
TOC |
Once the authorization is determined, the Authorization Server returns a successful response or an error response.
TOC |
If the Resource Owner grants the access request, the Authorization Server issues a code and delivers it to the Client by adding the following query parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format as defined in Section 4.1.2 of OAuth 2.0 (Hammer, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Framework,” June 2012.) [OAuth2.0].
- code
- REQUIRED. The OAuth 2.0 authorization code.
- state
- REQUIRED if the state parameter is present in the client Authorization Request. Clients MUST verify that the state value is equal to the exact value of state parameter in the Authorization Request.
The following is a non-normative example (with line wraps after the second line for the display purposes only):
HTTP/1.1 302 Found Location: https://client.example.org/cb? code=SplxlOBeZQQYbYS6WxSbIA &state=af0ifjsldkj
TOC |
If the End-User denies the authorization or the End-User authentication fails, the Authorization Server MUST return the error authorization response as defined in 4.1.2.1 of OAuth 2.0 (Hammer, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Framework,” June 2012.) [OAuth2.0]. No other parameters SHOULD be returned.
TOC |
Once code is obtained, the Client requests the tokens at the Token Endpoint in the following manner:
TOC |
The Client makes a request to the token endpoint as described in Section 4.1.3 of OAuth 2.0 (Hammer, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Framework,” June 2012.) [OAuth2.0].
The following is a non-normative example of such a token request (with line wraps after the second line for the display purposes only):
POST /token HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded;charset=UTF-8 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
TOC |
- access_token
- REQUIRED. The Access Token for the UserInfo Endpoint.
- token_type
- REQUIRED. The value MUST be "bearer"
- id_token
- REQUIRED. The ID Token.
- expires_in
- OPTIONAL. The expiration time in seconds of the Access Token.
- refresh_token
- OPTIONAL. The Refresh Token.
The Client can then use the Access Token to access protected resources at Resource Servers.
The following is a non-normative example (with line wraps after the second line for the display purposes only):
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"SlAV32hkKG", "token_type":"bearer", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "id_token":"eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso" }
TOC |
The ID Token is a security token that contains Claims about the authentication event and other requested Claims. The ID Token is represented as a JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” May 2012.) [JWT].
The ID Token is used to manage the authentication event and user identifier and is scoped to a particular Client via the aud (audience) and nonce Claims.
The following Claims are REQUIRED within the ID Token:
- iss
- REQUIRED. The Issuer Identifier for the Issuer of the response.
- user_id
- REQUIRED. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client. e.g. 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length.
- aud
- REQUIRED. This member identifies the audience that this ID Token is intended for. It MUST be the OAuth 2.0 client_id of the Client.
- exp
- REQUIRED. Type Integer. Identifies the expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. The value is number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired date/time. See RFC 3339 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] for details regarding date/times in general and UTC in particular.
- iat
- REQUIRED. Type Integer. The iat (issued at) Claim identifies the time at which the JWT was issued. The value is number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired date/time. See RFC 3339 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] for details regarding date/times in general and UTC in particular.
Additional optional claims may be present in the ID Token.
TOC |
To verify the validity of ID Token in the Token Endpoint Response, the Client MUST first split the id_token at the period (".") characters, take the second segment, and base64url decode it to obtain a JSON object that includes the ID Token claims, which MUST be verified as follows:
TOC |
To obtain the additional attributes and tokens, the Client makes a GET or POST request to the UserInfo Endpoint.
UserInfo Endpoint Servers MUST require the use of a transport-layer security mechanism. The UserInfo Endpoint Server MUST support TLS 1.2 RFC 5246 (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) [RFC5246] and/or TLS 1.0 [RFC2246] (Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.) and MAY support other transport-layer mechanisms with equivalent security.
NOTE: The UserInfo Endpoint response is not guaranteed to be about the Interactive user identified by the user_id element of the ID Token. The user_id Claim in the UserInfo Endpoint response MUST exactly match the user_id Claim in the ID Token, before using additional UserInfo Endpoint Claims.
TOC |
Clients MAY send requests with the following parameters to the UserInfo Endpoint to obtain further information about the End-User. The UserInfo Endpoint is an OAuth 2.0 (Hammer, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Framework,” June 2012.) [OAuth2.0] Protected Resource that complies with the OAuth 2.0 Bearer Tokens (Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” June 2012.) [OAuth.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 the HTTP Authorization header or a form-encoded HTTP POST body parameter.
- schema
- REQUIRED. The schema in which the data is to be returned. The only defined value is openid.
- id
- This identifier is reserved. It MUST be ignored by the endpoint when the openid schema is used.
The following is a non-normative example:
GET /userinfo?schema=openid HTTP/1.1 Host: server.example.com Authorization: Bearer SlAV32hkKG
TOC |
If the requested schema is openid, the response MUST return a JSON object that contains the full set or subset of Claims that are defined below. Additional Claims (not specified below) MAY also be returned.
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 members 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 member names delimited by a #, e.g., family_name#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 family_name#ja-Hani-JP.
Member | Type | Description |
---|---|---|
user_id | string | REQUIRED Identifier for the End-User at the Issuer. |
name | string | End-User's full name in displayable form including all name parts, ordered according to End-User's locale and preferences. |
given_name | string | Given name or first name of the End-User. |
family_name | string | Surname or last name of the End-User. |
middle_name | string | Middle name of the End-User. |
nickname | string | Casual name of the End-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. |
preferred_username | string | Shorthand name that the End-User wishes to be referred to at the RP, such as janedoe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace. This value MUST NOT be relied upon to be unique by the RP. (See Section 2.5.2.2 (Claim Stability and Uniqueness).) |
profile | string | URL of the End-User's profile page. |
picture | string | URL of the End-User's profile picture. |
website | string | URL of the End-User's web page or blog. |
string | The End-User's preferred e-mail address. This value MUST NOT be relied upon to be unique by the RP. (See Section 2.5.2.2 (Claim Stability and Uniqueness).) | |
email_verified | boolean | True if the End-User's e-mail address has been verified; otherwise false. |
gender | string | The End-User's gender: Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable. |
birthday | string | The End-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.) time zone database. For example, Europe/Paris or America/Los_Angeles. |
locale | string | The End-User's locale, represented as a BCP47 (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 End-User's preferred telephone number. E.164 (International Telecommunication Union, “E.164: The international public telecommunication numbering plan,” 2010.) [E.164] is RECOMMENDED as the format of this Claim. For example, +1 (425) 555-1212 or +56 (2) 687 2400. |
address | JSON object | The End-User's preferred address. The value of the address member is a JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] structure containing some or all of the members defined in Section 2.5.2.1 (Address Claim). |
updated_time | string | Time the End-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 Member Definitions |
Following is a non-normative example of such a response:
{ "user_id": "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" }
The UserInfo Endpoint MUST return Claims in JSON format unless a different format was specified during OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2012.) [OpenID.Registration]. 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 | JSON Web Token (JWT) |
TOC |
The components of 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 SHOULD be combined.
- formatted
- The full mailing address, formatted for display or use with a mailing label. This field MAY contain newlines. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.
- street_address
- The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This field MAY contain newlines.
- locality
- The city or locality component.
- region
- The state, province, prefecture or region component.
- postal_code
- The zip code or postal code component.
- country
- The country name component.
TOC |
The user_id claim is the only claim that a client can rely upon to be stable, since the user_id claim MUST be locally unique and never reassigned within the Issuer for a particular End-User, as described in Section 2.3 (ID Token).
Therefore, the only guaranteed unique identifier for a given End-User is a combination of the Issuer's identifier and the user_id claim; other fields such as preferred_username and email MUST NOT be used as unique identifiers for a given End-User.
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 a given preferred_username or email address claim across different End-Users at different points in time, and the claimed preferred_username or email address for a given End-User MAY change over time.
TOC |
When an error condition occurs, the UserInfo Endpoint returns an Error Response as defined in Section 3 of OAuth 2.0 Bearer Tokens (Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” June 2012.) [OAuth.Bearer].
In addition to the error codes defined in Section 3.1 of OAuth 2.0 Bearer Tokens (Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” June 2012.) [OAuth.Bearer], this specification defines the following error codes:
- invalid_schema
- The requested schema is invalid or unsupported.
TOC |
Some OpenID Connect installations can use a pre-configured set of OpenID Providers and/or Relying Parties. In those cases, it may not be necessary to support dynamic discovery of information about identities or services or dynamic registration of Clients.
However, if installations choose to support unanticipated interactions between Relying Parties and OpenID Providers that do not have pre-configured relationships, they SHOULD accomplish this by implementing the facilities defined in the OpenID Connect Discovery 1.0 (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” May 2012.) [OpenID.Discovery] and OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2012.) [OpenID.Registration] specifications.
TOC |
In order to serialize the parameters using the query string serialization, the Client constructs the string by adding the parameters and values to the query component using the application/x-www-form-urlencoded format as defined by [W3C.REC‑html401‑19991224] (Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” December 1999.).
Following is a non-normative example of such serialization:
GET /authorize?scope=openid&response_type=code &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1 Host: server.example.com
TOC |
Parameters and their values are form serialized by adding the parameter names and values to the entity body of the HTTP request using the application/x-www-form-urlencoded format as defined by [W3C.REC‑html401‑19991224] (Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” December 1999.). Form serialization is typically used in HTTP POST requests.
Following is a non-normative example of such serialization:
POST /authorize HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded scope=openid&response_type=code &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
TOC |
Processing some OpenID Connect messages requires comparing values in the messages to known values. For example, the Claim Names returned by the UserInfo Endpoint might be compared to specific Claim Names such as user_id. Comparing Unicode strings, however, has significant security implications.
Therefore, comparisons between JSON strings and other Unicode strings MUST be performed as specified below:
In several places, this specification uses space delimited lists of strings. In all such cases, only the ASCII space character (0x20) MAY be used for this purpose.
TOC |
For security considerations, refer to the OpenID Connect Standard 1.0 Specification (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” June 2012.) [OpenID.Standard].
TOC |
The UserInfo response typically contains Personally Identifiable Information. As such, End-User consent for the release of the information for the specified purpose SHOULD be obtained at or prior to the authorization time in accordance with relevant regulations. The purpose of use is typically registered in association with the redirect_uri.
Only necessary UserInfo data SHOULD be stored at the Client and the Client SHOULD associate the received data with the purpose of use statement.
The Resource Server SHOULD make the UserInfo access log available to the End-User so that the End-User can monitor who accessed his data.
To protect the End-User from a possible correlation among Clients, the use of a Pairwise Pseudonymous Identifier (PPID) as the user_id SHOULD be considered.
TOC |
This document makes no requests of IANA.
TOC |
TOC |
[E.164] | International Telecommunication Union, “E.164: The international public telecommunication numbering plan,” 2010. |
[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., Bradley, J., and N. Sakimura, “JSON Web Token,” May 2012. |
[OAuth.Bearer] | Jones, M., Hardt, D., and D. Recordon, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” June 2012. |
[OAuth2.0] | Hammer, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Framework,” June 2012. |
[OpenID.Discovery] | Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” May 2012. |
[OpenID.Registration] | Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2012. |
[OpenID.Standard] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” June 2012. |
[RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
[RFC2246] | Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” RFC 2246, January 1999 (TXT). |
[RFC2616] | Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML). |
[RFC3339] | Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML). |
[RFC4627] | Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT). |
[RFC5246] | Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” RFC 5246, August 2008 (TXT). |
[RFC5646] | Phillips, A. and M. Davis, “Tags for Identifying Languages,” BCP 47, RFC 5646, September 2009 (TXT). |
[USA15] | Davis, M., Whistler, K., and M. Dürst, “Unicode Normalization Forms,” Unicode Standard Annex 15, 09 2009. |
[W3C.REC-html401-19991224] | Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (HTML). |
[zoneinfo] | Public Domain, “The tz database,” June 2011. |
TOC |
[OpenID.Implicit] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Implicit Client Profile 1.0,” June 2012. |
TOC |
The OpenID Community would like to thank the following people for the work they've done in the drafting and editing of this specification.
Andreas Akre Solberg (andreas.solberg@uninett.no), UNINET
Anthony Nadalin (tonynad@microsoft.com), Microsoft
Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom
Breno de Medeiros (breno@gmail.com), Google
Casper Biering (cb@peercraft.com), Peercraft
Chuck Mortimore (cmortimore@salesforce.com), Salesforce
David Recordon (dr@fb.com), Facebook
Edmund Jay (ejay@mgi1.com), Illumila
George Fletcher (george.fletcher@corp.aol.com), AOL
Hideki Nara (hideki.nara@gmail.com), Takt Communications
John Bradley (ve7jtb@ve7jtb.com), Ping Identity
Johnny Bufu (jbufu@janrain.com), Janrain
Justin Richer (jricher@mitre.org), Mitre
Luke Shepard (lshepard@fb.com), Facebook
Michael B. Jones (mbj@microsoft.com), Microsoft
Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.
Nov Matake (nov@matake.jp), Independent
Pamela Dingle (pdingle@pingidentity.com), Ping Identity
Paul Tarjan (pt@fb.com), Facebook
Roland Hedberg (roland.hedberg@adm.umu.se), Independent
Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc.
Torsten Lodderstedt (t.lodderstedt@telekom.de), Deutsche Telekom
TOC |
Copyright (c) 2012 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.
TOC |
[[ To be removed from the final specification ]]
-20
-19
-18
-17
-16
-15
-14
-13
-12
-11
-10
-09
-08
-07
-06
-05
-04
-03
-02
-01
TOC |
Nat Sakimura | |
Nomura Research Institute, Ltd. | |
Email: | n-sakimura@nri.co.jp |
John Bradley | |
Ping Identity | |
Email: | ve7jtb@ve7jtb.com |
Michael B. Jones | |
Microsoft | |
Email: | mbj@microsoft.com |
Breno de Medeiros | |
Email: | breno@google.com |
Chuck Mortimore | |
Salesforce | |
Email: | cmortimore@salesforce.com |