draft-ietf-oauth-browser-based-apps-04.txt   draft-ietf-oauth-browser-based-apps-05.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: March 25, 2020 Ping Identity Expires: August 31, 2020 Ping Identity
September 22, 2019 February 28, 2020
OAuth 2.0 for Browser-Based Apps OAuth 2.0 for Browser-Based Apps
draft-ietf-oauth-browser-based-apps-04 draft-ietf-oauth-browser-based-apps-05
Abstract Abstract
This specification details the security considerations and best This specification details the security considerations and best
practices that must be taken into account when developing browser- practices that must be taken into account when developing browser-
based applications that use OAuth 2.0. based applications that use 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
skipping to change at page 1, line 33 skipping to change at page 1, line 33
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 March 25, 2020. This Internet-Draft will expire on August 31, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 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
skipping to change at page 2, line 19 skipping to change at page 2, line 19
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. First-Party Applications . . . . . . . . . . . . . . . . . . 4 5. First-Party Applications . . . . . . . . . . . . . . . . . . 4
6. Application Architecture Patterns . . . . . . . . . . . . . . 5 6. Application Architecture Patterns . . . . . . . . . . . . . . 5
6.1. Browser-Based Apps that Can Share Data with the Resource 6.1. Browser-Based Apps that Can Share Data with the Resource
Server . . . . . . . . . . . . . . . . . . . . . . . . . 5 Server . . . . . . . . . . . . . . . . . . . . . . . . . 5
6.2. JavaScript Applications with a Backend . . . . . . . . . 6 6.2. JavaScript Applications with a Backend . . . . . . . . . 6
6.3. JavaScript Applications without a Backend . . . . . . . . 8 6.3. JavaScript Applications without a Backend . . . . . . . . 8
7. Authorization Code Flow . . . . . . . . . . . . . . . . . . . 9 7. Authorization Code Flow . . . . . . . . . . . . . . . . . . . 9
7.1. Initiating the Authorization Request from a Browser-Based 7.1. Initiating the Authorization Request from a Browser-Based
Application . . . . . . . . . . . . . . . . . . . . . . . 9 Application . . . . . . . . . . . . . . . . . . . . . . . 10
7.2. Handling the Authorization Code Redirect . . . . . . . . 9 7.2. Handling the Authorization Code Redirect . . . . . . . . 10
8. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . . . 10 8. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . . . 10
9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11
9.1. Registration of Browser-Based Apps . . . . . . . . . . . 11 9.1. Registration of Browser-Based Apps . . . . . . . . . . . 12
9.2. Client Authentication . . . . . . . . . . . . . . . . . . 11 9.2. Client Authentication . . . . . . . . . . . . . . . . . . 12
9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 11 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 12
9.4. Cross-Site Request Forgery Protections . . . . . . . . . 12 9.4. Cross-Site Request Forgery Protections . . . . . . . . . 13
9.5. Authorization Server Mix-Up Mitigation . . . . . . . . . 12 9.5. Authorization Server Mix-Up Mitigation . . . . . . . . . 13
9.6. Cross-Domain Requests . . . . . . . . . . . . . . . . . . 12 9.6. Cross-Domain Requests . . . . . . . . . . . . . . . . . . 13
9.7. Content-Security Policy . . . . . . . . . . . . . . . . . 13 9.7. Content-Security Policy . . . . . . . . . . . . . . . . . 14
9.8. OAuth Implicit Grant Authorization Flow . . . . . . . . . 13 9.8. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 14
9.8.1. Threat: Interception of the Redirect URI . . . . . . 13 9.8.1. Attacks on the Implicit Flow . . . . . . . . . . . . 14
9.8.2. Threat: Access Token Leak in Browser History . . . . 13 9.8.2. Countermeasures . . . . . . . . . . . . . . . . . . . 15
9.8.3. Threat: Manipulation of Scripts . . . . . . . . . . . 14 9.8.3. Disadvantages of the Implicit Flow . . . . . . . . . 15
9.8.4. Threat: Access Token Leak to Third Party Scripts . . 14 9.8.4. Historic Note . . . . . . . . . . . . . . . . . . . . 16
9.8.5. Countermeasures . . . . . . . . . . . . . . . . . . . 14
9.8.6. Disadvantages of the Implicit Flow . . . . . . . . . 14
9.8.7. Historic Note . . . . . . . . . . . . . . . . . . . . 15
9.9. Additional Security Considerations . . . . . . . . . . . 16 9.9. Additional Security Considerations . . . . . . . . . . . 16
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
11.1. Normative References . . . . . . . . . . . . . . . . . . 16 11.1. Normative References . . . . . . . . . . . . . . . . . . 17
11.2. Informative References . . . . . . . . . . . . . . . . . 17 11.2. Informative References . . . . . . . . . . . . . . . . . 18
Appendix A. Server Support Checklist . . . . . . . . . . . . . . 17 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 18
Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 Appendix B. Document History . . . . . . . . . . . . . . . . . . 18
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 19 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 20
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
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 executing
entirely in a browser. 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
integration of these technologies. This document is formally known integration of these technologies. This document is formally known
as [RFC8252] or BCP 212, but nicknamed "AppAuth" after the OpenID as [RFC8252] or BCP 212, but nicknamed "AppAuth" after the OpenID
Foundation-sponsored set of libraries that assist developers in Foundation-sponsored set of libraries that assist developers in
adopting these practices. adopting these practices. [RFC8252] makes specific recommendations
for how to securely implement OAuth in native applications, including
[RFC8252] makes specific recommendations for how to securely incorporating additional OAuth extensions where needed.
implement OAuth in native applications, including incorporating
additional OAuth extensions where needed.
OAuth 2.0 for Browser-Based Apps addresses the similarities between OAuth 2.0 for Browser-Based Apps addresses the similarities between
implementing OAuth for native apps as well as browser-based apps, and implementing OAuth for native apps and browser-based apps, and
includes additional considerations when running in a browser. This includes additional considerations when running in a browser. This
is primarily focused on OAuth, except where OpenID Connect provides is primarily focused on OAuth, except where OpenID Connect provides
additional considerations. additional considerations.
2. Notational Conventions 2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"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]
and [RFC6750].
"Browser-based application": An application that is dynamically "Browser-based application": An application that is dynamically
downloaded and executed in a web browser, usually written in downloaded and executed in a web browser, usually written in
JavaScript. Also sometimes referred to as a "single-page JavaScript. Also sometimes referred to as a "single-page
application", or "SPA". application", or "SPA".
4. Overview 4. Overview
At the time that OAuth 2.0 RFC 6749 was created, browser-based At the time that OAuth 2.0 [RFC6749] and [RFC6750] were created,
JavaScript applications needed a solution that strictly complied with browser-based JavaScript applications needed a solution that strictly
the same-origin policy. Common deployments of OAuth 2.0 involved an complied with the same-origin policy. Common deployments of OAuth
application running on a different domain than the authorization 2.0 involved an application running on a different domain than the
server, so it was historically not possible to use the authorization authorization server, so it was historically not possible to use the
code flow which would require a cross-origin POST request. This was authorization code flow which would require a cross-origin POST
the principal motivation for the definition of the implicit flow, request. This was one of the motivations for the definition of the
which returns the access token in the front channel via the fragment implicit flow, which returns the access token in the front channel
part of the URL, bypassing the need for a cross-origin POST request. via the fragment part of the URL, bypassing the need for a cross-
origin POST request.
However, there are several drawbacks to the implicit flow, generally However, there are several drawbacks to the implicit flow, generally
involving vulnerabilities associated with the exposure of the access involving vulnerabilities associated with the exposure of the access
token in the URL. See Section 9.8 for an analysis of these attacks token in the URL. See Section 9.8 for an analysis of these attacks
and the drawbacks of using the implicit flow in browsers. Additional and the drawbacks of using the implicit flow in browsers. Additional
attacks and security considerations can be found in attacks and security considerations can be found in
[oauth-security-topics]. [oauth-security-topics].
In recent years, widespread adoption of Cross-Origin Resource Sharing In recent years, widespread adoption of Cross-Origin Resource Sharing
(CORS), which enables exceptions to the same-origin policy, allows (CORS), which enables exceptions to the same-origin policy, allows
browser-based apps to use the OAuth 2.0 authorization code flow and browser-based apps to use the OAuth 2.0 authorization code flow and
make a POST request to exchange the authorization code for an access make a POST request to exchange the authorization code for an access
token at the token endpoint. In this flow, the access token is never token at the token endpoint. In this flow, the access token is never
exposed in the less secure front-channel. Furthermore, adding PKCE exposed in the less secure front-channel. Furthermore, adding PKCE
to the flow assures that even if an authorization code is to the flow ensures that even if an authorization code is
intercepted, it is unusable by an attacker. intercepted, it is unusable by an attacker.
For this reason, and from other lessons learned, the current best For this reason, and from other lessons learned, the current best
practice for browser-based applications is to use the OAuth 2.0 practice for browser-based applications is to use the OAuth 2.0
authorization code flow with PKCE. authorization code flow with PKCE.
Browser-based applications MUST: Browser-based applications MUST:
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 Protect themselves against CSRF attacks by using the OAuth 2.0 o Protect themselves against CSRF attacks by ensuring the
state parameter to carry one-time use CSRF tokens, or by ensuring authorization server supports PKCE, or by using the OAuth 2.0
the authorization server supports PKCE "state" parameter or the OpenID Connect "nonce" parameter to carry
one-time use CSRF tokens
o Register one or more redirect URIs, and not vary the redirect URI o Register one or more redirect URIs, and use only exact registered
per authorization request redirect URIs in authorization requests
OAuth 2.0 authorization servers MUST: OAuth 2.0 authorization servers MUST:
o Require exact matching of registered redirect URIs o Require exact matching of registered redirect URIs
o Support the PKCE extension o Support the PKCE extension
5. First-Party Applications 5. First-Party Applications
While OAuth was initially created to allow third-party applications While OAuth was initially created to allow third-party applications
to access an API on behalf of a user, it has proven to be useful in a to access an API on behalf of a user, it has proven to be useful in a
first-party scenario as well. First-party apps are applications first-party scenario as well. First-party apps are applications
where the same organization provides both the API and the where the same organization provides both the API and the
application. application.
For example, a web email client provided by the operator of the email Examples of first-party applications are a web email client provided
account, or a mobile banking application created by bank itself. by the operator of the email account, or a mobile banking application
(Note that there is no requirement that the application actually be created by bank itself. (Note that there is no requirement that the
developed by the same company; a mobile banking application developed application actually be developed by the same company; a mobile
by a contractor that is branded as the bank's application is still banking application developed by a contractor that is branded as the
considered a first-party application.) The first-party app bank's application is still considered a first-party application.)
consideration is about the user's relationship to the application and The first-party app consideration is about the user's relationship to
the service. the application and the service.
To conform to this best practice, first-party applications using To conform to this best practice, first-party applications using
OAuth or OpenID Connect MUST use the OAuth Authorization Code flow as OAuth or OpenID Connect MUST use a redirect-based flow (such as the
described later in this document. OAuth Authorization Code flow) as described later in this document.
The Resource Owner Password Grant MUST NOT be used, as described in The Resource Owner Password Grant MUST NOT be used, as described in
[oauth-security-topics] section 3.4. [oauth-security-topics] section 3.4. Instead, by using the
Authorization Code flow and redirecting the user to the authorization
By using the Authorization Code flow and redirecting the user to the server, this provides the authorization server the opportunity to
authorization server, this provides the authorization server the prompt the user for multi-factor authentication options, take
opportunity to prompt the user for multi-factor authentication advantage of single-sign-on sessions, or use third-party identity
options, take advantage of single-sign-on sessions, or use third- providers. In contrast, the Password grant does not provide any
party identity providers. In contrast, the Password grant does not built-in mechanism for these, and would instead be extended with
provide any built-in mechanism for these, and would instead be custom code.
extended with custom code.
6. Application Architecture Patterns 6. Application Architecture Patterns
There are three primary architectural patterns available when There are three primary architectural patterns available when
building browser-based applications. building browser-based applications.
o a JavaScript application with no backend, accessing resource o a JavaScript application that has methods of sharing data with
servers directly resource servers, such as using common-domain cookies
o a JavaScript application with a backend o a JavaScript application with a backend
o a JavaScript application that has methods of sharing data with o a JavaScript application with no backend, accessing resource
resource servers, such as using common-domain cookies servers directly
These three architectures have different use cases and These three architectures have different use cases and
considerations. considerations.
6.1. Browser-Based Apps that Can Share Data with the Resource Server 6.1. Browser-Based Apps that Can Share Data with the Resource Server
For simple system architectures, such as when the JavaScript For simple system architectures, such as when the JavaScript
application is served from a domain that can share cookies with the application is served from a domain that can share cookies with the
domain of the API (resource server), OAuth adds additional attack domain of the API (resource server), OAuth adds additional attack
vectors that could be avoided with a different solution. vectors that could be avoided with a different solution.
In particular, using any redirect-based mechanism of obtaining an In particular, using any redirect-based mechanism of obtaining an
access token enables the redirect-based attacks described in access token enables the redirect-based attacks described in
[oauth-security-topics], but if the application, AS and API share a [oauth-security-topics], but if the application, authorization server
domain, then it is unnecessary to use a redirect mechanism to and resource server share a domain, then it is unnecessary to use a
communicate between them. redirect mechanism to communicate between them.
An additional concern with handling access tokens in a browser is An additional concern with handling access tokens in a browser is
that there is no secure storage mechanism where JavaScript code can that as of the date of this publication, there is no secure storage
keep the access token to be later used in an API request. Using an mechanism where JavaScript code can keep the access token to be later
OAuth flow results in the JavaScript code getting an access token, used in an API request. Using an OAuth flow results in the
needing to store it somewhere, and then retrieve it to make an API JavaScript code getting an access token, needing to store it
request. Instead, a more secure design is to use an HTTP-only cookie somewhere, and then retrieve it to make an API request.
between the JavaScript application and API so that the JavaScript
code can't access the cookie value itself. Instead, a more secure design is to use an HTTP-only cookie between
the JavaScript application and API so that the JavaScript code can't
access the cookie value itself. Additionally, the SameSite cookie
attribute can be used to prevent CSRF attacks, or alternatively, the
application and API could be written to use anti-CSRF tokens.
OAuth was originally created for third-party or federated access to OAuth was originally created for third-party or federated access to
APIs, so it may not be the best solution in a common-domain APIs, so it may not be the best solution in a common-domain
deployment. That said, using OAuth even in a common-domain deployment. That said, using OAuth even in a common-domain
architecture does mean you can more easily rearchitect things later, architecture does mean you can more easily rearchitect things later,
such as if you were to later add a new domain to the system. such as if you were to later add a new domain to the system.
6.2. JavaScript Applications with a Backend 6.2. JavaScript Applications with a Backend
+-------------+ +-------------+
| | | |
skipping to change at page 7, line 41 skipping to change at page 7, line 41
| | | |
| Browser | | Browser |
| | | |
+-------------+ +-------------+
In this architecture, the JavaScript code is loaded from a dynamic In this architecture, the JavaScript code is loaded from a dynamic
Application Server that also has the ability to execute code itself. Application Server that also has the ability to execute code itself.
This enables the ability to keep all of the steps involved in This enables the ability to keep all of the steps involved in
obtaining an access token outside of the JavaScript application. obtaining an access token outside of the JavaScript application.
In this case, the Application Server performs the OAuth flow itself,
and keeps the access token and refresh token stored internally,
creating a separate session with the browser-based app via a
traditional browser cookie.
(Common examples of this architecture are an Angular front-end with a (Common examples of this architecture are an Angular front-end with a
.NET backend, or a React front-end with a Spring Boot backend.) .NET backend, or a React front-end with a Spring Boot backend.)
The Application Server SHOULD be considered a confidential client, The Application Server SHOULD be considered a confidential client,
and issued its own client secret. The Application Server SHOULD use and issued its own client secret. The Application Server SHOULD use
the OAuth 2.0 authorization code grant to initiate a request for an the OAuth 2.0 authorization code grant to initiate a request for an
access token. Upon handling the redirect from the Authorization access token. Upon handling the redirect from the Authorization
Server, the Application Server will request an access token using the Server, the Application Server will request an access token using the
authorization code returned (A), which will be returned to the authorization code returned (A), which will be returned to the
Application Server (B). The Application Server utilizes its own Application Server (B). The Application Server stores this access
session with the browser to store the access token. token itself and establishes its own cookie-based session with the
Browser application. The Application Server can store the access
token either server-side, or in the cookie itself.
When the JavaScript application in the browser wants to make a When the JavaScript application in the browser wants to make a
request to the Resource Server, it MUST instead make the request to request to the Resource Server, it MUST instead make the request to
the Application Server, and the Application Server will make the the Application Server, and the Application Server will make the
request with the access token to the Resource Server (C), and forward request with the access token to the Resource Server (C), and forward
the response (D) back to the browser. the response (D) back to the browser.
Security of the connection between code running in the browser and Security of the connection between code running in the browser and
this Application Server is assumed to utilize browser-level this Application Server is assumed to utilize browser-level
protection mechanisms. Details are out of scope of this document, protection mechanisms. Details are out of scope of this document,
but many recommendations can be found at the OWASP Foundation but many recommendations can be found in the OWASP Cheat Sheet series
(https://www.owasp.org/), such as setting an HTTP-only and Secure (https://cheatsheetseries.owasp.org/), such as setting an HTTP-only
cookie to authenticate the session between the browser and and Secure cookie to authenticate the session between the browser and
Application Server. Application Server.
In this scenario, the session between the browser and Application In this scenario, the session between the browser and Application
Server MAY be either a session cookie provided by the Application Server MAY be either a session cookie provided by the Application
Server, OR the access token itself. Note that if the access token is Server, OR the access token itself. Note that if the access token is
used as the session identifier, this exposes the access token to the used as the session identifier, this exposes the access token to the
end user even if it is not available to the JavaScript application, end user even if it is not available to the JavaScript application,
so some authorization servers may wish to limit the capabilities of so some authorization servers may wish to limit the capabilities of
these clients to mitigate risk. these clients to mitigate risk.
skipping to change at page 8, line 50 skipping to change at page 9, line 25
| | | | | | | |
+ v + v + v + v
+-----------------+ +-------------------------------+ +-----------------+ +-------------------------------+
| | (A) | | | | (A) | |
| Static Web Host | +-----> | Browser | | Static Web Host | +-----> | Browser |
| | | | | | | |
+-----------------+ +-------------------------------+ +-----------------+ +-------------------------------+
In this architecture, the JavaScript code is first loaded from a In this architecture, the JavaScript code is first loaded from a
static web host into the browser (A). The application then runs in static web host into the browser (A), and the application then runs
the browser, and is considered a public client since it has no in the browser. This application is considered a public client,
ability to be issued a client secret. since there is no way to issue it a client secret and there is no
other secure client authentication mechanism available in the
browser.
The code in the browser then initiates the authorization code flow The code in the browser initiates the authorization code flow with
with the PKCE extension (described in Section 7) (B) above, and the PKCE extension (described in Section 7) (B) above, and obtains an
obtains an access token via a POST request (C). The JavaScript app access token via a POST request (C). The JavaScript app is then
is then responsible for storing the access token securely using responsible for storing the access token (and optional refresh token)
appropriate browser APIs. securely using appropriate browser APIs.
When the JavaScript application in the browser wants to make a When the JavaScript application in the browser wants to make a
request to the Resource Server, it can include the access token in request to the Resource Server, it can include the access token in
the request (D) and make the request directly. the request (D) and make the request directly.
In this scenario, the Authorization Server and Resource Server MUST In this scenario, the Authorization Server and Resource Server MUST
support the necessary CORS headers to enable the JavaScript code to support the necessary CORS headers to enable the JavaScript code to
make this POST request from the domain on which the script is make this POST request from the domain on which the script is
executing. (See Section 9.6 for additional details.) executing. (See Section 9.6 for additional details.)
skipping to change at page 9, line 39 skipping to change at page 10, line 18
Public browser-based apps MUST implement the Proof Key for Code Public browser-based apps MUST implement the Proof Key for Code
Exchange (PKCE [RFC7636]) extension to OAuth, and authorization Exchange (PKCE [RFC7636]) extension to OAuth, and authorization
servers MUST support PKCE for such clients. servers MUST support PKCE for such clients.
The PKCE extension prevents an attack where the authorization code is The PKCE extension prevents an attack where the authorization code is
intercepted and exchanged for an access token by a malicious client, intercepted and exchanged for an access token by a malicious client,
by providing the authorization server with a way to verify the same by providing the authorization server with a way to verify the same
client instance that exchanges the authorization code is the same one client instance that exchanges the authorization code is the same one
that initiated the flow. that initiated the flow.
Browser-based apps MUST use a unique value for the the OAuth 2.0 Browser-based apps MUST prevent CSRF attacks against their redirect
"state" parameter on each request, and MUST verify the returned state URI. This can be accomplished by any of the below:
in the authorization response matches the original state the app
created. o using PKCE, and confirming that the authorization server supports
PKCE
o if the application is using OpenID Connect, by using the OpenID
Connect "nonce" parameter
o using a unique value for the OAuth 2.0 "state" parameter
Browser-based apps MUST follow the recommendations in Browser-based apps MUST follow the recommendations in
[oauth-security-topics] section 3.1 to protect themselves during [oauth-security-topics] Section 2.1 to protect themselves during
redirect flows. redirect flows.
7.2. Handling the Authorization Code Redirect 7.2. Handling the Authorization Code Redirect
Authorization servers MUST require an exact match of a registered Authorization servers MUST require an exact match of a registered
redirect URI. redirect URI.
8. Refresh Tokens 8. Refresh Tokens
Refresh tokens provide a way for applications to obtain a new access Refresh tokens provide a way for applications to obtain a new access
skipping to change at page 10, line 19 skipping to change at page 11, line 5
the risk of a leaked refresh token is greater than leaked access the risk of a leaked refresh token is greater than leaked access
tokens, since an attacker may be able to continue using the stolen tokens, since an attacker may be able to continue using the stolen
refresh token to obtain new access tokens potentially without being refresh token to obtain new access tokens potentially without being
detectable by the authorization server. detectable by the authorization server.
Browser-based applications provide an attacker with several Browser-based applications provide an attacker with several
opportunities by which a refresh token can be leaked, just as with opportunities by which a refresh token can be leaked, just as with
access tokens. As such, these applications are considered a higher access tokens. As such, these applications are considered a higher
risk for handling refresh tokens. risk for handling refresh tokens.
[oauth-security-topics] describes some additional requirements around Authorization servers may choose whether or not to issue refresh
refresh tokens on top of the recommendations of [RFC6749]. tokens to browser-based applications. [oauth-security-topics]
Applications and authorization servers conforming to this BCP MUST describes some additional requirements around refresh tokens on top
also follow the recommendations in [oauth-security-topics] around of the recommendations of [RFC6749]. Applications and authorization
refresh tokens. servers conforming to this BCP MUST also follow the recommendations
in [oauth-security-topics] around refresh tokens if refresh tokens
are issued to browser-based apps.
In particular, authorization servers: In particular, authorization servers:
o MUST rotate refresh tokens on each use, in order to be able to o MUST rotate refresh tokens on each use, in order to be able to
detect a stolen refresh token if one is replayed (described in detect a stolen refresh token if one is replayed (described in
[oauth-security-topics] section 4.12) [oauth-security-topics] section 4.12)
o MUST either set a maximum lifetime on refresh tokens OR expire if o MUST either set a maximum lifetime on refresh tokens OR expire if
the refresh token has not been used within some amount of time the refresh token has not been used within some amount of time
skipping to change at page 12, line 4 skipping to change at page 12, line 42
secret for SPA clients MUST treat the client as a public client, and secret for SPA clients MUST treat the client as a public client, and
not accept the secret as proof of the client's identity. Without not accept the secret as proof of the client's identity. Without
additional measures, such clients are subject to client impersonation additional measures, such clients are subject to client impersonation
(see Section 9.3 below). (see Section 9.3 below).
9.3. Client Impersonation 9.3. Client Impersonation
As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization
server SHOULD NOT process authorization requests automatically server SHOULD NOT process authorization requests automatically
without user consent or interaction, except when the identity of the without user consent or interaction, except when the identity of the
client can be assured. Even when the user has previously approved an client can be assured.
authorization request for a given client_id, the request SHOULD be
processed as if no previous request had been approved, unless the
identity of the client can be proven.
If authorization servers restrict redirect URIs to a fixed set of If authorization servers restrict redirect URIs to a fixed set of
absolute HTTPS URIs without wildcard domains, paths, or query string absolute HTTPS URIs, preventing the use of wildcard domains, wildcard
components, this exact match of registered absolute HTTPS URIs MAY be paths, or wildcard query string components, this exact match of
accepted by authorization servers as proof of identity of the client registered absolute HTTPS URIs MAY be accepted by authorization
for the purpose of deciding whether to automatically process an servers as proof of identity of the client for the purpose of
authorization request when a previous request for the client_id has deciding whether to automatically process an authorization request
already been approved. when a previous request for the client_id has already been approved.
9.4. Cross-Site Request Forgery Protections 9.4. Cross-Site Request Forgery Protections
Section 5.3.5 of [RFC6819] recommends using the "state" parameter to Clients MUST prevent Cross-Site Request Forgery (CSRF) attacks
link client requests and responses to prevent CSRF (Cross-Site against their redirect URI. Clients can accomplish this by either
Request Forgery) attacks. To conform to this best practice, use of ensuring the authorization server supports PKCE and relying on the
the "state" parameter is REQUIRED, as described in Section 7.1, CSRF protection that PKCE provides, or if the client is also an
unless the application has a method of ensuring the authorization OpenID Connect client, using the OpenID Connect "nonce" parameter, or
server supports PKCE, since PKCE also prevents CSRF attacks. by using the "state" parameter to carry one-time-use CSRF tokens as
described in Section 7.1.
See Section 2.1 of [oauth-security-topics] for additional details.
9.5. Authorization Server Mix-Up Mitigation 9.5. Authorization Server Mix-Up Mitigation
The security considerations around the authorization server mix-up The security considerations around the authorization server mix-up
that are referenced in Section 8.10 of [RFC8252] also apply to that are referenced in Section 8.10 of [RFC8252] also apply to
browser-based apps. browser-based apps.
Clients MUST use a unique redirect URI for each authorization server Clients MUST use a unique redirect URI for each authorization server
used by the application. The client MUST store the redirect URI used by the application. The client MUST store the redirect URI
along with the session data (e.g. along with "state") and MUST verify along with the session data (e.g. along with "state") and MUST verify
skipping to change at page 13, line 21 skipping to change at page 14, line 14
9.7. Content-Security Policy 9.7. Content-Security Policy
A browser-based application that wishes to use either long-lived A browser-based application that wishes to use either long-lived
refresh tokens or privileged scopes SHOULD restrict its JavaScript refresh tokens or privileged scopes SHOULD restrict its JavaScript
execution to a set of statically hosted scripts via a Content execution to a set of statically hosted scripts via a Content
Security Policy ([CSP2]) or similar mechanism. A strong Content Security Policy ([CSP2]) or similar mechanism. A strong Content
Security Policy can limit the potential attack vectors for malicious Security Policy can limit the potential attack vectors for malicious
JavaScript to be executed on the page. JavaScript to be executed on the page.
9.8. OAuth Implicit Grant Authorization Flow 9.8. OAuth Implicit Flow
The OAuth 2.0 Implicit grant authorization flow (defined in The OAuth 2.0 Implicit flow (defined in Section 4.2 of OAuth 2.0
Section 4.2 of OAuth 2.0 [RFC6749]) works by receiving an access [RFC6749]) works by receiving an access token in the HTTP redirect
token in the HTTP redirect (front-channel) immediately without the (front-channel) immediately without the code exchange step. In this
code exchange step. In this case, the access token is returned in case, the access token is returned in the fragment part of the
the fragment part of the redirect URI, providing an attacker with redirect URI, providing an attacker with several opportunities to
several opportunities to intercept and steal the access token. intercept and steal the access token.
Several attacks on the implicit flow are described by [RFC6819] and
[oauth-security-topics], not all of which have sufficient mitigation
strategies.
9.8.1. Threat: Interception of the Redirect URI 9.8.1. Attacks on the Implicit Flow
Many attacks on the implicit flow described by [RFC6819] and
[oauth-security-topics] do not have sufficient mitigation strategies.
The following sections describe the specific attacks that cannot be
mitigated while continuing to use the implicit flow.
9.8.1.1. Threat: Interception of the Redirect URI
If an attacker is able to cause the authorization response to be sent If an attacker is able to cause the authorization response to be sent
to a URI under his control, he will directly get access to the to a URI under their control, they will directly get access to the
fragment carrying the access token. A method of performing this fragment carrying the access token. Several methods of performing
attack is described in detail in [oauth-security-topics]. this attack are described in detail in [oauth-security-topics].
9.8.2. Threat: Access Token Leak in Browser History 9.8.1.2. Threat: Access Token Leak in Browser History
An attacker could obtain the access token from the browser's history. An attacker could obtain the access token from the browser's history.
The countermeasures recommended by [RFC6819] are limited to using The countermeasures recommended by [RFC6819] are limited to using
short expiration times for tokens, and indicating that browsers short expiration times for tokens, and indicating that browsers
should not cache the response. Neither of these fully prevent this should not cache the response. Neither of these fully prevent this
attack, they only reduce the potential damage. attack, they only reduce the potential damage.
Additionally, many browsers now also sync browser history to cloud Additionally, many browsers now also sync browser history to cloud
services and to multiple devices, providing an even wider attack services and to multiple devices, providing an even wider attack
surface to extract access tokens out of the URL. surface to extract access tokens out of the URL.
This is discussed in more detail in Section 4.3.2 of This is discussed in more detail in Section 4.3.2 of
[oauth-security-topics]. [oauth-security-topics].
9.8.3. Threat: Manipulation of Scripts 9.8.1.3. Threat: Manipulation of Scripts
An attacker could modify the page or inject scripts into the browser An attacker could modify the page or inject scripts into the browser
via various means, including when the browser's HTTPS connection is through various means, including when the browser's HTTPS connection
being man-in-the-middled by for example a corporate network. While is being man-in-the-middled by, for example, a corporate network.
this type of attack is typically out of scope of basic security While this type of attack is typically out of scope of basic security
recommendations to prevent, in the case of browser-based apps it is recommendations to prevent, in the case of browser-based apps it is
much easier to perform this kind of attack, where an injected script much easier to perform this kind of attack, where an injected script
can suddenly have access to everything on the page. can suddenly have access to everything on the page.
The risk of a malicious script running on the page is far greater The risk of a malicious script running on the page may be amplified
when the application uses a known standard way of obtaining access when the application uses a known standard way of obtaining access
tokens, namely that the attacker can always look at the tokens, namely that the attacker can always look at the
window.location to find an access token. This threat profile is very "window.location" variable to find an access token. This threat
different compared to an attacker specifically targeting an profile is different from an attacker specifically targeting an
individual application by knowing where or how an access token individual application by knowing where or how an access token
obtained via the authorization code flow may end up being stored. obtained via the authorization code flow may end up being stored.
9.8.4. Threat: Access Token Leak to Third Party Scripts 9.8.1.4. Threat: Access Token Leak to Third Party Scripts
It is relatively common to use third-party scripts in browser-based It is relatively common to use third-party scripts in browser-based
apps, such as analytics tools, crash reporting, and even things like apps, such as analytics tools, crash reporting, and even things like
a Facebook or Twitter "like" button. In these situations, the author a Facebook or Twitter "like" button. In these situations, the author
of the application may not be able to be fully aware of the entirety of the application may not be able to be fully aware of the entirety
of the code running in the application. When an access token is of the code running in the application. When an access token is
returned in the fragment, it is visible to any third-party scripts on returned in the fragment, it is visible to any third-party scripts on
the page. the page.
9.8.5. Countermeasures 9.8.2. Countermeasures
In addition to the countermeasures described by [RFC6819] and In addition to the countermeasures described by [RFC6819] and
[oauth-security-topics], using the authorization code with PKCE [oauth-security-topics], using the authorization code with PKCE
avoids these attacks. extension prevents the attacks described above by avoiding returning
the access token in the redirect URI at all.
When PKCE is used, if an authorization code is stolen in transport, When PKCE is used, if an authorization code is stolen in transport,
the attacker is unable to do anything with the authorization code. the attacker is unable to do anything with the authorization code.
9.8.6. Disadvantages of the Implicit Flow 9.8.3. Disadvantages of the Implicit Flow
There are several additional reasons the Implicit flow is There are several additional reasons the Implicit flow is
disadvantageous compared to using the standard Authorization Code disadvantageous compared to using the standard Authorization Code
flow. flow.
o OAuth 2.0 provides no mechanism for a client to verify that an o OAuth 2.0 provides no mechanism for a client to verify that an
access token was issued to it, which could lead to misuse and access token was issued to it, which could lead to misuse and
possible impersonation attacks if a malicious party hands off an possible impersonation attacks if a malicious party hands off an
access token it retrieved through some other means to the client. access token it retrieved through some other means to the client.
skipping to change at page 15, line 33 skipping to change at page 16, line 31
(response_type=id_token) requires the client validate the JWT (response_type=id_token) requires the client validate the JWT
signature, as malicious parties could otherwise craft and supply signature, as malicious parties could otherwise craft and supply
fraudulent id_tokens. Performing OpenID Connect using the fraudulent id_tokens. Performing OpenID Connect using the
authorization code flow provides the benefit of the client not authorization code flow provides the benefit of the client not
needing to verify the JWT signature, as the ID token will have been needing to verify the JWT signature, as the ID token will have been
fetched over an HTTPS connection directly from the authorization fetched over an HTTPS connection directly from the authorization
server. Additionally, in many cases an application will request both server. Additionally, in many cases an application will request both
an ID token and an access token, so it is simplier and provides fewer an ID token and an access token, so it is simplier and provides fewer
attack vectors to obtain both via the authorization code flow. attack vectors to obtain both via the authorization code flow.
9.8.7. Historic Note 9.8.4. Historic Note
Historically, the Implicit flow provided an advantage to single-page Historically, the Implicit flow provided an advantage to single-page
apps since JavaScript could always arbitrarily read and manipulate apps since JavaScript could always arbitrarily read and manipulate
the fragment portion of the URL without triggering a page reload. the fragment portion of the URL without triggering a page reload.
This was necessary in order to remove the access token from the URL This was necessary in order to remove the access token from the URL
after it was obtained by the app. after it was obtained by the app.
Modern browsers now have the Session History API (described in Modern browsers now have the Session History API (described in
"Session history and navigation" of [HTML]), which provides a "Session history and navigation" of [HTML]), which provides a
mechanism to modify the path and query string component of the URL mechanism to modify the path and query string component of the URL
skipping to change at page 16, line 20 skipping to change at page 17, line 15
OAuth 2.0 Browser-Based application. OAuth 2.0 Browser-Based application.
10. IANA Considerations 10. IANA Considerations
This document does not require any IANA actions. This document does not require any IANA actions.
11. References 11. References
11.1. Normative References 11.1. Normative References
[CSP2] West, M., Barth, A., and D. Veditz, "Content Security [CSP2] West, M., "Content Security Policy", October 2018.
Policy", December 2016.
[Fetch] whatwg, "Fetch", 2018. [Fetch] whatwg, "Fetch", 2018.
[oauth-security-topics] [oauth-security-topics]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"OAuth 2.0 Security Best Current Practice", July 2019. "OAuth 2.0 Security Best Current Practice", July 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>.
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013, DOI 10.17487/RFC6819, January 2013,
<https://www.rfc-editor.org/info/rfc6819>. <https://www.rfc-editor.org/info/rfc6819>.
[RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key
for Code Exchange by OAuth Public Clients", RFC 7636, for Code Exchange by OAuth Public Clients", RFC 7636,
DOI 10.17487/RFC7636, September 2015, DOI 10.17487/RFC7636, September 2015,
<https://www.rfc-editor.org/info/rfc7636>. <https://www.rfc-editor.org/info/rfc7636>.
[RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
<https://www.rfc-editor.org/info/rfc8252>. <https://www.rfc-editor.org/info/rfc8252>.
11.2. Informative References 11.2. Informative References
[HTML] whatwg, "HTML", 2018. [HTML] whatwg, "HTML", 2020.
Appendix A. Server Support Checklist Appendix A. Server Support Checklist
OAuth authorization servers that support browser-based apps MUST: OAuth authorization servers that support browser-based apps MUST:
1. Require "https" scheme redirect URIs. 1. Require "https" scheme redirect URIs.
2. Require exact matching of registered redirect URIs. 2. Require exact matching of registered redirect URIs.
3. Support PKCE [RFC7636]. Required to protect authorization code 3. Support PKCE [RFC7636]. Required to protect authorization code
skipping to change at page 17, line 38 skipping to change at page 18, line 38
clients. clients.
7. Follow the [oauth-security-topics] recommendations on refresh 7. Follow the [oauth-security-topics] recommendations on refresh
tokens, as well as the additional requirements described in tokens, as well as the additional requirements described in
Section 8. Section 8.
Appendix B. Document History Appendix B. Document History
[[ To be removed from the final specification ]] [[ To be removed from the final specification ]]
-05
o Incorporated editorial and substantive feedback from Mike Jones
o Added references to "nonce" as another way to prevent CSRF attacks
o Updated headers in the Implicit Flow section to better represent
the relationship between the paragraphs
-04 -04
o Disallow the use of the Password Grant o Disallow the use of the Password Grant
o Add PKCE support to summary list for authorization server o Add PKCE support to summary list for authorization server
requirements requirements
o Rewrote refresh token section to allow refresh tokens if they are o Rewrote refresh token section to allow refresh tokens if they are
time-limited, rotated on each use, and requiring that the rotated time-limited, rotated on each use, and requiring that the rotated
refresh token lifetimes do not extend past the lifetime of the refresh token lifetimes do not extend past the lifetime of the
skipping to change at page 19, line 41 skipping to change at page 20, line 49
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:
Annabelle Backman, Brian Campbell, Brock Allen, Christian Mainka, Annabelle Backman, Brian Campbell, Brock Allen, Christian Mainka,
Daniel Fett, George Fletcher, Hannes Tschofenig, Janak Amarasena, Daniel Fett, George Fletcher, Hannes Tschofenig, Janak Amarasena,
John Bradley, Joseph Heenan, Justin Richer, Karl McGuinness, Leo John Bradley, Joseph Heenan, Justin Richer, Karl McGuinness, Leo
Tohill, Tomek Stojecki, Torsten Lodderstedt, and Vittorio Bertocci. Tohill, Mike Jones, Tomek Stojecki, Torsten Lodderstedt, and Vittorio
Bertocci.
Authors' Addresses Authors' Addresses
Aaron Parecki Aaron Parecki
Okta Okta
Email: aaron@parecki.com Email: aaron@parecki.com
URI: https://aaronparecki.com URI: https://aaronparecki.com
David Waite David Waite
Ping Identity Ping Identity
Email: david@alkaline-solutions.com Email: david@alkaline-solutions.com
 End of changes. 53 change blocks. 
157 lines changed or deleted 195 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/