draft-ietf-oauth-browser-based-apps-00.txt   draft-ietf-oauth-browser-based-apps-01.txt 
Open Authentication Protocol A. Parecki Open Authentication Protocol A. Parecki
Internet-Draft Okta Internet-Draft Okta
Intended status: Best Current Practice D. Waite Intended status: Best Current Practice D. Waite
Expires: August 2, 2019 Ping Identity Expires: September 28, 2019 Ping Identity
January 29, 2019 March 27, 2019
OAuth 2.0 for Browser-Based Apps OAuth 2.0 for Browser-Based Apps
draft-ietf-oauth-browser-based-apps-00 draft-ietf-oauth-browser-based-apps-01
Abstract Abstract
OAuth 2.0 authorization requests from apps running entirely in a OAuth 2.0 authorization requests from browser-based apps must be made
browser are unable to use a Client Secret during the process, since using the authorization code grant with the PKCE extension, and
they have no way to keep a secret confidential. This specification should not be issued a client secret when registered.
details the security considerations that must be taken into account
when developing browser-based applications, as well as best practices This specification details the security considerations that must be
for how they can securely implement OAuth 2.0. taken into account when developing browser-based applications, as
well as best practices for how they can securely implement OAuth 2.0.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 2, 2019. This Internet-Draft will expire on September 28, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5. First-Party Applications . . . . . . . . . . . . . . . . . . 4 5. First-Party Applications . . . . . . . . . . . . . . . . . . 5
6. Architectural Considerations . . . . . . . . . . . . . . . . 5 6. Architectural Considerations . . . . . . . . . . . . . . . . 5
6.1. Apps Served from the Same Domain as the API . . . . . . . 5 6.1. Apps Served from a Common Domain as the API . . . . . . . 5
6.2. Browser-Based App with a Backend Component . . . . . . . 5 6.2. Browser-Based App with a Backend Component . . . . . . . 6
7. Authorization Code Flow . . . . . . . . . . . . . . . . . . . 6 7. Authorization Code Flow . . . . . . . . . . . . . . . . . . . 6
7.1. Initiating the Authorization Request from a Browser-Based 7.1. Initiating the Authorization Request from a Browser-Based
Application . . . . . . . . . . . . . . . . . . . . . . . 6 Application . . . . . . . . . . . . . . . . . . . . . . . 6
7.2. Handling the Authorization Code Redirect . . . . . . . . 6 7.2. Handling the Authorization Code Redirect . . . . . . . . 7
8. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . . . 7 8. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . . . 7
9. Security Considerations . . . . . . . . . . . . . . . . . . . 7 9. Security Considerations . . . . . . . . . . . . . . . . . . . 8
9.1. Registration of Browser-Based Apps . . . . . . . . . . . 7 9.1. Registration of Browser-Based Apps . . . . . . . . . . . 8
9.2. Client Authentication . . . . . . . . . . . . . . . . . . 7 9.2. Client Authentication . . . . . . . . . . . . . . . . . . 8
9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 8 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 8
9.4. Cross-Site Request Forgery Protections . . . . . . . . . 8 9.4. Cross-Site Request Forgery Protections . . . . . . . . . 9
9.5. Authorization Server Mix-Up Mitigation . . . . . . . . . 8 9.5. Authorization Server Mix-Up Mitigation . . . . . . . . . 9
9.6. Cross-Domain Requests . . . . . . . . . . . . . . . . . . 9 9.6. Cross-Domain Requests . . . . . . . . . . . . . . . . . . 9
9.7. Content-Security Policy . . . . . . . . . . . . . . . . . 9 9.7. Content-Security Policy . . . . . . . . . . . . . . . . . 10
9.8. OAuth Implicit Grant Authorization Flow . . . . . . . . . 9 9.8. OAuth Implicit Grant Authorization Flow . . . . . . . . . 10
9.8.1. Threat: Interception of the Redirect URI . . . . . . 10 9.8.1. Threat: Interception of the Redirect URI . . . . . . 10
9.8.2. Threat: Access Token Leak in Browser History . . . . 10 9.8.2. Threat: Access Token Leak in Browser History . . . . 10
9.8.3. Threat: Manipulation of Scripts . . . . . . . . . . . 10 9.8.3. Threat: Manipulation of Scripts . . . . . . . . . . . 10
9.8.4. Threat: Access Token Leak to Third Party Scripts . . 10 9.8.4. Threat: Access Token Leak to Third Party Scripts . . 11
9.8.5. Countermeasures . . . . . . . . . . . . . . . . . . . 11 9.8.5. Countermeasures . . . . . . . . . . . . . . . . . . . 11
9.8.6. Disadvantages of the Implicit Flow . . . . . . . . . 11 9.8.6. Disadvantages of the Implicit Flow . . . . . . . . . 11
9.8.7. Historic Note . . . . . . . . . . . . . . . . . . . . 12 9.8.7. Historic Note . . . . . . . . . . . . . . . . . . . . 12
9.9. Additional Security Considerations . . . . . . . . . . . 12 9.9. Additional Security Considerations . . . . . . . . . . . 12
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
11.1. Normative References . . . . . . . . . . . . . . . . . . 12 11.1. Normative References . . . . . . . . . . . . . . . . . . 12
11.2. Informative References . . . . . . . . . . . . . . . . . 13 11.2. Informative References . . . . . . . . . . . . . . . . . 13
Appendix A. Server Support Checklist . . . . . . . . . . . . . . 13 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 13
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 13 Appendix B. Document History . . . . . . . . . . . . . . . . . . 14
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction 1. Introduction
This specification describes the current best practices for This specification describes the current best practices for
implementing OAuth 2.0 authorization flows in applications running implementing OAuth 2.0 authorization flows in applications running
entirely in a browser. entirely in a browser.
For native application developers using OAuth 2.0 and OpenID Connect, For native application developers using OAuth 2.0 and OpenID Connect,
an IETF BCP (best current practice) was published that guides an IETF BCP (best current practice) was published that guides
skipping to change at page 3, line 40 skipping to change at page 3, line 46
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
[RFC2119]. [RFC2119].
3. Terminology 3. Terminology
In addition to the terms defined in referenced specifications, this In addition to the terms defined in referenced specifications, this
document uses the following terms: document uses the following terms:
"OAuth": In this document, "OAuth" refers to OAuth 2.0, [RFC6749]. "OAuth": In this document, "OAuth" refers to OAuth 2.0, [RFC6749].
"Browser-based application": An application that runs entirely in a "Browser-based application": An application that is dynamically
web browser, usually written in JavaScript, where the source code downloaded and executed in a web browser, usually written in
is downloaded from a domain prior to execution. Also sometimes JavaScript. Also sometimes referred to as a "single-page
referred to as a "single-page application", or "SPA". application", or "SPA".
4. Overview 4. Overview
For authorizing users within a browser-based application, the best For authorizing users within a browser-based application, the best
current practice is to current practice is to
o Use the OAuth 2.0 authorization code flow with the PKCE extension o Use the OAuth 2.0 authorization code flow with the PKCE extension
o Require the OAuth 2.0 state parameter o Use the OAuth 2.0 state parameter to carry one-time use CSRF
tokens
o Recommend exact matching of redirect URIs, and require the o Recommend exact matching of redirect URIs, and require the
hostname of the redirect URI match the hostname of the URL the app hostname of the redirect URI match the hostname of the URL the app
was served from was served from
o Do not return access tokens in the front channel o Do not return access tokens in the front channel
Previously it was recommended that browser-based applications use the Since the publication of OAuth 2.0 RFC 6749, browsers have broadly
OAuth 2.0 Implicit flow. That approach has several drawbacks, adopted the concept of CORS, enabling the ability for JavaScript
including the fact that access tokens are returned in the front- applications to make cross-domain requests. During the time RFC 6749
channel via the fragment part of the redirect URI, and as such are was originally being written, browsers did not have wide support, so
vulnerable to a variety of attacks where the access token can be it was not possible to require browsers to use the authorization code
intercepted or stolen. See Section 9.8 for a deeper analysis of flow, so the implicit flow was developed instead.
these attacks and the drawbacks of using the Implicit flow in
browsers, many of which are described by [oauth-security-topics].
Instead, browser-based apps can perform the OAuth 2.0 authorization There are several drawbacks to the implicit flow, including the fact
code flow and make a POST request to the token endpoint to exchange that access tokens are returned in the front-channel via the fragment
an authorization code for an access token, just like other OAuth part of the redirect URI, and as such are vulnerable to a variety of
clients. This ensures that access tokens are not sent via the less attacks where the access token can be intercepted or stolen. See
secure front-channel, and are only returned over an HTTPS connection Section 9.8 for a deeper analysis of these attacks and the drawbacks
initiated from the application. Combined with PKCE, this enables the of using the implicit flow in browsers, many of which are described
authorization server to ensure that authorization codes are useless by [oauth-security-topics].
even if intercepted in transport.
Now, thanks to the wide adoption of CORS, browser-based apps can
perform the OAuth 2.0 authorization code flow and make a POST request
to the token endpoint to exchange an authorization code for an access
token, just like other OAuth clients. This ensures that access
tokens are not sent via the less secure front-channel, and are only
returned over an HTTPS connection initiated from the application.
Combined with PKCE, this enables the authorization server to ensure
that authorization codes are useless even if intercepted in
transport.
Historically, the Implicit flow provided an advantage to single-page
apps since JavaScript could always arbitrarily read and manipulate
the fragment portion of the URL without triggering a page reload.
Now with the Session History API (described in "Session history and
navigation" of [HTML]), browsers have a mechanism to modify the path
component of the URL without triggering a page reload, so this
overloaded use of the fragment portion is no longer needed.
5. First-Party Applications 5. First-Party Applications
While OAuth and OpenID Connect were initially created to allow third- While OAuth and OpenID Connect were initially created to allow third-
party applications to access an API on behalf of a user, they have party applications to access an API on behalf of a user, they have
both proven to be useful in a first-party scenario as well. First- both proven to be useful in a first-party scenario as well. First-
party apps are applications created by the same organization that party apps are applications where by the same organization that
provides the API being accessed by the application. provides the API being accessed by the application.
For example, a web email client provided by the operator of the email For example, a web email client provided by the operator of the email
account, or a mobile banking application created by bank itself. account, or a mobile banking application created by bank itself.
(Note that there is no requirement that the application actually be (Note that there is no requirement that the application actually be
developed by the same company; a mobile banking application developed developed by the same company; a mobile banking application developed
by a contractor that is branded as the bank's application is still by a contractor that is branded as the bank's application is still
considered a first-party application.) The first-party app considered a first-party application.) The first-party app
consideration is about the user's relationship to the application and consideration is about the user's relationship to the application and
the service. the service.
skipping to change at page 5, line 13 skipping to change at page 5, line 38
redirecting to the authorization server, this provides the redirecting to the authorization server, this provides the
authorization server the opportunity to prompt the user for multi- authorization server the opportunity to prompt the user for multi-
factor authentication options, take advantage of single-sign-on factor authentication options, take advantage of single-sign-on
sessions, or use third-party identity providers. In contrast, the sessions, or use third-party identity providers. In contrast, the
Password grant does not provide any built-in mechanism for these, and Password grant does not provide any built-in mechanism for these, and
must be extended with custom code. must be extended with custom code.
6. Architectural Considerations 6. Architectural Considerations
In some cases, it may make sense to avoid the use of a strictly In some cases, it may make sense to avoid the use of a strictly
browser-based OAuth application entirely, instead using an browser-based OAuth application entirely, and instead use an
architecture that can provide better security. architecture that keeps OAuth access tokens out of the browser.
6.1. Apps Served from the Same Domain as the API 6.1. Apps Served from a Common Domain as the API
For simple system architectures, such as when the JavaScript For simple system architectures, such as when the JavaScript
application is served from the same domain as the API (resource application is served from a domain that can share cookies with the
server) being accessed, it is likely a better decision to avoid using API's (resource server's) domain, it is likely a better decision to
OAuth entirely, and just use session authentication to communicate avoid using OAuth entirely, and just use session authentication to
with the API. communicate with the API.
OAuth and OpenID Connect provide very little benefit in this OAuth and OpenID Connect provide very little benefit in this
deployment scenario, so it is recommended to reconsider whether you deployment scenario, so it is recommended to reconsider whether you
need OAuth or OpenID Connect at all in this case. Session need OAuth or OpenID Connect at all in this case. Session
authentication has the benefit of having fewer moving parts and fewer authentication has the benefit of having fewer moving parts and fewer
attack vectors. OAuth and OpenID Connect were created primarily for attack vectors. OAuth and OpenID Connect were created primarily for
third-party or federated access to APIs, so may not be the best third-party or federated access to APIs, so may not be the best
solution in a same-domain scenario. solution in a same-domain scenario.
6.2. Browser-Based App with a Backend Component 6.2. Browser-Based App with a Backend Component
To avoid the risks inherent in handling OAuth access tokens from a To avoid the risks inherent in handling OAuth access tokens from a
purely browser-based application, implementations may wish to move purely browser-based application, implementations may wish to move
the authorization code exchange and handling of access and refresh the authorization code exchange and handling of access and refresh
tokens into a backend component. tokens into a backend component.
The backend component essentially becomes a new authorization server Security of the connection between code running in the browser and
for the code running in the browser, issuing its own tokens (e.g. a this backend component is assumed to utilize browser-level protection
session cookie). Security of the connection between code running in mechanisms. Details are out of scope of this document, but many
the browser and this backend component is assumed to utilize browser- recommendations can be found at the OWASP Foundation
level protection mechanisms. Details are out of scope of this (https://www.owasp.org/).
document, but many recommendations can be found at the OWASP
Foundation (https://www.owasp.org/).
In this scenario, the backend component may be a confidential client In this scenario, the backend component may be a confidential client
which is issued its own client secret. Despite this, there are still which has the ability to authenticate itself. Despite this, there
some ways in which this application is effectively a public client, are still some ways in which this application is effectively a public
as the end result is the application's code is still running in the client, as the end result is the application's code is still running
browser and visible to the user. Some authorization servers may have in the browser and visible to the user. Some authorization servers
different policies for public and confidential clients, and this type may have different policies for public and confidential clients, and
of hybrid approach does not provide all the assurances of this type of hybrid approach does not provide all the assurances of
confidential clients that an authorization server is expecting. confidential clients that an authorization server is expecting.
Authorization servers may wish to treat this type of deployment as a Authorization servers may wish to treat this type of deployment as a
public client. public client.
7. Authorization Code Flow 7. Authorization Code Flow
Public browser-based apps needing user authorization create an Public browser-based apps needing user authorization create an
authorization request URI with the authorization code grant type per authorization request URI with the authorization code grant type per
Section 4.1 of OAuth 2.0 [RFC6749], using a redirect URI capable of Section 4.1 of OAuth 2.0 [RFC6749], using a redirect URI capable of
being received by the app. being received by the app.
skipping to change at page 13, line 37 skipping to change at page 14, line 8
3. Support PKCE [RFC7636]. Required to protect authorization code 3. Support PKCE [RFC7636]. Required to protect authorization code
grants sent to public clients. See Section 7.1 grants sent to public clients. See Section 7.1
4. Support cross-domain requests at the token endpoint in order to 4. Support cross-domain requests at the token endpoint in order to
allow browsers to make the authorization code exchange request. allow browsers to make the authorization code exchange request.
See Section 9.6 See Section 9.6
5. Not assume that browser-based clients can keep a secret, and 5. Not assume that browser-based clients can keep a secret, and
SHOULD NOT issue secrets to applications of this type. SHOULD NOT issue secrets to applications of this type.
Appendix B. Acknowledgements Appendix B. Document History
[[ To be removed from the final specification ]]
-01
o Incorporated feedback from Torsten Lodderstedt
o Updated abstract
o Clarified the definition of browser-based apps to not exclude
applications cached in the browser, e.g. via Service Workers
o Clarified use of the state parameter for CSRF protection
o Added background information about the original reason the
implicit flow was created due to lack of CORS support
o Clarified the same-domain use case where the SPA and API share a
cookie domain
o Moved historic note about the fragment URL into the Overview
Appendix C. Acknowledgements
The authors would like to acknowledge the work of William Denniss and The authors would like to acknowledge the work of William Denniss and
John Bradley, whose recommendation for native apps informed many of John Bradley, whose recommendation for native apps informed many of
the best practices for browser-based applications. The authors would the best practices for browser-based applications. The authors would
also like to thank Hannes Tschofenig and Torsten Lodderstedt, the also like to thank Hannes Tschofenig and Torsten Lodderstedt, the
attendees of the Internet Identity Workshop 27 session at which this attendees of the Internet Identity Workshop 27 session at which this
BCP was originally proposed, and the following individuals who BCP was originally proposed, and the following individuals who
contributed ideas, feedback, and wording that shaped and formed the contributed ideas, feedback, and wording that shaped and formed the
final specification: final specification:
 End of changes. 24 change blocks. 
68 lines changed or deleted 108 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/