| OAuth Working Group | J. Ideskog |
| Internet-Draft | T. Spencer |
| Intended status: Standards Track | Curity AB |
| Expires: September 19, 2018 | March 18, 2018 |
OAuth 2.0 Assisted Token
draft-ideskog-assisted-token-00
The OAuth 2.0 authorization flow for Single Page Applications (SPAs), often referred to as the assisted token flow, enables OAuth clients to request user authorization written in scripting languages, like JavaScript, with a simplified integration compared to the implicit grant type flow. Communication does not rely on redirection of the user agent, but instead leverages HTML's iframe element, child windows, and the postMessage interface. This communication is done using an additional endpoint, the assisted token endpoint, which this document defines.
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 https://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 September 19, 2018.
Copyright (c) 2018 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 (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents 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.
This OAuth 2.0 protocol flow for Single-page Applications (SPA), often referred to as the assisted token flow, provides clients written in scripting languages, like JavaScript, with a simplified integration (compared to the implicit grant type flow) and ensures that end users are not redirected away from the current page in order to obtain authorization from the resource owner. The communication between the client and the authorization server takes place within an HTML iframe element or child window that is only displayed when interactive user interaction is required; this is the case when authentication and/or authorization are necessary. To communicate the result from this iframe or child window to the client application, HTML's postMessage interface is used instead of the redirection endpoint defined in Section 3.1.2 of The OAuth 2.0 Authorization Framework. This difference is important for many SPAs which take time to reload and may not be able to recreate the same state prior to the user being redirected to the authorization server.
Another goal of the assisted token flow is to simplify integration of the client with the authorization server. Though [RFC6749] resulted in a much simpler integration for client applications compared to its predecessor, [RFC5849], developers still struggle with the many inputs required to perform the various OAuth flows. For this reason, the assisted token flow introduces a new endpoint called the assisted token endpoint rather than extending and reusing the token endpoint defined in Section 3.2 of [RFC6749]. As a result, client developers do not need to specify a response_type parameter in the authorization request. This coupled with the use of HTML's postMessage interface for communication between the client and the authorization server means that the redirect_uri and state parameters are also unnecessary. Consequently, client developers only need to provide a client_id, create a dynamic iframe or open a child window, and handle the postMessage that is fired by the authorization server in order to implement OAuth.
This interaction is shown in Figure 1.
+----------------------------+ +---------------+
| Client | | Authorization |
| +--------------------------+ | Server |
| | +-----------+ | |
| |--(A)-------->| |--(B)-- Client ------>| |
| | | | Identifier | |
| | | Hidden | | |
| | | iframe |<-(C)-- HTML with ----| |
| |<-(D)- Token -| | postMessage | |
| | or | | including | |
| | error +-----------+ access token | |
| +--------------------------+ or error | |
| | | |
+----------------------------+ +---------------+
Figure 1: Assisted Token Flow
The assisted token flow illustrated in Figure 1 includes the following steps:
If the resource owner has not authenticated or has not authorized the client, then interaction between the resource owner and the authorization server is required to obtain these. In such a case, the HTML in step (C) of Figure 1 will include an error indicating that user involvement is required. This will be handled by the client in step (D) and login and/or consent will commence. This process is illustrated in Figure 2.
+----------------------------+ +---------------+
| Client | | Authorization |
| +--------------------------+ | Server |
| | +-----------+ Client | |
| |--(E)-------->| |--(F)-- Identifier -->| |
| | | Visible | | |
| | | iframe |--(G)-- User -------->| |
| | | or child | authenticates | |
| |<-(I)- Token -| window | | |
| | | |<-(H)-- HTML with ----| |
| | +-----------+ postMessage | |
| +--------------------------+ including | |
| | access token | |
+----------------------------+ +---------------+
Figure 2: Assisted Token Login and/or Consent Flow
The flow shown in Figure 2 includes the following steps:
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 Key words for use in RFCs to Indicate Requirement Levels [RFC2119].
All other terms used in this document are as defined in [RFC6749]. Unless otherwise noted, all the protocol parameter names and values are case sensitive.
The means through which the client obtains the location of the assisted token endpoint is either by using the authorization server's metadata as set forth in Section 6, the service documentation, or some other method that is beyond the scope of this specification.
The endpoint URI MAY include an "application/x-www-form-urlencoded" formatted (per Appendix B of [RFC6749]) query component (Section 3.4 of [RFC3986]), which MUST be retained when adding additional query parameters. The endpoint URI MUST NOT include a fragment component.
Since requests to the assisted token endpoint result in the transmission of clear-text credentials (in the HTTP request and response), the authorization server MUST require the use of TLS as described in Section 1.6 of [RFC6749] when sending requests to the assisted token endpoint.
The client MUST use the HTTP "GET" method when making access token requests to this endpoint.
Parameters sent without a value MAY be treated as if they were omitted from the request. The authorization server MUST ignore unrecognized request parameters. Request and response parameters MUST NOT be included more than once.
After completing its interaction with the resource owner, the authorization server will fire an event using the HTML postMessage interface. This message MUST NOT be posted to all origins, denoted by "*". Instead, the authorization server MUST post this message only to the client's allowed origin(s) previously established with the authorization server during the client registration process.
Like the authorization and token endpoints, the assisted token endpoint allows the client to specify the scope of the access request using the "scope" request parameter. In turn, the authorization server uses the "scope" response parameter to inform the client of the scope of the access token issued. Unlike the typical behavior of those endpoints, however, access tokens issued by the authorization server using the assisted token endpoint MUST use the client's pre-configured scope or the authorization server's pre-defined default if none have been configured for the client.
If the client did not include a "scope" request parameter or if the issued access token scope is different from the one requested by the client, the authorization server MUST include the "scope" response parameter to inform the client of the actual scope granted. Even when the scope of the issued access token is the same as the one requested by the client, the authorization server SHOULD include the "scope" response parameter.
The format, constraints, and grammar of the scope parameter value is as defined in Section 3.3 of [RFC6749].
The authorization server SHOULD NOT return an error if a scope has not been pre-configured for the client; only if the authorization server does not have a pre-defined default scope.
The assisted token endpoint MAY support CORS [W3C.WD-cors-20120403].
The assisted token request is an HTTP GET request constructed by the client with the following parameters provided on the query string:
Other values may be provided in this list; the authorization server MUST ignore them without producing an error if it cannot understand them.
The response from the assisted token endpoint is an HTML document that executes a script which invokes the HTML postMessage interface to send a message to either the parent window (in the case shown in Figure 1) or the opener (in the case illustrated in Figure 2). The origin that this event is posted to is that of the client. The contents of this message is a JSON object with the following fields:
As with a successful response, an error is returned to the client using an the HTML postMessage interface. Such an error is returned whenever the resource owner denies the access request or whenever the request fails for reasons other than the origin of the client being disallowed to frame the assisted token endpoint. The error message includes a JSON object with the following fields:
Values for the "error" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
The authorization server MAY allow dynamic clients to request the use of the assisted token flow when registering. Such a client may indicate that it will interact with the authorization server using the assisted token flow by including the string element "urn:ietf:params:oauth:grant-type:assisted_token" in the array associated with the "grant_types" metadata field sent to the client registration endpoint (as defined in Section 3. of [RFC7591]). If the authorization server allows the client to register with this grant type, the "grant_types" included in the response MUST include the value "urn:ietf:params:oauth:grant-type:assisted_token". The inclusion of this value in the "grant_types" field is done despite the fact that the client will not use this grant type at the token endpoint but rather the assisted token endpoint.
The following client metadata field is defined by this specification. It MAY be included in a registration request, as set forth in Section 2. of [RFC7591].
Support for the assisted token flow MUST be declared in the OAuth 2.0 Authorization Server Metadata [I-D.ietf-oauth-discovery] with the following metadata:
This specification registers the following values in the IANA "OAuth URI" registry [IANA.OAuth.Parameters] established by [RFC6755].
This specification registers the following values in the IANA "OAuth 2.0 Authorization Server Metadata" registry [IANA.OAuth.Parameters] established by [I-D.ietf-oauth-discovery].
In addition to all the security considerations discussed in OAuth 2.0, the following security considerations SHOULD be taken into account.
Due to the use of an iframe to host the assisted token endpoint, the authorization server MUST take precautions to ensure that only trusted origins are allowed to frame it. The authorization server MUST prevent any origin from framing the assisted token endpoint except ones that an administrator has explicitly allowed. It may do this in any manner that is available to the application.
One such mechanism that MAY be deployed is Content Security Policy. This protocol SHOULD be used on the assisted token endpoint (and, if applicable, other endpoints used to authenticated the user in a specific deployment) to prevent framing from unauthorized origins. Using CSP allows the authorization server to specify multiple origins in a single response header field and to constrain these using flexible patterns (see [CSP-2] for details). This standard provides a robust mechanism for protecting against click-jacking when combining policies that restrict "child-src" with the sources of scripts that are allowed to execute by using "script-src" policies.
Because some user agents do not support [CSP-2], this technique SHOULD be combined with others. In particular, the authorization server SHOULD return an "X-Frame-Options" response header on the assisted token endpoint (and, if applicable, other endpoints used to authenticate the user in a specific deployment). As defined in [RFC7034], this header will cause user agents that support it (but not CSP) to block framing from any origin that is not specified in this header's value. Because this header's value can only include one origin, the framer should use the "for_origin" parameter (as specified in Section 4.1) to include its own origin.
Some user agents do not support X-Frame-Options nor [CSP-2]. Therefore, the authorization server SHOULD include a frame-busting script like that shown in Figure 7 of [FRAME-BUSTING]. Such a script would use JavaScript to break out of any unauthorized origin that is framing the assisted token endpoint. The authorization server MAY simply break out of all frames in case X-Frame-Options and [CSP-2] are unsupported by the user agent, though this would render the assisted token flow non-functional. The choice of whether or not this drastic countermeasure should be employed depends on the user agents being targetted in a certain deployment.
Because the client applications that use the assisted token flow are written in scripting languages like JavaScript and are hosted in Web pages, users may keep such applications open in their user agents for a prolonged period of time. During such period, the token issued to the client may expire or be revoked. To ensure that such expired tokens left remnant in the user agent are benign, a Handle Token SHOULD always be issued by the assisted token endpoint. This ensures that no identity data is exposed (even when the token is not yet expired) and that a revoked token does not increase risks.
As admitted in Section 8 of [RFC6454], preventing exfiltration of cookies, tokens, and other such credentials in web browsers has historically proven difficult to implement. Instead, the same-origin policy has emerged as the cornerstone of security for such user agents. Using this security model, it is not possible to prevent access to a token issued to a client if that client includes nefarious scripts from untrustworthy sources that have access to the Document Object Model (DOM) where the token is stored. For this reason, the authorization server MUST warn client application developers who interact with the assisted token endpoint not to use untrusted scripts in their applications. This warning SHOULD at least be conveyed through the documentation but MAY also be provided through other mechanisms.
As described in Section 4.1, the authorization server will return an access token to the client using HTML's postMessage interface. The receiver of this message is provided with an event object that contains an origin property. A client application MUST compare this with that of the authorization server before consuming the message. Otherwise, it runs the risk of processing messages posted from untrusted origins. An example of a proper message handler is shown in the following non-normative, JavaScript listing:
<script type="text/javascript">
window.addEventListener("message", function(evt) {
if (evt.origin !== "https://oauth-server.example.com")
return; // Ignore event from untrusted source
...
});
</script>
Figure 3: Comparing the origin of the postMessage event with that of the authorization server
Most client applications that use the assisted token flow will maintain the access token issued by the authorization server in a persisted state; this will commonly be an HTTP cookie or local storage. This is necessary, for instance, to create a pleasing user experience when a user navigates away from the application in their web browser and then returns. To ensure that the token is stored safely, the authorization server MAY provide application developers with guidance in the accompanying documentation on how to safely persist tokens. The authorization server MAY also provide script libraries that perform this action according to best common practices. The authorization server MAY also store the token in an HTTP cookie in its own DNS domain (rather than that of the client) using the assisted token endpoint's path. In some cases, this would elevate any storage requirements from the client application developer. Besides simplifying the programming model for developers, this technique allows the authorization server to check the validity of the token and determine if the token has expired or if the associated grant has been revoked in subsequent requests to the assisted token endpoint; this will be possible because the requests will include the token in the HTTP Cookie request header. In such cases, the authorization server can take the appropriate action, such as authenticating the user anew or request consent, before issuing a new token. If the token is stored by the application, however, this kind of verification cannot be performed by the authorization server without an explicit request to validate a stored token.
When the authorization server and client are provided by separate parties, it is important that the resource owner is able to distinguish the two. The only safe way of doing so is by examination of the user agent's address bar where the validity of the certificate and location can be made. In such situations, whenever user interaction is required, the client SHOULD open the assisted token endpoint in a new browser window rather than a hidden iframe. The authorization serer MAY take any measures deemed appropriate in a deployment to ensure that the client has not framed the user's manual interaction; however, the necessity for interactive user authentication and/or consent SHOULD be possible for the client to determine in a hidden iframe.
In some deployments, the assisted token endpoint may be served from a distinct domain from that of the client. In such cases, the client will be a third-party domain, and the resource owner's user agent may prevent the authorization server from storing any third-party cookies. If the authorization server requires state to be persisted when performing the assisted token flow, it SHOULD provide a privacy-preserving mechanism to store and retrieve its state even when the assisted token endpoint is hosted on a distinct domain from that of the client. The technical details of how to accomplish this are implementation specific, and are beyond the scope of this specification. If the authorization server does not support clients that are hosted from a third-party domain, it MUST indicate this to the client through some mechanism (e.g., its associated documentation).
| [I-D.ietf-oauth-discovery] | Jones, M., Sakimura, N. and J. Bradley, "OAuth 2.0 Authorization Server Metadata", Internet-Draft draft-ietf-oauth-discovery-10, November 2017. |
| [IANA.OAuth.Parameters] | IANA, "OAuth Parameters" |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005. |
| [RFC6749] | Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012. |
| [RFC7591] | Richer, J., Jones, M., Bradley, J., Machulak, M. and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015. |
| [USASCII] | American National Standards Institute, "Coded Character Set -- 7-bit American Standard Code for Information Interchange", ANSI X3.4, 1986. |
| [CSP-2] | West, M., Barth, A. and D. Veditz, "Content Security Policy Level 2", July 2015. |
| [FRAME-BUSTING] | Rydstedt, G., Bursztein, E., Boneh, D. and C. Jackson, "Busting frame busting: a study of clickjacking vulnerabilities at popular sites", July 2010. |
| [RFC5849] | Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, DOI 10.17487/RFC5849, April 2010. |
| [RFC6454] | Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, December 2011. |
| [RFC6755] | Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012. |
| [RFC6819] | Lodderstedt, T., McGloin, M. and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013. |
| [RFC7034] | Ross, D. and T. Gondrom, "HTTP Header Field X-Frame-Options", RFC 7034, DOI 10.17487/RFC7034, October 2013. |
| [W3C.WD-cors-20120403] | Kesteren, A., "Cross-Origin Resource Sharing", World Wide Web Consortium LastCall WD-cors-20120403, April 2012. |
The following individuals contributed ideas, feedback, and wording to this specification:
Mark Dobrinic, Karl McGuinness
[[ to be removed by the RFC editor before publication as an RFC ]]
-00