OAuth Cookie Response Mode

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 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 19 August 2024.¶

Copyright Notice

Copyright (c) 2024 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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. 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 [I-D.ietf-oauth-security-topics] and [I-D.ietf-oauth-browser-based-apps]. 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.¶

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3. User-Agent-based Applications

This specification applies to user-agent-based applications, which is a client profile defined in Section 2.1 of [RFC6749]. 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.¶

4. 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.¶

GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz
   &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
   &response_mode=cookie HTTP/1.1
Host: server.example.com

HTTP/1.1 302 Found
Location: http://example.com/cb#state=xyz&token_type=example
          &expires_in=3600
Set-Cookie: at=2YotnFZFEjr1zCsicMWpAA; Path=/

5. Accessing Protected Resources

This specification describes how to use the HTTP state management mechanism defined by [RFC6265] to access protected resources.¶

GET /resource HTTP/1.1
Host: server.example.com
Cookie: at=2YotnFZFEjr1zCsicMWpAA
Accept: text/html

<a href="https://server.example.com/resource">Resource</a>

<form action="https://server.example.com/resource" method="post">
  <label for="description">Name:</label>
  <input type="text" id="description" name="description">
  <button type="submit">Update</button>
</form>

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Cookie realm="example"
                         form-action="/login"
                         cookie-name=at
Content-Type: text/html

<title>Unauthorized</title>
<form action="/login" method="post">
  <label for="username">Username:</label>
  <input type="text" id="username" name="username">
  <label for="password">Password:</label>
  <input type="password" id="password" name="password">
  <button type="submit">Sign in</button>
</form>

6. 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.¶

7. Security Considerations

TODO Security¶

8. IANA Considerations

This document has no IANA actions.¶

Acknowledgments

TODO acknowledge.¶

Author's Address