OAuth 2.0 for Browser-Based Apps

Internet-Draft	OAuth 2.0 for Browser-Based Apps	March 2022
Parecki & Waite	Expires 8 September 2022	[Page]

Abstract

This specification details the security considerations and best practices that must be taken into account when developing browser-based applications that use OAuth 2.0.¶

At the time that OAuth 2.0 [RFC6749] and [RFC6750] were created, browser-based JavaScript applications needed a solution that strictly complied with the same-origin policy. Common deployments of OAuth 2.0 involved an application running on a different domain than the authorization server, so it was historically not possible to use the Authorization Code flow which would require a cross-origin POST request. This was one of the motivations for the definition of the Implicit flow, which returns the access token in the front channel 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 involving vulnerabilities associated with the exposure of the access 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 attacks and security considerations can be found in [oauth-security-topics].¶

In recent years, widespread adoption of Cross-Origin Resource Sharing (CORS), which enables exceptions to the same-origin policy, allows 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 token at the token endpoint. In this flow, the access token is never exposed in the less secure front channel. Furthermore, adding PKCE to the flow ensures that even if an authorization code is intercepted, it is unusable by an attacker.¶

For this reason, and from other lessons learned, the current best practice for browser-based applications is to use the OAuth 2.0 Authorization Code flow with PKCE.¶

Browser-based applications:¶

MUST use the OAuth 2.0 Authorization Code flow with the PKCE extension when obtaining an access token¶
MUST Protect themselves against CSRF attacks by either:¶
- ensuring the authorization server supports PKCE, or¶
- by using the OAuth 2.0 "state" parameter or the OpenID Connect "nonce" parameter to carry one-time use CSRF tokens¶
MUST Register one or more redirect URIs, and use only exact registered redirect URIs in authorization requests¶

OAuth 2.0 authorization servers supporting browser-based applications:¶

MUST Require exact matching of registered redirect URIs¶
MUST Support the PKCE extension¶
MUST NOT issue access tokens in the authorization response¶
If issuing refresh tokens to browser-based applications, then:¶
- MUST rotate refresh tokens on each use or use sender-constrained refresh tokens, and¶
- MUST set a maximum lifetime on refresh tokens or expire if they are not used in some amount of time¶

6. Application Architecture Patterns

There are three primary architectural patterns available when building browser-based applications.¶

a JavaScript application that has methods of sharing data with resource servers, such as using common-domain cookies¶
a JavaScript application with a backend component¶
a JavaScript application with no backend, accessing resource servers directly¶

These three architectures have different use cases and considerations.¶

6.2. JavaScript Applications with a Backend

+-------------+  +--------------+ +---------------+
|             |  |              | |               |
|Authorization|  |    Token     | |   Resource    |
|  Endpoint   |  |   Endpoint   | |    Server     |
|             |  |              | |               |
+-------------+  +--------------+ +---------------+

       ^                ^                   ^
       |             (D)|                (G)|
       |                v                   v
       |
       |         +--------------------------------+
       |         |                                |
       |         |          Application           |
    (B)|         |            Server              |
       |         |                                |
       |         +--------------------------------+
       |
       |           ^     ^     +          ^    +
       |        (A)|  (C)|  (E)|       (F)|    |(H)
       v           v     +     v          +    v

+-------------------------------------------------+
|                                                 |
|                   Browser                       |
|                                                 |
+-------------------------------------------------+

In this architecture, commonly referred to as "backend for frontend" or "BFF", the JavaScript code is loaded from a dynamic Application Server (A) that also has the ability to execute code itself. This enables the ability to keep all of the steps involved in obtaining an access token outside of the JavaScript application.¶

Note that this application backend is not the Resource Server, it is still considered part of the OAuth client and would be accessing data at a separate resource server.¶

In this case, the Application Server initiates the OAuth flow itself, by redirecting the browser to the authorization endpoint (B). When the user is redirected back, the browser delivers the authorization code to the application server (C), where it can then exchange it for an access token at the token endpoint (D) using its client secret. The application server then keeps the access token and refresh token stored internally, and creates a separate session with the browser-based app via a traditional browser cookie (E).¶

