]> Okta

jared.hanson@okta.com

This specification defines a response mode for OAuth 2.0 that uses a cookie to obtain and transmit an access token. In this mode, the access token is encoded using an HTTP Set-Cookie header and transmitted via the HTTP Cookie header to the client or resource server. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction OAuth was initially created to allow third-party clients to access protected resources hosted by a resource server, with the approval of the resource owner. It has proven useful in first-party scenarios as well, where clients and resource servers are managed by the same organization. The implicit grant defined by OAuth is a flow optimized for clients implemented in a browser using a scripting language such as JavaScript. In this flow, the client is issued the access token directly, where, due to the nature of browsers, it may be exposed to other applications with access to the resource owner's user-agent. Due to this, OAuth does not support issuance of refresh tokens via the implicit grant, as refresh tokens are typically long-lasting credentials that must be kept confidential and not exposed to unauthorized parties. With the increasing adoption of OAuth, new threat models and security best current practices have been identified in and . These new practices recommend the use of authorization code grant by browser-based applications and advise against use of the implicit grant. The rationale for the shift in guidance is sound, as the implicit grant is susceptible to a number of a attack vectors that aren't applicable to the authorization code grant. However, concerns around exposing tokens to unauthorized parties with access to the user-agent remain, and may be exacerbated if refresh tokens are introduced to an environment in which they were previously forbidden. These concerns are unavoidable, especially in scenarios where delegation is granted to third-party clients. However, first-party scenarios have the ability to use cookies, which can be limited in such a way that they aren't exposed to JavaScript. Such limits mitigate various attack vectors, benefiting scenarios in which use of cookies is applicable. This specification defines a response mode for OAuth 2.0 that uses a cookie to transmit an access token. In this mode, the access token is encoded using an HTTP Set-Cookie header and transmitted via the the HTTP Cookie header to the client or resource server.

Conventions and Definitions 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 BCP 14 when, and only when, they appear in all capitals, as shown here.

User-Agent-based Applications This specification applies to user-agent-based applications, which is a client profile defined in Section 2.1 of . A user-agent- based application is a public client in which the client code is downloaded from a web server and executes within a user-agent (e.g., web browser) on the device used by the resource owner. Protocol data and credentials are easily accessible (and often visible) to the resource owner. Since such applications reside within the user- agent, they can make seamless use of the user-agent capabilities when requesting authorization. This specification has been designed around the following user-agent- based application profiles, representing common architectual patterns for building web applications:

"multi-page application":

A multi-page application (MPA) is a user- agent-based application that interacts with the user using hypertext, where each interaction triggers a request to a server which responds with a new page that is loaded into the browser. A MPA makes use of HTML links, forms, and HTTP redirects.

"single-page application":

A single-page application (SPA) is a user- agent-based application that interacts with the user by dynamically rewriting the current page rather than loading entire new pages from a server. A SPA makes use of JavaScript and web browser APIs.

"hybrid application":

A hybrid application is a user-agent-based application that interacts with the user using both hypertext and dynamic scripting. A hybrid application makes use of both HTML and/or JavaScript within a single page and the entirety of the application may span multiple pages.

Cookie Response Mode This specification defines the Cookie Response Mode, which is described with its response_mode parameter value:

"cookie":

In this mode, the access token parameter of an authorization response is encoded in a Set-Cookie HTTP header when responding to the client.

Authorization Request The client constructs the request URI as defined in Section 4.2.1 of , and includes the response_mode extension parameter as defined by this specification. The client directs the resource owner to the constructed URI using an HTTP redirection response, or by other means available to it via the user-agent. For example, the client directs the user-agent to make the following HTTP request using TLS (with extra line breaks for display purposes only):

Access Token Response If the resource owner grants the access request, the authorization server issues an access token and delivers it to the client by including an HTTP Set-Cookie header in the redirection response to the client as defined by . Any additional parameters other than the access token are added to the fragment component of the redirection URI as defined in Section 4.2.2 of . For example, the authorization server redirects the user-agent by sending the following HTTP response (with extra line breaks for display purposes only):

Accessing Protected Resources This specification describes how to use the HTTP state management mechanism defined by to access protected resources.

Bearer Token Usage defines how to use bearer tokens in HTTP requests, primarily using the WWW-Authenticate and Authorization HTTP headers defined by . Many user-agent-based applications, particularly multi-page applications, do not make use of the HTTP Authentication framework to authorize access to protected resources. Instead, these applications use cookies to establish a "session" for subsequent requests to the server. This section defines a method of sending bearer access tokens in resource requests to resource servers that makes use of the HTTP state management mechanism implemented by the user-agent within which a user-agent-based application is executing.

Cookie Request Header Field When sending the access token using the HTTP state management mechanism, the client uses the "Cookie" request header field to transmit the access token. For example: This method is implemented by user-agents in such a way that the "Cookie" request header field, and associated access token, are are automatically presented by the client to the resource server, typically without any involvement from the client developer. For example, a multi-page application would make the above request when the end-user clicks on a link: Resource ]]> The corresponding HTTP POST request to the same endpoint would be made when the end-user submits a form, for example: Name: Update ]]>

Unauthenticated Requests If the protected resource request does not include authentication credentials or does not contain an access token that enables access to the protected resource, the resource server MAY include the HTTP WWW-Authenticate response header field. If the resource server includes the HTTP WWW-Authenticate response header field, it SHOULD use the auth-scheme value Cookie as defined by . For example: Unauthorized

Username: Password: Sign in

]]>

TODO Discuss cookie attributes like Expires and Path in relation to Resource servers and token expiration times. Works when authorization server and the resource server (and the client?) are the same entity. - Client may need to be same entity as AS, depending on browser cookie restrictinos like ITP.

Security Considerations TODO Security

IANA Considerations This document has no IANA actions.

References Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This document defines the HTTP Cookie and Set-Cookie header fields. These header fields can be used by HTTP servers to store state (called cookies) at HTTP user agents, letting the servers maintain a stateful session over the mostly stateless HTTP protocol. Although cookies have many historical infelicities that degrade their security and privacy, the Cookie and Set-Cookie header fields are widely used on the Internet. This document obsoletes RFC 2965. [STANDARDS-TRACK] This document specifies an HTTP authentication scheme for use when credentials are validated by an out-of-band mechanism (not defined here) and later communicated to the server through the use of a cookie. Which out-of-band mechanism should be used, and how, is described by the 401 (Unauthorized) response body. It is common practice that this mechanism is an HTML form, sending the user's credentials with the use of an HTTP POST request to a tier URL which will set a cookie in response; though this document doesn't preclude the use of other mechanisms. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References SPRIND Yubico Independent Researcher Authlete This document describes best current security practice for OAuth 2.0. It updates and extends the threat model and security advice given in [RFC6749], [RFC6750], and [RFC6819] to incorporate practical experiences gathered since OAuth 2.0 was published and covers new threats relevant due to the broader application of OAuth 2.0. It further deprecates some modes of operation that are deemed less secure or even insecure. Okta Ping Identity Pragmatic Web Security This specification details the threats, attack consequences, security considerations and best practices that must be taken into account when developing browser-based applications that use OAuth 2.0. Discussion Venues This note is to be removed before publishing as an RFC. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Source for this draft and an issue tracker can be found at https://github.com/oauth-wg/oauth-browser-based-apps. This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypermedia information systems. This document defines the HTTP Authentication framework.

Acknowledgments TODO acknowledge.