Network Working Group J. Hanson Internet-Draft Auth0 Inc. Expires: October 22, 2017 April 20, 2017 OpenID Connect Cross-Origin Authentication draft-hanson-openid-connect-cross-origin-authentication-latest Abstract OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It enables 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. This specification describes a cross-origin authentication flow which allows Clients to directly control the authentication ceremony, initiate a session at the Authorization Server, and request authorization from the Authorization Server after the authentication ceremony is complete. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 22, 2017. Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents Hanson Expires October 22, 2017 [Page 1] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 1. Introduction OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It enables 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. This specification describes a cross-origin authentication flow which allows Clients to directly control the authentication ceremony, initiate a session at the Authorization Server, and request authorization from the Authorization Server after the authentication ceremony is complete. This flow is optimized for clients implemented in a browser using a scripting language such as JavaScript. It makes use of XMLHttpRequest to allow Clients to authenticate users without HTTP redirection. This specification does not change the semantics of the OpenID Connect authentication flows. It introduces a new endpoint to which the authentication request is sent and processed. 1.1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 1.2. Terminology This specification also defines the following terms: Login Ticket: A single-use ticket representing a valid authentication which can be exchanged for tokens, including access tokens and ID tokens. Hanson Expires October 22, 2017 [Page 2] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 2. Overview OpenID Connect, in building upon OAuth 2.0, allows a service to delegate authentication responsibilities to a centralized authorization server. In many deployment scenarios, enabling single sign-on is a motivating factor for implementing OpenID Connect, as it allows a user to access multiple services without re-authentication. In some instances a service may have multiple domains that act as primary points of interaction with the user. For example, an online retailer may operate category-focused sites at www.phoneshop.example and www.camerashop.example. The pages on each domain present the user with a traditional login dialog, prompting for a username and password. Because the retailer maintains a single user directory, a single set of user credentials works on both domains. In order to improve the shopping experience, the retailer has decided to allow single-sign on by operating an OpenID Provider at login.shop.example. As part of that deployment, the retailer should consider replacing the login dialog on each site with a single "sign- in" button that redirects to login.shop.example and presents a unified login experience. In some circumstances, however, it may be desireable to continue to accept credentials directly on each separate domain. The cross-origin authentication endpoint offers a solution that can satisfy this scenario. 3. Cross-Origin Authentication Endpoint The cross-origin authentication endpoint is used to authenticate an End-User. Authentication is requested by sending an HTTP POST request directly from the Client, using XMLHttpRequest to the OP's cross-origin authentication endpoint. Use of the cross-origin authentication endpoint requires direct Client access to the End-User's credentials. The credentials should only used when there is a high degree of trust between the End-User and the Client. Communication with the cross-origin authentication endpoint MUST utilize TLS. 3.1. Authentication Request The client makes a request to the cross-origin authentication endpoint by sending the following parameters using the "application/ Hanson Expires October 22, 2017 [Page 3] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 json" format with a character encoding of UTF-8 in the HTTP request entity-body: credential_type REQUIRED. The type of credential used for authentication. Value is case insensitive. client_id REQUIRED. The client identifier. The request MUST include additional parameters that are interpreted according to a credential type definition. The following is a non-normative JavaScript code sample that would cause the User-Agent to make an Authentication Request to the cross- origin authentication endpoint: var req = new XMLHttpRequest(); req.addEventListener('load', function() { var data = JSON.parse(this.responseText); // handle response }); req.open('POST', 'https://server.example.com/co/authenticate'); req.withCredentials = true; // OPTIONAL req.setRequestHeader('Content-Type', 'application/json'); var data = { client_id: 's6BhdRkqt3', credential_type: 'password', username: document.getElementById('username').value, password: document.getElementById('password').value } data = JSON.stringify(data); req.send(data); The following is a non-normative example request that would be sent by the Client to the Authorization Server: POST /co/authenticate HTTP/1.1 Host: server.example.com Origin: https://www.example.net Content-Type: application/json { "client_id": "s6BhdRkqt3", "credential_type": "password", "username": "jane", "password": "s3cr1t" } The Client SHOULD: Hanson Expires October 22, 2017 [Page 4] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 o set XMLHttpRequest.withCredentials to true, which will include cookies in the HTTP request and allow cookies to be set by the HTTP response. Note that even with this set, browser policy may prevent this behavior. o include cross-origin confirmation parameters in the HTTP request, such as those defined by Proof Key for Cross-Origin Requests by OAuth Public Clients. Such confirmation allows a session to be initiated subsequent to the authentication request, in the scenario in which cookies are unable to be set in the HTTP response from the OpenID Provider. The OpenID Provider MUST: o ensure that the Origin header is present and that its value corresponds to the Client's origin previously established with the authorization server during the client registration process, o verify that the client is allowed to use the cross-origin authentication flow. o verify the authentication credentials. 3.2. Session Establishment If the authentication request is valid and authorized, the OpenID Provider SHOULD establish a session for the authenticated End-User. The following scenarios deserve special attention due to the security implications of establishing sessions in response to cross-origin requests. 3.2.1. No Existing Session If no existing login session exists at the OpenID Provider, a new login session can be established without adverse consequences. 3.2.2. Existing Session for Same End-User If an existing login session exists at the OpenID Provider for the authenticated End-User, the existing session should be preserved. An additional login session SHOULD NOT be established. 3.2.3. Existing Session for Different End-User If an existing login session exists at the OpenID Provider for an End-User other than the authenticated End-User, an additional login Hanson Expires October 22, 2017 [Page 5] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 session SHOULD be established for the authenticated End-User. The existing session for the other End-User SHOULD be preserved. In particular, the other End-User's session SHOULD NOT be terminated in order to avoid adverse consequences with other Clients that may have already federated the other End-User's session. 3.3. Authentication Response If the authentication request is valid and authorized, the OpenID Provider constructs the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code: login_ticket REQUIRED. The Login Ticket representing the valid authentication. The parameters are included in the entity body of the HTTP response using the "application/json" media type as defined by [RFC4627]. The Login Ticket MUST be bound to the session established for the authenticated End-User. If the Client included cross-origin confirmation parameters in the authentication request, the OpenID Provider MUST bind the Login Ticket in such a way that the parameters can be verified prior to establishing a login session if subsequent session initiation is necessary. When making use of cross-origin authentication, communication occurs directly between the Client and OP, without using HTTP redirection. Furthermore, clients implemented in a browser are public clients and unable to be authenticated. These two limitations imply that it is impossible to verify the identity of the Client making the request. Due to the lack of Client identity verification, the Login Ticket MUST be confidentiality protected from the Client. The Login Ticket SHOULD be exchanged by the Client at the Authorization Endpoint for an ID Token and/or Access Token and MAY be exchanged in a mode that does not require further End-User interaction. 3.4. Authentication Error Response If the authentication request failed End-User authentication or is invalid, the authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following parameters with the response: error REQUIRED. A single ASCII error code from the following: Hanson Expires October 22, 2017 [Page 6] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than credential type), repeats a parameter, or is otherwise malformed. unauthorized_client The client is not authorized to use cross-origin authentication or the origin of the request is invalid. access_denied The credentials are invalid or the OpenID Provider denied the request. unsupported_credential_type The OpenID Provider does not support issuing an ID Token using this method. server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request. error_description OPTIONAL. A human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. error_uri OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. 4. Authentication Credentials To authenticate an End-User, the client first obtains the End-User's credentials. This specification defines a single credential type: password. It also provides an extension mechanism for defining additional credential types. 4.1. End-User Password Credentials The end-user password credentials type is suitable in cases where the End-User has a trust relationship with the client, such as a website known to be operated by a trusted organization. The authorization server should take special care when enabling this credential type and only allow it when other flows are not viable. Hanson Expires October 22, 2017 [Page 7] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 4.1.1. Authentication Request The client makes a request to the token endpoint by adding the following parameters using the "application/json" format with a character encoding of UTF-8 in the HTTP request entity-body: credential_type REQUIRED. Value MUST be set to "password". username REQUIRED. The End-User username. password REQUIRED. The End-User password.. client_id REQUIRED. The client identifier.. The OpenID Provider MUST: o validate the End-User password credentials using its existing password validation algorithm. 5. Obtaining Tokens Having authenticated an End-User's credentials, a Client needs to obtain an ID Token that contains claims about the Authentication event. In order to receive tokens, the Client makes a standard Authentication Request to the Authorization Endpoint. Use of the Authorization Endpoint allows the Client's identity to be verified prior to issuing tokens, preventing the disclosure of protected information to unauthorized clients. It also allows further consent to be obtained, in cases where authentication alone is insufficient. 5.1. Authentication Request The client makes a request to the Authorization Endpoint in the manner specified by OpenID Connect. The login_ticket returned from the Cross-Origin Authentication Endpoint is included in the "login_ticket" parameter. Hanson Expires October 22, 2017 [Page 8] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 The following is a non-normative example request that would be sent by the Client to the Authorization Server: GET /authorize? response_type=id_token%20token &login_ticket=2YotnFZFEjr1zCsicMWpAA &scope=openid%20profile%20email &client_id=s6BhdRkqt3 &state=af0ifjsldkj &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1 Host: server.example.com 5.2. Authentication Request Validation The Authorization Server MUST validate the request received as follows: 1. The Authorization Server MUST validate all the OAuth 2.0 parameters according to the OAuth 2.0 specification. 2. The Authorization Server MUST validate all the OpenID Connect parameters according to the OpenID Connect specification. 3. If the End-User identified by the Login Ticket has a login session, verify that the Login Ticket is bound to the session. If so, continue normal processing. If not, respond with an access_denied error. 4. If the End-User identified by the Login Ticket does not have a login session: A. If the Login Ticket does not have any cross-origin confirmation parameters, respond with an access_denied error. B. If the Login Ticket does have cross-origin confirmation parameters, start a session initiation flow. C. Verify the cross-origin confirmation parameters. The exact confirmation mechanism is beyond the scope of this specification. Use of Proof Key for Cross-Origin Requests by OAuth Public Clients is RECOMMENDED. D. If the cross-origin confirmation parameters are verified, establish a login session for the End-User identified by the Login Ticket and resume normal processing. Otherwise, respond with an access_denied error. Hanson Expires October 22, 2017 [Page 9] Internet-Draft OpenID Connect Cross-Origin Authentication April 2017 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, DOI 10.17487/RFC4627, July 2006, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [I-D.ietf-oauth-discovery] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", draft-ietf-oauth- discovery-05 (work in progress), January 2017. Author's Address Jared Hanson Auth0 Inc. Email: jaredhanson@gmail.com URI: http://www.jaredhanson.net/ Hanson Expires October 22, 2017 [Page 10]