Nomura Research Institute, Ltd.

n-sakimura@nri.co.jp

Ping Identity

ve7jtb@ve7jtb.com

Microsoft

mbj@microsoft.com

Google

breno@google.com

Illumila

ejay@mgi1.com

OpenID Connect Working Group 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 Standard 1.0 is an HTTP protocol binding for the OpenID Connect Messages 1.0 request and response messages.

The OAuth 2.0 Authorization Framework and OAuth 2.0 Bearer Token Usage specifications provide a general framework for third-party applications to obtain and use limited access to HTTP resources. They define mechanisms to obtain and use Access Tokens to access resources but do not define standard methods to provide identity information. Notably, without profiling OAuth 2.0, it is incapable of providing information about the authentication of an End-User. This specification is a binding of the messages defined in the OpenID Connect Messages 1.0 specification to RFC6749 and RFC6750, including messages that provide identity and authentication information, allowing services to securely exchange identity information. This binding builds an identity layer on top of OAuth 2.0. Using this specification, deployments are able to share authentication and attributes on OAuth 2.0 based systems.

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 . 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) and JSON Web Encryption (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.

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, and the terms defined by OpenID Connect Messages 1.0. This specification also defines the following terms: Document whose content is a Request Object representing a set of Authorization Request parameters. URL that references a Request File. The Request File contents MUST be retrievable by the Authorization Server. IMPORTANT NOTE TO READERS: The terminology definitions in this section are a normative portion of this specification, imposing requirements upon implementations. All the capitalized words in the text of this specification, such as "Request File", reference these defined terms. Whenever the reader encounters them, their definitions found in this section must be followed.

The Authorization Endpoint performs authentication of the End-User and requests authorization from the End-User to release information to an OpenID Connect Relying Party (Client). When an End-User accesses a Relying Party application that requires the End-User's identity and other information, it sends the End-User to the Authorization Server's Authorization Endpoint for authentication and authorization. The Authorization Server then issues an ID Token that asserts the End-User's identity and an Access Token that allows the Client to access the End-User's information at Protected Resource endpoints. Protected Resource endpoints MAY perform different actions or return different information based on the scopes associated with the presented Access Token. Clients MUST specify how the Access Token and ID Token are to be returned by using the response_type parameter in the Authorization Request.

Authorization Requests follow two main paths to obtain Access Tokens and ID Tokens, the Implicit Flow and the Authorization Code Flow. The flows determine how the Access Token and ID Token are returned to the Client. Access Tokens are credentials used to access Protected Resources, as defined in Section 1.4 of OAuth 2.0. Access Tokens represent a Resource Owner's authorization and MUST NOT be exposed to unauthorized parties. The Implicit Flow is mainly used by Clients implemented in a browser using a scripting language. The Access Token and ID Token are returned directly to the Client, which MAY expose them to the Resource Owner and other applications that have access to the Resource Owner's User-Agent. The Authorization Server does not perform Client Authentication before issuing the Access Token. The Authorization Code Flow returns an Authorization Code to the Client, which can then exchange it for an Access Token directly. This provides the added benefit of not exposing the Access Token to the Resource Owner and possibly other malicious applications with access to the Resource Owner's User-Agent. The Authorization Server can also authenticate the Client before exchanging the Authorization Code for an Access Token. 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.

In this specification, the Client sends the Authorization Request to the Authorization Endpoint through the User-Agent to obtain the ID Token and Access Token. It can obtain them from the Token Endpoint utilizing the Authorization Code that it obtained from the Authorization Endpoint using the Authorization Code Flow or from the Authorization Endpoint using the Implicit Flow.

The Authorization Code Flow goes through the following steps. Client prepares an Authorization Request containing the desired request parameters. Client sends a request to the Authorization Server. Authorization Server Authenticates the End-User. Authorization Server Obtains the End-User Consent/Authorization. Authorization Server Sends the End-User back to the Client with an Authorization Code. Client requests a response using the Authorization Code at the Token Endpoint, per . Client receives a response that contains an Access Token and ID Token in the response body. Client validates the ID Token and retrieves the End-User's subject identifier. (OPTIONAL) Client accesses the UserInfo Endpoint with the Access Token, per . (OPTIONAL) Client receives UserInfo Response. Note that in each step, the party that receives a message MUST validate it according to the validation rules in OpenID Connect Messages 1.0.

The Implicit Flow follows the following steps: Client prepares an Authorization Request containing the desired request parameters. Client sends a request to the Authorization Server. Authorization Server Authenticates the End-User. Authorization Server Obtains the End-User Consent/Authorization. Authorization Server Sends the End-User back to the Client with an Access Token and an ID Token if requested. Client validates the ID Token and retrieves the End-User's subject identifier. (OPTIONAL) Client accesses the UserInfo Endpoint with the Access Token, per . (OPTIONAL) Client receives UserInfo Response. Note that in each step, the party that receives a message MUST validate it according to the validation rules in OpenID Connect Messages 1.0.

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. Communication with the Authorization Endpoint MUST utilize TLS. See for more information on using TLS. Authorization Servers MUST support the use of the HTTP GET and POST methods defined in RFC 2616 at the Authorization Endpoint. Clients MAY use the HTTP GET or POST methods to send the Authorization Request to the Authorization Server. If using the HTTP GET method, the request parameters are serialized using URI Query String Serialization, per . If using the HTTP POST method, the request parameters are serialized using Form Serialization, per .

The Client prepares an Authorization Request to the Authorization Endpoint with the request parameters using the HTTP GET or POST method. The scheme used in the Authorization URL MUST be https.

OpenID Connect uses the following OAuth 2.0 request parameters: REQUIRED. OAuth 2.0 registered response type value that determines how the Authorization Response is returned to the Client. As described in OAuth 2.0 Multiple Response Type Encoding Practices, the following registered values are supported by OpenID Connect: code code id_token id_token id_token token code token code id_token token REQUIRED. OAuth 2.0 Client Identifier. REQUIRED. Space delimited, case sensitive list of ASCII OAuth 2.0 scope values. OpenID Connect requests MUST contain the openid scope value. OPTIONAL scope values of profile, email, address, phone, and offline_access are also defined. Section 2.4 of OpenID Connect Messages 1.0 defines the OpenID Connect scope values. REQUIRED. Redirection URI to which the response will be sent. This MUST be pre-registered with the OpenID Provider. This URI MUST exactly match one of the redirect_uris registered for the Client, with the matching performed as described in Section 6.2.1 of (Simple String Comparison). RECOMMENDED. Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with the browser cookie. This specification also uses the following request parameters. Refer to OpenID Connect Messages 1.0 for more information about these parameters. REQUIRED or OPTIONAL. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. Use of the nonce is REQUIRED when using the implicit flow and OPTIONAL when using the code flow. OPTIONAL. ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User. The defined values are: page, popup, touch, and wap. OPTIONAL. Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are: none, login, consent, and select_account. OPTIONAL. Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User. OPTIONAL. End-User's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 language tag values, ordered by preference. OPTIONAL. End-User's preferred languages and scripts for Claims being returned, represented as a space-separated list of BCP47 language tag values, ordered by preference. OPTIONAL. Previously issued ID Token passed to the Authorization Server as a hint about the End-User's current or past authenticated session with the Client. OPTIONAL. Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary). OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this authentication request, with the values appearing in order of preference. OPTIONAL. This parameter is used to request that specific Claims be returned. The value is a JSON object listing the requested Claims. OPTIONAL. This parameter is used by the Client to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic Client Registration. OPTIONAL. Request Object value. OPTIONAL. URL that references a resource containing a Request Object value.

There are three methods to construct and send the request to the Authorization Endpoint: Simple Request Method Request Parameter Method Request File Method The Simple Request Method can be used in cases where signed or encrypted requests are not needed and where the size of the request does not exceed limits imposed by User-Agents. The Request Parameter Method is used when the Client wants or needs to send an OpenID Connect request as a single, self-contained Request Object value. This method enables requests to be signed and optionally encrypted. Like the Simple Request Method, some requests using this method can exceed limits imposed by User-Agents. The Request File Method works similarly to the Request Parameter Method but differs in that it sends a URL as a reference to the Request Object. It enables large requests to be sent securely and compactly even on User-Agents with limited capabilities. Clients MAY use the Request File Method to minimize the request size.

The Client prepares an Authorization Request to the Authorization Endpoint using the appropriate parameters. If using the HTTP GET method, the request parameters are serialized using URI Query String Serialization, per . If using the HTTP POST method, the request parameters are serialized using Form Serialization, per .

The following is a non-normative example of an Authorization Request URL (with line wraps within values for display purposes only):

Having constructed the Authorization Request, the Client sends it to the Authorization Endpoint using HTTPS.

Following is a non-normative example using HTTP redirect (with line wraps within values for display purposes only):

The Client prepares an Authorization Request to the Authorization Endpoint using the appropriate HTTP parameter serialization. The Client SHOULD construct the request using the HTTP POST method, but MAY use the HTTP GET method. The Authorization Request MUST include the request parameter defined in . The Authorization Request MUST NOT include the request_uri parameter. The request parameter is a Request Object represented as a JWT containing a set of OpenID Connect request parameters. The Request Object MAY be a Plaintext JWT, signed, or signed and encrypted using JWS and/or JWE, thereby enabling authentication, integrity, non-repudiation, and/or confidentiality to be achieved.

The following is a non-normative example of the Claims in a Request Object before base64url encoding and signing:

Signing it with the RS256 algorithm results in this Request Object value (with line wraps within values for display purposes only):

The following is the RSA public key in JWK format that can be used to validate the Request Object signature in this and subsequent Request Object examples (with line wraps within values for display purposes only):

The following is a non-normative example of an Authorization Request using the request parameter (with line wraps within values for display purposes only):

Having constructed the Authorization Request, the Client sends it to the Authorization Endpoint using HTTPS.

Following is a non-normative example using HTTP redirect (with line wraps within values for display purposes only):

The Request File Method differs from the other methods in that it uses a Request File that contains a Request Object. It then sends the Request File URL as part of the Authorization Request. The Client prepares an Authorization Request using the desired HTTP GET or POST method. The Client SHOULD use the HTTP GET method, but MAY use the HTTP POST method. The scheme used in the Authorization URL MUST be https. The Authorization Request MUST NOT include the request parameter. The Authorization Request MUST include the request_uri parameter. The contents of the resource referenced by the URL MUST be a Request Object. The scheme used in the request_uri value MUST be https, unless the target Request Object is signed in a way that is verifiable by the Authorization Server. The request_uri value MUST be reachable by the Authorization Server, and SHOULD be reachable by the Client.

Following is a non-normative example of the contents of a Request File (with line wraps within values for display purposes only):

The Client stores the Request File either locally or remotely at a URL the Server can access. This is the Request URI, request_uri. Servers MAY cache the contents of the files referenced by request URIs. If the contents of the Request File could ever change, the URI SHOULD include the base64url encoded SHA-256 hash of the referenced file contents as the fragment component of the URI. If the fragment value used for a URI changes, that signals the server that any cached value for that URI with the old fragment value is no longer valid. Note that Clients MAY pre-register request_uri values using the request_uris parameter defined in Section 2 of the OpenID Connect Dynamic Client Registration 1.0 specification. OPs can require that request_uri values used be pre-registered with the require_request_uri_registration discovery parameter. If the Request File includes attribute values, it MUST NOT be revealed to anybody but the Authorization Server. As such, the request_uri MUST have appropriate entropy for its lifetime. It is RECOMMENDED that it be removed if it is known that it will not be used again or after a reasonable timeout unless access control measures are taken. The Client then records the Request File either locally or remotely and obtains the Request File URI, request_uri.

Following is a non-normative example (with line wraps within values for display purposes only):

The Client sends the Authorization Request to the Authorization Endpoint. The entire request URL MUST NOT exceed 512 ASCII characters.

Following is a non-normative example (with line wraps within values for display purposes only):

Upon receipt of the Request, the Authorization Server MUST send a GET request to the request_uri to retrieve the content unless it is already cached and parse it to recreate the Authorization Request parameters. Note that the RP SHOULD use a unique URI for each request utilizing distinct parameters, or otherwise prevent the Authorization Server from caching the request_uri.

Following is a non-normative example of this fetch process:

The Authorization Server validates the request according to Section 5.1 of OpenID Connect Messages 1.0.

The Authorization Server validates the request to ensure all REQUIRED parameters are present and all parameters are valid. If the request is valid, the Authorization Server attempts to log in the End-User or determines whether he is logged in, depending upon the request parameter values used. The methods used by the Authorization Server to log in the End-User (e.g. username and password, session cookies, etc.) are beyond the scope of this specification. An authentication user interface MAY be displayed by the Authorization Server, depending upon the request parameter values used and the authentication methods used. The Authorization Server MUST attempt to log in the End-User in the following cases: The End-User is not already logged in. The Authorization Request contains the prompt parameter with the value login. In this case, the Authorization Server MUST reauthenticate the End-User even if the End-User is already authenticated. The Authorization Server MUST NOT interact with the End-User in the following case: The Authorization Request contains the prompt parameter with the value none. In this case, the Authorization Server MUST return an error if the End-User is not already logged in or could not be silently logged in. The Authorization Server MUST employ appropriate measures against Cross-Site Request Forgery and Clickjacking as, described in Sections 10.12 and 10.13 of OAuth 2.0.

Once the End-User is authenticated, the Authorization Server MUST obtain an authorization decision. This MAY be 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 conditions for processing or other means (for example, via previous administrative consent). The Authorization Server MUST attempt to request authorization from the End-User in the following cases: The End-User has not pre-authorized the Client for the Authorization Request. The Authorization Request contains the prompt parameter with the value consent. The Authorization Server SHOULD request End-User authorization even if the End-User has previously authorized the Client. The Authorization Server MUST NOT request End-User authorization in the following cases: The Authorization Request contains the prompt parameter with the value none. The Authorization Server MUST return an error if the End-User has not pre-authorized the Client. As in the previous section, the Authorization Server MUST employ countermeasures against Cross-Site Request Forgery and Clickjacking when interacting with the End-User.

Once the authorization is determined, the Authorization Server returns a successful or error response.

If the End-User grants the access request, the Authorization Server issues an Authorization Response as described in Section 2.1.2 of OpenID Connect Messages 1.0 to the Client by adding the response parameters to redirect_uri specified in the Authorization Request using the "application/x-www-form-urlencoded" format. Note that if the response_type parameter in the Authorization Request includes the string value token or id_token, all response parameters are added to the fragment component of the redirection URI, as specified in OAuth 2.0 Multiple Response Type Encoding Practices. Otherwise, the response parameters are added to the query component of the redirection URI. The Client MUST validate the response as follows: Case 1: response_type=code Validate the response according to RFC 6749, especially Sections 4.1.2 and 10.12. Case 2: response_type=id_token token Verify that the response conforms to Section 5 of . Follow the validation rules in RFC 6749, especially those in Sections 4.2.2 and 10.12. Follow the validation rules in Sections 4.2 and 4.4 of . Case 3: response_type=code id_token Verify that the response conforms to Section 5 of . Follow the validation rules in RFC 6749, especially those in Sections 4.2.2 and 10.12. Follow the validation rules in Sections 4.2 and 4.5 of . Case 4: response_type=code token Verify that the response conforms to Section 5 of . Follow the validation rules in RFC 6749, especially those in Sections 4.2.2 and 10.12. Case 5: response_type=code id_token token Verify that the response conforms to Section 5 of . Follow the validation rules in RFC 6749, especially those in Sections 4.2.2 and 10.12. Follow the validation rules in Sections 4.2, 4.4, and 4.5 of . Case 6: response_type=id_token Verify that the response conforms to Section 5 of . Follow the validation rules in RFC 6749, especially those in Sections 4.2.2 and 10.12. Follow the validation rules in Section 4.2 of . The following are non-normative examples of requests with differing response_type values and their responses (with line wraps within values for display purposes only):

Case 1: response_type=code

Case 2: response_type=id_token token

Verifying and decoding the ID Token will yield the following Claims:

Case 3: response_type=code id_token

Verifying and decoding the ID Token will yield the following Claims:

Case 4: response_type=code token

Case 5: response_type=code id_token token

Verifying and decoding the ID Token will yield the following Claims:

This following example makes a request using a request parameter value requesting that specific Claims be returned in the ID Token. The sample Request Object used is described in .

Case 6: response_type=id_token

Verifying and decoding the ID Token will yield the following Claims:

The following is the RSA public key in JWK format that can be used to validate the ID Token signatures in the above examples (with line wraps within values for display purposes only):

If the End-User denies the authorization or the user authentication fails, the Authorization Server MUST return the Authorization Error Response as defined in Section 2.1.3 of OpenID Connect Messages 1.0. The Authorization Server returns the Client to the redirection URI specified in the Authorization Request with the appropriate error parameters. No other parameters SHOULD be returned. The error response parameters are the following: REQUIRED. Error code. OPTIONAL. Human-readable ASCII encoded text description of the error. OPTIONAL. URI of a web page that includes additional information about the error. OAuth 2.0 state value. REQUIRED if the Authorization Request included the state parameter. Set to the value received from the Client. If the response_type parameter in the Authorization Request includes the string value token or id_token, all error response parameters are be added to the fragment component of the redirection URI, as specified in OAuth 2.0 Multiple Response Type Encoding Practices. Otherwise, the response parameters are added to the query component of the redirection URI.

The following is a non-normative example (with line wraps within values for the display purposes only):

The Token Endpoint handles requests for retrieving and refreshing Access Tokens as well as ID Token and other variables. Clients MUST use the HTTP POST method to make requests to the Token Endpoint. Request parameters are added using Form Serialization, per . Clients MAY provide authentication parameters in the request to the Token Endpoint as described in Section 2.2.1 of OpenID Connect Messages 1.0. The Token Endpoint MUST support the use of the HTTP POST method defined in RFC 2616 at the Token Endpoint. Communication with the Token Endpoint MUST utilize TLS. See for more information on using TLS. All Token Endpoint responses that contain tokens, secrets, or other sensitive information MUST include the following HTTP response header fields and values: Header Name Header Value Cache-Control no-store Pragma no-cache

To retrieve an Access Token when using the Authorization Code Flow, a Client MUST have an Authorization Code obtained as described in .

To obtain an Access Token, Refresh Token or ID Token, the Client MUST authenticate to the Token Endpoint using the authentication method registered for its client_id, as documented in Section 2.2.1 of OpenID Connect Messages 1.0. The Client sends the parameters via HTTPS POST to the Token Endpoint using Form Serialization, per , as described in Section 4.1.3 of OAuth 2.0.

The following is a non-normative example of an Access Token Request:

The Authorization Server MUST: Authenticate any Clients that were issued Client Credentials (or for which other Client Authentication methods can be used), Ensure the Authorization Code was issued to the authenticated Client, Verify that the Authorization Code is valid, and Ensure that the Scheme, Host, Path, and Query Parameter segments in the redirect_uri parameter are identical to the redirect_uri parameter value that was included in the initial Authorization Request. If the redirect_uri parameter value not be present when there is only one registered redirect_uri value, the Authorization Server MAY return an error (since the Client should have included the parameter) or MAY proceed without an error (since OAuth 2.0 permits the parameter to be omitted in this case).

Upon receipt of the Token Request, the Authorization Server MUST return either a successful response or an error response that corresponds to the received Authorization Code. A successful response returns the application/json media type and the response body is the Access Token Response documented in Section 2.2.3 of OpenID Connect Messages 1.0.

Following is a non-normative example of a successful response:

If the Token Request is invalid or unauthorized, the Authorization Server constructs the response by returning the Token Error Response defined in OpenID Connect Messages 1.0 in the entity body of the HTTP response using the application/json media type with HTTP response code 400.

Following is a non-normative example:

To refresh an Access Token, the Client MUST authenticate to the Token Endpoint using the authentication method registered for its client_id, as documented in Section 2.2.1 of OpenID Connect Messages 1.0. The Client sends the parameters via HTTPS POST to the Token Endpoint using Form Serialization, per , as described in Section 6 of OAuth 2.0: The Authorization Server MUST validate the Refresh Token.

Upon receipt of the Refresh Token Request, the Authorization Server MUST return either a successful response or an error response that corresponds to the received Refresh Token. Upon successful validation of the Refresh Token, a successful response returns the application/json media type and the response body is the Access Token Response of Section 2.2.3 of OpenID Connect Messages 1.0 except that it MUST NOT return an id_token.

Following is a non-normative example of a Refresh Token Request and response:

If the Refresh Token Request is invalid or unauthorized, the Authorization Server returns the Token Error Response as defined in Section 5.2 of OAuth 2.0.

The UserInfo Endpoint is an OAuth 2.0 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 in Section 2.3.1 of OpenID Connect Messages 1.0. Communication with the UserInfo Endpoint MUST utilize TLS. See 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 at the UserInfo Endpoint. The UserInfo Endpoint MUST accept Access Tokens as OAuth 2.0 Bearer Token Usage. The UserInfo Endpoint SHOULD support the use of Cross Origin Resource Sharing (CORS) and or other methods as appropriate to enable Java Script Clients to access the endpoint.

Client SHOULD send the UserInfo Request defined in Section 2.3.1 of OpenID Connect Messages 1.0 either in an HTTPS GET or HTTPS POST request. The Access Token obtained from an OpenID Connect Authorization Request MUST be sent as a Bearer Token. Section 2 of the OAuth 2.0 Bearer Token Usage specification documents the permissible methods of sending the Access Token. 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:

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. Upon receipt of the UserInfo request, the UserInfo Endpoint MUST return the JSON Serialization of the UserInfo response as in Section 2.3.2 of OpenID Connect Messages 1.0 in the HTTP response body unless a different format was specified during Registration . 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. Upon receipt of the UserInfo Response, the Client MUST verify the response in accordance with Section 5.3 (UserInfo Response Validation) of OpenID Connect Messages 1.0.

Following is a non-normative example of such 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 specification utilizing an error code as specified in Section 2.3.3 of OpenID Connect Messages 1.0.

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

OpenID Connect supports Self-Issued OpenID Providers - personal OPs that issue self-signed ID Tokens. Self-Issued OPs use the special Issuer Identifier https://self-issued.me. The messages used to communicate with Self-Issued OPs are mostly the same as those used to communicate with other OPs. Specifications for the few additional parameters used and for the values of some parameters in the Self-Issued case are described in Section 7 of the OpenID Connect Messages 1.0 specification.

In some cases, the login flow can start at the Authorization Server or another party by contacting the Client via a stored link. The target resource at the Client can be a deep link, rather than a default landing page. The Client MAY optionally register an initiate_login_uri that can be used by the Authorization Server or another party to initiate a login for an End-User at the Client. The Authorization Server or a third party sends a Login Initiation Request to the Client Initiation URI with the following parameters: OPTIONAL. Hint to the Authorization Server about the login identifier the End-User might use to log in. If the client receives a value for this string-valued parameter, it MUST include it in the subsequent authorization request as the login_hint parameter value. REQUIRED. Issuer Identifier for the Issuer that the Client is to send the authentication request to. Its value MUST be a URL using the https scheme. OPTIONAL. URI that the Client is requested to redirect to after authentication. Clients MUST verify the value of the target_link_uri to prevent being used as an open redirector to external sites. Other parameters MAY be sent, if defined by extensions. Any parameters used that are not understood MUST be ignored by the Client. Clients SHOULD employ frame busting and other techniques to prevent End-Users from being logged in by third party sites without their knowledge.

Messages are serialized using one of the following methods: Query String Serialization Form Serialization JSON Serialization Not all methods can be used for all messages.

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 of a URL using the application/x-www-form-urlencoded format as defined by . Query String Serialization is typically used in HTTP GET requests. The same serialization method is also used when adding parameters to the fragment component of a URL.

Following is a non-normative example of this serialization (with line wraps within values for display purposes only):

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 . Form Serialization is typically used in HTTP POST requests.

Following is a non-normative example of this serialization (with line wraps within values for display purposes only):

The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. Each parameter MAY have a JSON structure as its value.

Following is a non-normative example of this serialization:

This specification defines features used by both Relying Parties and OpenID Providers. Features that are mandatory to implement for Relying Parties are already described in the OpenID Connect Basic Client Profile 1.0 and OpenID Connect Implicit Client Profile 1.0 specifications, and so are not discussed again here. All OpenID Providers MUST implement the features that are already listed elsewhere in this specification as being "REQUIRED" or are described with a "MUST". Since this specification is a protocol binding for the OpenID Connect Messages 1.0 specification, all the implementation considerations described in that specification also apply here.

Some OpenID Connect installations can use a pre-configured set of OpenID Providers and/or Relying Parties. In those cases, it might 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 and OpenID Connect Dynamic Client Registration 1.0 specifications.

This specification references the security considerations defined in OpenID Connect Messages 1.0, Section 10 of OAuth 2.0, and Section 5 of OAuth 2.0 Bearer Token Usage. Furthermore, the OAuth 2.0 Threat Model and Security Considerations specification provides an extensive list of threats and controls that apply to this specification as well, given that it is an OAuth 2.0 binding of OpenID Connect Messages 1.0. Implementers are highly advised to read these references in detail and apply the countermeasures described therein. In addition, the following list of attack vectors and remedies are also considered.

In the implicit grant flow, the Access Token is returned in the fragment component of the Client's redirect_uri through HTTPS, thus it is protected between the OP and the User-Agent, and User-Agent and the RP. The only the place it can be captured is the User-Agent where the TLS session is terminated, and is possible if the User-Agent is infested by malware.

Implementations MUST support TLS. Which version(s) ought to be implemented will vary over time, and depend on the widespread deployment and known security vulnerabilities at the time of implementation. At the time of this writing, TLS version 1.2 is the most recent version, but has very limited actual deployment, and might not be readily available in implementation toolkits. TLS version 1.0 is the most widely deployed version, and will give the broadest interoperability. To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection. Whenever TLS is used, a TLS server certificate check MUST be performed, per RFC 6125.

This document makes no requests of IANA.

Microsoft Ping Identity Nomura Research Institute, Ltd. Microsoft Ping Identity Nomura Research Institute, Ltd. Microsoft RTFM, Inc. Cisco Systems, Inc. Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Illumila Nomura Research Institute, Ltd. Ping Identity Microsoft Nomura Research Institute, Ltd. Ping Identity Microsoft Illumila Google Google Facebook Opera Software ASA Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Illumila

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.

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.

[[ To be removed from the final specification ]] -21 Fixed #839 - Described requirement to employ countermeasures against Cross-Site Request Forgery and Clickjacking. Fixed #841 - Described verification requirements for Authorization Server responses. Fixed #846 - Provided a more complete introduction to Standard. Removed the Privacy Considerations section in Standard since it was a duplicate of the one in Messages. Stated that redirect_uri matches must be exact, with matching performed as described in Section 6.2.1 of RFC 3986 (Simple String Comparison). Fixed #850 - Clarified login_hint semantics for third party initiated logins. Fixed #854 - Clarified that the acr_values values are in order of preference. Fixed #859 - Added IMPORTANT NOTE TO READERS about the terminology definitions being a normative part of the specification. -20 Changed from using the term "byte" to either "octet" or "character". Fixed #836 - Clarified language describing signing and encrypting request parameter values. Stated that the JWS Compact Serialization and the JWE Compact Serialization are always used for JWS and JWE data structures. -19 Fixed #821 - Moved definition of JSON Serialization to where it's used. -18 Fixed #801 - Removed schema and id parameters to UserInfo Endpoint. Also fixed related issue #791 - Removed invalid_schema error. -17 Fixed #715 - Delete "profile" from request object example. Fixed #722 - Text on "id_token_hint" needs to be clarified. Fixed #718 - Text on re-encrypting should be clearer. Fixed #714 - Clarified text specifying response_type behaviors, including prohibiting the use of the "token" response_type, since it returns no ID Token. Added Security Considerations section about TLS version requirements and usage. Removed language about supporting other transport-layer mechanisms with equivalent security to TLS. State that when any validations fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used. Fixed #744 - Promoted max_age to being a top-level parameter. Fixed #748 - Promoted claims to being a top-level parameter separate from the OpenID Request Object. Fixed #597 - Changed representation of omitted year in birthdate from 9999 to 0000. Fixed #773 - Added request_uris registration parameter to pre-register request_uri values. Also clarified that Request File contents may be cached. Deleted top-level policy_url parameter from the Self-Issued case, since it is already a registration parameter member. Fixed #778 - Added registration parameter to Self-Issued request example. Fixed #782 - Changed uses of "_url" in identifiers to "_uri". Fixed #719 - Moved message definitions for Self-Issued OPs to the Messages spec. Fixed #788 - Renamed "OpenID Request Object" to "Request Object". Use legal acr values in examples. -16 Added Implementation Considerations section. Fixed #698 - Inconsistent use of articles. Fixed #655 - Specify UTF-8 as encoding scheme whenever necessary. To remove ambiguity in the self-issued sub computation, changed the text "the concatenation of the key values" to "the concatenation of the bytes of the UTF-8 representations of the base64url encoded key values". Renamed the user_jwk Claim to sub_jwk, paralleling the change from user_id to sub. Tracked JWK parameter name changes alg -> kty, mod -> n, exp -> e. -15 Fixed #687 - Inconsistency between user_id and prn claims. The fix changed these names: user_id -> sub, user_id_types_supported -> subject_types_supported, user_id_type -> subject_type, and prn -> sub. Fixed #689 - Track JWT change that allows JWTs to have multiple audiences. Fixed #539 - Add scope for offline access. Re #601 add Initiating login at a client from a third party Made the OpenID Foundation Artifact Binding Working Group the change controller for the values registered with IANA. Moved OAuth error registrations from Standard to Messages since the errors are defined in Messages and not in Standard. Re #657 Changed id_token to id_token_hint in Sec 2.3.1 -14 Fixed #614 - Discovery - 3.2 Distinguishing between signature and integrity parameters for HMAC algorithms. This fix tracks the parameter changes made to the JWE spec in draft-ietf-jose-json-web-encryption-06. It deletes the parameters {userinfo,id_token}_encrypted_response_int. It replaces the parameters {userinfo,id_token,request_object,token_endpoint}_algs_supported with {userinfo,id_token,request_object,token_endpoint}_signing_alg_values_supported and {userinfo,id_token,request_object,token_endpoint}_encryption_{alg,enc}_values_supported. Fixed #666 - JWS signature validation vs. verification. Fixed #681 - Change remaining uses of "birthday" to "birthdate". Fixed #669 - Inconsistent treatment of redirect_uri parameter. Referenced OAuth 2.0 RFCs -- RFC 6749 and RFC 6750. -13 Defined means of using a self-issued OP -12 Updated matching of redirect URI to include query parameters to match Google's implementation -11 Removed claims_in_id_token scope value, per decision on June 15, 2012 special working group call -10 Changed verified to email_verified, per issue #564 Added scope value claims_in_id_token as a switch to indicate that the UserInfo claims should be returned in the id_token, per issue #561 Changed optional claim request parameter to essential, per issue #577 Removed Check ID Endpoint, per issue #570 Specified that parameters present in both the OpenID Request Object and the OAuth 2.0 Authorization Request MUST exactly match, per issue #575 Changed OpenID Request Object from being specified as a JWT to being specified as a JWS signed base64url encoded JSON object, per issue #592 Made use of the nonce REQUIRED when using the implicit flow and OPTIONAL when using the code flow, per issue #569 Changed client.example.com to client.example.org, per issue #251 Removed example text for generating a nonce via a signed session cookie, per issue #562 Use standards track version of JSON Web Token spec (draft-ietf-oauth-json-web-token) -09 Added error interaction_required and removed user_mismatched, per issue #523 Changed invalid_request_request_uri to invalid_request_uri and invalid_request_redirect_uri to invalid_redirect_uri, per issue #553 Added optional id_token to authorization request parameters, per issue #535 Removed use of non-existent scope parameters registry, per issue #558 Updated Notices Updated References -08 Updated version number and date Fix #543 Section 2.3.1.3 Request file requiring all request params to be included is false Fix Section 5.1 to reference Messages 2.4.1 rather than 3.3 Added reference to CORS for JS clients to userinfo and check_id endpoints -07 Removed definition and usage for assertion and claim object Removed Request File Registration Service Consistent use of End-User email scope allows access to the 'verified' claim Removed language pertaining to custom userinfo schemas Updated error section for refreshing access token Remove 'audience' parameter from Authorization Request Moved display=none to prompt=none Moved IANA considerations from Messages Check ID Endpoint returns only JSON Removed PPID scope value Reference Messages for validation of request object encryption and signature Redefined 'nonce' in Authorization Request. Changed to REQUIRED parameter. Changed usage of "approval" to "consent" Use RFC 6125 to verify TLS endpoints Added Privacy considerations Changed 'request_uri' to require HTTPS unless the referenced content is signed and only needs to be reachable by AS Added hash and entropy considerations to 'request_uri' Added requirement to compare user_id from userinfo endpoint to id_token Check ID Endpoint SHOULD use POST Changed UserInfo Error Response to augment and return OAuth 2.0 Bearer Token Error Response Added section about string comparison rules needed Added Response Encoding according to Multiple Response Types spec Allows only 'id_token' for 'response_type' parameter in Authorization Request Clarified redirect_uris matching Added explanation of select_account Changed Security Considerations to refer to corresponding section in Messages Check ID Endpoint uses ID Token as Access Token according to Bearer Token spec Update John Bradley email and affiliation for Implementer's Draft Removed invalid_authorization_code, invalid_id_token error codes -06 Reworked return type wording in section 4.4.1 per ticket #174. Added reference to registered return types. Bumped Version number and date. Make clear the server passes the value of nonce through untouched. Ticket #97. Prevent caching of request_uri. Ticket #148. Add nonce to request examples. Ticket #147. Fixed 4.3.1.3 per ticket #150. Fixed 4.3.2 to remove display scopes per ticket #172. Make scope optional for refresh in 5.2. Reference messages 3.2.2 for field definitions in section 5.2.1 per ticket #159. Removed scopes from display value in 4.3.1 per ticket #172. Make "code" and "id_token token" response types mandatory for Authorization Servers to support. -05 Changed check_session to check_id. schema=openid now required when requesting UserInfo. Removed display values popup, touch, and mobile, since not well defined. Resolve issue #135, clarifying that the access_token MAY be sent in the message body. -04 Changes associated with renaming "Lite" to "Basic Client" and replacing "Core" and "Framework" with "Messages" and "Standard". Numerous cleanups, including updating references. -03 Added secret_type to the Token Endpoint. Minor edits to the samples. -02 Incorporates feedback from Nat Sakimura. -01 First Draft that incorporates the merge of the Core and Framework specs.