When the JavaScript application in the browser wants to make a request to the Resource Server, it instead makes the request to the Application Server (F), and the Application Server will make the request with the access token to the Resource Server (G), and forward the response (H) back to the browser.¶

(Common examples of this architecture are an Angular front-end with a .NET backend, or a React front-end with a Spring Boot backend.)¶

The Application Server SHOULD be considered a confidential client, and issued its own client secret. The Application Server SHOULD use the OAuth 2.0 Authorization Code grant with PKCE to initiate a request for an access token. Detailed recommendations for confidential clients can be found in [oauth-security-topics] Section 2.1.1.¶

In this scenario, the connection between the browser and Application Server SHOULD be a session cookie provided by the Application Server.¶

Security of the connection between code running in the browser and this Application Server is assumed to utilize browser-level protection mechanisms. Details are out of scope of this document, but many recommendations can be found in the OWASP Cheat Sheet series (https://cheatsheetseries.owasp.org/), such as setting an HTTP-only and Secure cookie to authenticate the session between the browser and Application Server.¶

6.3. JavaScript Applications without a Backend

                      +---------------+           +--------------+
                      |               |           |              |
                      | Authorization |           |   Resource   |
                      |    Server     |           |    Server    |
                      |               |           |              |
                      +---------------+           +--------------+

                             ^     ^                 ^     +
                             |     |                 |     |
                             |(B)  |(C)              |(D)  |(E)
                             |     |                 |     |
                             |     |                 |     |
                             +     v                 +     v

+-----------------+         +-------------------------------+
|                 |   (A)   |                               |
| Static Web Host | +-----> |           Browser             |
|                 |         |                               |
+-----------------+         +-------------------------------+

In this architecture, the JavaScript code is first loaded from a static web host into the browser (A), and the application then runs in the browser. This application is considered a public client, 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 initiates the Authorization Code flow with the PKCE extension (described in Section 7) (B) above, and obtains an access token via a POST request (C). The JavaScript application is then responsible for storing the access token (and optional refresh token) as securely as possible using appropriate browser APIs. As of the date of this publication there is no browser API that allows to store tokens in a completely secure way.¶

When the JavaScript application in the browser wants to make a request to the Resource Server, it can interact with the Resource Server directly. It includes the access token in the request (D) and receives the Resource Server's response (E).¶

In this scenario, the Authorization Server and Resource Server MUST support the necessary CORS headers to enable the JavaScript code to make this POST request from the domain on which the script is executing. (See Section 9.6 for additional details.)¶

8. Refresh Tokens

Refresh tokens provide a way for applications to obtain a new access token when the initial access token expires. With public clients, the risk of a leaked refresh token is greater than leaked access tokens, since an attacker may be able to continue using the stolen refresh token to obtain new access tokens potentially without being detectable by the authorization server.¶

Browser-based applications provide an attacker with several opportunities by which a refresh token can be leaked, just as with access tokens. As such, these applications are considered a higher risk for handling refresh tokens.¶

Authorization servers may choose whether or not to issue refresh tokens to browser-based applications. [oauth-security-topics] describes some additional requirements around refresh tokens on top of the recommendations of [RFC6749]. Applications and authorization 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 applications.¶

In particular, authorization servers:¶

MUST either rotate refresh tokens on each use OR use sender-constrained refresh tokens as described in [oauth-security-topics] Section 4.13.2¶
MUST either set a maximum lifetime on refresh tokens OR expire if the refresh token has not been used within some amount of time¶
MUST NOT extend the lifetime of the new refresh token beyond the lifetime of the initial refresh token¶
upon issuing a rotated refresh token, MUST NOT extend the lifetime of the new refresh token beyond the lifetime of the initial refresh token if the refresh token has a preestablished expiration time¶

For example:¶

A user authorizes an application, issuing an access token that lasts 1 hour, and a refresh token that lasts 24 hours¶
After 1 hour, the initial access token expires, so the application uses the refresh token to get a new access token¶
The authorization server returns a new access token that lasts 1 hour, and a new refresh token that lasts 23 hours¶
This continues until 24 hours pass from the initial authorization¶
At this point, when the application attempts to use the refresh token after 24 hours, the request will fail and the application will have to involve the user in a new authorization request¶

By limiting the overall refresh token lifetime to the lifetime of the initial refresh token, this ensures a stolen refresh token cannot be used indefinitely.¶

Authorization servers MAY set different policies around refresh token issuance, lifetime and expiration for browser-based applications compared to other public clients.¶

9. Security Considerations

9.1. Registration of Browser-Based Apps

Browser-based applications are considered public clients as defined by Section 2.1 of OAuth 2.0 [RFC6749], and MUST be registered with the authorization server as such. Authorization servers MUST record the client type in the client registration details in order to identify and process requests accordingly.¶

Authorization servers MUST require that browser-based applications register one or more redirect URIs.¶

9.2. Client Authentication

Since a browser-based application's source code is delivered to the end-user's browser, it cannot contain provisioned secrets. As such, a browser-based app with native OAuth support is considered a public client as defined by Section 2.1 of OAuth 2.0 [RFC6749].¶

Secrets that are statically included as part of an app distributed to multiple users should not be treated as confidential secrets, as one user may inspect their copy and learn the shared secret. For this reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT RECOMMENDED for authorization servers to require client authentication of browser-based applications using a shared secret, as this serves little value beyond client identification which is already provided by the client_id request parameter.¶

Authorization servers that still require a statically included shared 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 additional measures, such clients are subject to client impersonation (see Section 9.3 below).¶

9.3. Client Impersonation

As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization server SHOULD NOT process authorization requests automatically without user consent or interaction, except when the identity of the client can be assured.¶

If authorization servers restrict redirect URIs to a fixed set of absolute HTTPS URIs, preventing the use of wildcard domains, wildcard paths, or wildcard query string components, this exact match of registered absolute HTTPS URIs MAY be accepted by authorization servers as proof of identity of the client for the purpose of deciding whether to automatically process an authorization request when a previous request for the client_id has already been approved.¶

9.4. Cross-Site Request Forgery Protections

Clients MUST prevent Cross-Site Request Forgery (CSRF) attacks against their redirect URI. Clients can accomplish this by either ensuring the authorization server supports PKCE and relying on the CSRF protection that PKCE provides, or if the client is also an OpenID Connect client, using the OpenID Connect "nonce" parameter, or 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

Authorization server mix-up attacks mark a severe threat to every client that supports at least two authorization servers. To conform to this BCP such clients MUST apply countermeasures to defend against mix-up attacks.¶

It is RECOMMENDED to defend against mix-up attacks by identifying and validating the issuer of the authorization response. This can be achieved either by using the "iss" response parameter, as defined in [oauth-iss-auth-resp], or by using the "iss" Claim of the ID token when OpenID Connect is used.¶

Alternative countermeasures, such as using distinct redirect URIs for each issuer, SHOULD only be used if identifying the issuer as described is not possible.¶

Section 4.4 of [oauth-security-topics] provides additional details about mix-up attacks and the countermeasures mentioned above.¶

9.6. Cross-Domain Requests

To complete the Authorization Code flow, the browser-based application will need to exchange the authorization code for an access token at the token endpoint. If the authorization server provides additional endpoints to the application, such as metadata URLs, dynamic client registration, revocation, introspection, discovery or user info endpoints, these endpoints may also be accessed by the browser-based app. Since these requests will be made from a browser, authorization servers MUST support the necessary CORS headers (defined in [Fetch]) to allow the browser to make the request.¶

This specification does not include guidelines for deciding whether a CORS policy for the token endpoint should be a wildcard origin or more restrictive. Note, however, that the browser will attempt to GET or POST to the API endpoint before knowing any CORS policy; it simply hides the succeeding or failing result from JavaScript if the policy does not allow sharing.¶

9.7. Content Security Policy

A browser-based application that wishes to use either long-lived refresh tokens or privileged scopes SHOULD restrict its JavaScript execution to a set of statically hosted scripts via a Content Security Policy ([CSP2]) or similar mechanism. A strong Content Security Policy can limit the potential attack vectors for malicious JavaScript to be executed on the page.¶

9.8. OAuth Implicit Flow

The OAuth 2.0 Implicit flow (defined in Section 4.2 of OAuth 2.0 [RFC6749]) works by the authorization server issuing an access token in the authorization response (front channel) without the code exchange step. In this case, the access token is returned in the fragment part of the redirect URI, providing an attacker with several opportunities to intercept and steal the access token.¶

Authorization servers MUST NOT issue access tokens in the authorization response, and MUST issue access tokens only from the token endpoint.¶

9.8.1. Attacks on the Implicit Flow

Many attacks on the Implicit flow described by [RFC6819] and Section 4.1.2 of [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: Manipulation of the Redirect URI

If an attacker is able to cause the authorization response to be sent to a URI under their control, they will directly get access to the authorization response including the access token. Several methods of performing this attack are described in detail in [oauth-security-topics].¶

9.8.1.2. Threat: Access Token Leak in Browser History

An attacker could obtain the access token from the browser's history. The countermeasures recommended by [RFC6819] are limited to using short expiration times for tokens, and indicating that browsers should not cache the response. Neither of these fully prevent this attack, they only reduce the potential damage.¶

Additionally, many browsers now also sync browser history to cloud services and to multiple devices, providing an even wider attack surface to extract access tokens out of the URL.¶

This is discussed in more detail in Section 4.3.2 of [oauth-security-topics].¶

9.8.1.3. Threat: Manipulation of Scripts

An attacker could modify the page or inject scripts into the browser through various means, including when the browser's HTTPS connection is being intercepted by, for example, a corporate network. While man-in-the-middle attacks are typically out of scope of basic security recommendations to prevent, in the case of browser-based apps they are much easier to perform. An injected script can enable an attacker to have access to everything on the page.¶

The risk of a malicious script running on the page may be amplified when the application uses a known standard way of obtaining access tokens, namely that the attacker can always look at the window.location variable to find an access token. This threat profile is different from an attacker specifically targeting an individual application by knowing where or how an access token obtained via the Authorization Code flow may end up being stored.¶

9.8.1.4. Threat: Access Token Leak to Third-Party Scripts

It is relatively common to use third-party scripts in browser-based apps, such as analytics tools, crash reporting, and even things like 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 code running in the application. When an access token is returned in the fragment, it is visible to any third-party scripts on the page.¶

9.8.2. Countermeasures

In addition to the countermeasures described by [RFC6819] and [oauth-security-topics], using the Authorization Code flow with PKCE extension prevents the attacks described above by avoiding returning the access token in the redirect response at all.¶

When PKCE is used, if an authorization code is stolen in transport, the attacker is unable to do anything with the authorization code.¶

9.8.3. Disadvantages of the Implicit Flow

There are several additional reasons the Implicit flow is disadvantageous compared to using the standard Authorization Code flow.¶

OAuth 2.0 provides no mechanism for a client to verify that a particular access token was intended for that client, which could lead to misuse and possible impersonation attacks if a malicious party hands off an access token it retrieved through some other means to the client.¶
Returning an access token in the front-channel redirect gives the authorization server no assurance that the access token will actually end up at the application, since there are many ways this redirect may fail or be intercepted.¶
Supporting the Implicit flow requires additional code, more upkeep and understanding of the related security considerations, while limiting the authorization server to just the Authorization Code flow reduces the attack surface of the implementation.¶
If the JavaScript application gets wrapped into a native app, then [RFC8252] also requires the use of the Authorization Code flow with PKCE anyway.¶

In OpenID Connect, the ID Token is sent in a known format (as a JWT), and digitally signed. Returning an ID token using the Implicit flow (response_type=id_token) requires the client validate the JWT signature, as malicious parties could otherwise craft and supply fraudulent ID tokens. Performing OpenID Connect using the Authorization Code flow provides the benefit of the client not needing to verify the JWT signature, as the ID token will have been fetched over an HTTPS connection directly from the authorization server. Additionally, in many cases an application will request both an ID token and an access token, so it is simplier and provides fewer attack vectors to obtain both via the Authorization Code flow.¶

9.8.4. Historic Note

Historically, the Implicit flow provided an advantage to browser-based apps since JavaScript could always arbitrarily read and manipulate the fragment portion of the URL without triggering a page reload. This was necessary in order to remove the access token from the URL after it was obtained by the app.¶

Modern browsers now have the Session History API (described in "Session history and navigation" of [HTML]), which provides a mechanism to modify the path and query string component of the URL without triggering a page reload. This means modern browser-based apps can use the unmodified OAuth 2.0 Authorization Code flow, since they have the ability to remove the authorization code from the query string without triggering a page reload thanks to the Session History API.¶

9.9. Additional Security Considerations

The OWASP Foundation (https://www.owasp.org/) maintains a set of security recommendations and best practices for web applications, and it is RECOMMENDED to follow these best practices when creating an OAuth 2.0 Browser-Based application.¶

Appendix B. Document History

[[ To be removed from the final specification ]]¶

-09¶

Provide additional context for the same-domain architecture pattern¶
Added reference to draft-ietf-httpbis-rfc6265bis to clarify that SameSite is not the only CSRF protection measure needed¶
Editorial improvements¶

-08¶

Added a note to use the "Secure" cookie attribute in addition to SameSite etc¶
Updates to bring this draft in sync with the latest Security BCP¶
Updated text for mix-up countermeasures to reference the new "iss" extension¶
Changed "SHOULD" for refresh token rotation to MUST either use rotation or sender-constraining to match the Security BCP¶
Fixed references to other specs and extensions¶
Editorial improvements in descriptions of the different architectures¶

-07¶

Clarify PKCE requirements apply only to issuing access tokens¶
Change "MUST" to "SHOULD" for refresh token rotation¶
Editorial clarifications¶

-06¶

Added refresh token requirements to AS summary¶
Editorial clarifications¶

-05¶

Incorporated editorial and substantive feedback from Mike Jones¶
Added references to "nonce" as another way to prevent CSRF attacks¶
Updated headers in the Implicit Flow section to better represent the relationship between the paragraphs¶

-04¶

Disallow the use of the Password Grant¶
Add PKCE support to summary list for authorization server requirements¶
Rewrote refresh token section to allow refresh tokens if they are time-limited, rotated on each use, and requiring that the rotated refresh token lifetimes do not extend past the lifetime of the initial refresh token, and to bring it in line with the Security BCP¶
Updated recommendations on using state to reflect the Security BCP¶
Updated server support checklist to reflect latest changes¶
Updated the same-domain JS architecture section to emphasize the architecture rather than domain¶
Editorial clarifications in the section that talks about OpenID Connect ID tokens¶

-03¶

Updated the historic note about the fragment URL clarifying that the Session History API means browsers can use the unmodified authorization code flow¶
Rephrased "Authorization Code Flow" intro paragraph to better lead into the next two sections¶
Softened "is likely a better decision to avoid using OAuth entirely" to "it may be..." for common-domain deployments¶
Updated abstract to not be limited to public clients, since the later sections talk about confidential clients¶
Removed references to avoiding OpenID Connect for same-domain architectures¶
Updated headers to better describe architectures (Apps Served from a Static Web Server -> JavaScript Applications without a Backend)¶
Expanded "same-domain architecture" section to better explain the problems that OAuth has in this scenario¶
Referenced Security BCP in implicit flow attacks where possible¶
Minor typo corrections¶

-02¶

Rewrote overview section incorporating feedback from Leo Tohill¶
Updated summary recommendation bullet points to split out application and server requirements¶
Removed the allowance on hostname-only redirect URI matching, now requiring exact redirect URI matching¶
Updated Section 6.2 to drop reference of SPA with a backend component being a public client¶
Expanded the architecture section to explicitly mention three architectural patterns available to JS apps¶

-01¶

Incorporated feedback from Torsten Lodderstedt¶
Updated abstract¶
Clarified the definition of browser-based apps to not exclude applications cached in the browser, e.g. via Service Workers¶
Clarified use of the state parameter for CSRF protection¶
Added background information about the original reason the implicit flow was created due to lack of CORS support¶
Clarified the same-domain use case where the SPA and API share a cookie domain¶
Moved historic note about the fragment URL into the Overview¶