idnits 2.17.1 draft-ietf-oauth-browser-based-apps-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 02, 2020) is 1301 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'CSP2' -- Possible downref: Non-RFC (?) normative reference: ref. 'Fetch' ** Downref: Normative reference to an Informational RFC: RFC 6819 Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Open Authentication Protocol A. Parecki 3 Internet-Draft Okta 4 Intended status: Best Current Practice D. Waite 5 Expires: April 5, 2021 Ping Identity 6 October 02, 2020 8 OAuth 2.0 for Browser-Based Apps 9 draft-ietf-oauth-browser-based-apps-07 11 Abstract 13 This specification details the security considerations and best 14 practices that must be taken into account when developing browser- 15 based applications that use OAuth 2.0. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on April 5, 2021. 34 Copyright Notice 36 Copyright (c) 2020 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 53 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 5. First-Party Applications . . . . . . . . . . . . . . . . . . 5 56 6. Application Architecture Patterns . . . . . . . . . . . . . . 5 57 6.1. Browser-Based Apps that Can Share Data with the Resource 58 Server . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 6.2. JavaScript Applications with a Backend . . . . . . . . . 6 60 6.3. JavaScript Applications without a Backend . . . . . . . . 8 61 7. Authorization Code Flow . . . . . . . . . . . . . . . . . . . 9 62 7.1. Initiating the Authorization Request from a Browser-Based 63 Application . . . . . . . . . . . . . . . . . . . . . . . 9 64 7.2. Handling the Authorization Code Redirect . . . . . . . . 10 65 8. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . . . 10 66 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 67 9.1. Registration of Browser-Based Apps . . . . . . . . . . . 11 68 9.2. Client Authentication . . . . . . . . . . . . . . . . . . 11 69 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 12 70 9.4. Cross-Site Request Forgery Protections . . . . . . . . . 12 71 9.5. Authorization Server Mix-Up Mitigation . . . . . . . . . 12 72 9.6. Cross-Domain Requests . . . . . . . . . . . . . . . . . . 13 73 9.7. Content-Security Policy . . . . . . . . . . . . . . . . . 13 74 9.8. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 13 75 9.8.1. Attacks on the Implicit Flow . . . . . . . . . . . . 13 76 9.8.2. Countermeasures . . . . . . . . . . . . . . . . . . . 15 77 9.8.3. Disadvantages of the Implicit Flow . . . . . . . . . 15 78 9.8.4. Historic Note . . . . . . . . . . . . . . . . . . . . 16 79 9.9. Additional Security Considerations . . . . . . . . . . . 16 80 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 81 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 82 11.1. Normative References . . . . . . . . . . . . . . . . . . 16 83 11.2. Informative References . . . . . . . . . . . . . . . . . 17 84 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 17 85 Appendix B. Document History . . . . . . . . . . . . . . . . . . 18 86 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 20 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 89 1. Introduction 91 This specification describes the current best practices for 92 implementing OAuth 2.0 authorization flows in applications executing 93 in a browser. 95 For native application developers using OAuth 2.0 and OpenID Connect, 96 an IETF BCP (best current practice) was published that guides 97 integration of these technologies. This document is formally known 98 as [RFC8252] or BCP 212, but nicknamed "AppAuth" after the OpenID 99 Foundation-sponsored set of libraries that assist developers in 100 adopting these practices. [RFC8252] makes specific recommendations 101 for how to securely implement OAuth in native applications, including 102 incorporating additional OAuth extensions where needed. 104 OAuth 2.0 for Browser-Based Apps addresses the similarities between 105 implementing OAuth for native apps and browser-based apps, and 106 includes additional considerations when running in a browser. This 107 is primarily focused on OAuth, except where OpenID Connect provides 108 additional considerations. 110 2. Notational Conventions 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in 115 [RFC2119]. 117 3. Terminology 119 In addition to the terms defined in referenced specifications, this 120 document uses the following terms: 122 "OAuth": In this document, "OAuth" refers to OAuth 2.0, [RFC6749] 123 and [RFC6750]. 125 "Browser-based application": An application that is dynamically 126 downloaded and executed in a web browser, usually written in 127 JavaScript. Also sometimes referred to as a "single-page 128 application", or "SPA". 130 4. Overview 132 At the time that OAuth 2.0 [RFC6749] and [RFC6750] were created, 133 browser-based JavaScript applications needed a solution that strictly 134 complied with the same-origin policy. Common deployments of OAuth 135 2.0 involved an application running on a different domain than the 136 authorization server, so it was historically not possible to use the 137 authorization code flow which would require a cross-origin POST 138 request. This was one of the motivations for the definition of the 139 implicit flow, which returns the access token in the front channel 140 via the fragment part of the URL, bypassing the need for a cross- 141 origin POST request. 143 However, there are several drawbacks to the implicit flow, generally 144 involving vulnerabilities associated with the exposure of the access 145 token in the URL. See Section 9.8 for an analysis of these attacks 146 and the drawbacks of using the implicit flow in browsers. Additional 147 attacks and security considerations can be found in 148 [oauth-security-topics]. 150 In recent years, widespread adoption of Cross-Origin Resource Sharing 151 (CORS), which enables exceptions to the same-origin policy, allows 152 browser-based apps to use the OAuth 2.0 authorization code flow and 153 make a POST request to exchange the authorization code for an access 154 token at the token endpoint. In this flow, the access token is never 155 exposed in the less secure front-channel. Furthermore, adding PKCE 156 to the flow ensures that even if an authorization code is 157 intercepted, it is unusable by an attacker. 159 For this reason, and from other lessons learned, the current best 160 practice for browser-based applications is to use the OAuth 2.0 161 authorization code flow with PKCE. 163 Browser-based applications: 165 o MUST use the OAuth 2.0 authorization code flow with the PKCE 166 extension when obtaining an access token 168 o MUST Protect themselves against CSRF attacks by either: 170 * ensuring the authorization server supports PKCE, or 172 * by using the OAuth 2.0 "state" parameter or the OpenID Connect 173 "nonce" parameter to carry one-time use CSRF tokens 175 o MUST Register one or more redirect URIs, and use only exact 176 registered redirect URIs in authorization requests 178 OAuth 2.0 authorization servers: 180 o MUST Require exact matching of registered redirect URIs 182 o MUST Support the PKCE extension 184 o MUST NOT issue access tokens in the authorization response 186 o If issuing refresh tokens to browser-based apps, then: 188 * SHOULD rotate refresh tokens on each use, and 190 * MUST set a maximum lifetime on refresh tokens or expire if they 191 are not used in some amount of time 193 5. First-Party Applications 195 While OAuth was initially created to allow third-party applications 196 to access an API on behalf of a user, it has proven to be useful in a 197 first-party scenario as well. First-party apps are applications 198 where the same organization provides both the API and the 199 application. 201 Examples of first-party applications are a web email client provided 202 by the operator of the email account, or a mobile banking application 203 created by bank itself. (Note that there is no requirement that the 204 application actually be developed by the same company; a mobile 205 banking application developed by a contractor that is branded as the 206 bank's application is still considered a first-party application.) 207 The first-party app consideration is about the user's relationship to 208 the application and the service. 210 To conform to this best practice, first-party applications using 211 OAuth or OpenID Connect MUST use a redirect-based flow (such as the 212 OAuth Authorization Code flow) as described later in this document. 214 The Resource Owner Password Grant MUST NOT be used, as described in 215 [oauth-security-topics] section 3.4. Instead, by using the 216 Authorization Code flow and redirecting the user to the authorization 217 server, this provides the authorization server the opportunity to 218 prompt the user for multi-factor authentication options, take 219 advantage of single-sign-on sessions, or use third-party identity 220 providers. In contrast, the Password grant does not provide any 221 built-in mechanism for these, and would instead be extended with 222 custom code. 224 6. Application Architecture Patterns 226 There are three primary architectural patterns available when 227 building browser-based applications. 229 o a JavaScript application that has methods of sharing data with 230 resource servers, such as using common-domain cookies 232 o a JavaScript application with a backend 234 o a JavaScript application with no backend, accessing resource 235 servers directly 237 These three architectures have different use cases and 238 considerations. 240 6.1. Browser-Based Apps that Can Share Data with the Resource Server 242 For simple system architectures, such as when the JavaScript 243 application is served from a domain that can share cookies with the 244 domain of the API (resource server), OAuth adds additional attack 245 vectors that could be avoided with a different solution. 247 In particular, using any redirect-based mechanism of obtaining an 248 access token enables the redirect-based attacks described in 249 [oauth-security-topics], but if the application, authorization server 250 and resource server share a domain, then it is unnecessary to use a 251 redirect mechanism to communicate between them. 253 An additional concern with handling access tokens in a browser is 254 that as of the date of this publication, there is no secure storage 255 mechanism where JavaScript code can keep the access token to be later 256 used in an API request. Using an OAuth flow results in the 257 JavaScript code getting an access token, needing to store it 258 somewhere, and then retrieve it to make an API request. 260 Instead, a more secure design is to use an HTTP-only cookie between 261 the JavaScript application and API so that the JavaScript code can't 262 access the cookie value itself. Additionally, the SameSite cookie 263 attribute can be used to prevent CSRF attacks, or alternatively, the 264 application and API could be written to use anti-CSRF tokens. 266 OAuth was originally created for third-party or federated access to 267 APIs, so it may not be the best solution in a common-domain 268 deployment. That said, using OAuth even in a common-domain 269 architecture does mean you can more easily rearchitect things later, 270 such as if you were to later add a new domain to the system. 272 6.2. JavaScript Applications with a Backend 273 +-------------+ +--------------+ +---------------+ 274 | | | | | | 275 |Authorization| | Token | | Resource | 276 | Endpoint | | Endpoint | | Server | 277 | | | | | | 278 +-------------+ +--------------+ +---------------+ 280 ^ ^ ^ 281 | (D)| (G)| 282 | v v 283 | 284 | +--------------------------------+ 285 | | | 286 | | Application | 287 (B)| | Server | 288 | | | 289 | +--------------------------------+ 290 | 291 | ^ ^ + ^ + 292 | (A)| (C)| (E)| (F)| |(H) 293 v v + v + v 295 +-------------------------------------------------+ 296 | | 297 | Browser | 298 | | 299 +-------------------------------------------------+ 301 In this architecture, the JavaScript code is loaded from a dynamic 302 Application Server (A) that also has the ability to execute code 303 itself. This enables the ability to keep all of the steps involved 304 in obtaining an access token outside of the JavaScript application. 306 In this case, the Application Server initiates the OAuth flow itself, 307 by redirecting the browser to the authorization endpoint (B). When 308 the user is redirected back, the browser delivers the authorization 309 code to the application server (C), where it can then exchange it for 310 an access token at the token endpoint (D) using its client secret. 311 The application server then keeps the access token and refresh token 312 stored internally, and creates a separate session with the browser- 313 based app via a traditional browser cookie (E). 315 When the JavaScript application in the browser wants to make a 316 request to the Resource Server, it instead makes the request to the 317 Application Server (F), and the Application Server will make the 318 request with the access token to the Resource Server (H), and forward 319 the response (H) back to the browser. 321 (Common examples of this architecture are an Angular front-end with a 322 .NET backend, or a React front-end with a Spring Boot backend.) 324 The Application Server SHOULD be considered a confidential client, 325 and issued its own client secret. The Application Server SHOULD use 326 the OAuth 2.0 Authorization Code grant with PKCE to initiate a 327 request for an access token. 329 Security of the connection between code running in the browser and 330 this Application Server is assumed to utilize browser-level 331 protection mechanisms. Details are out of scope of this document, 332 but many recommendations can be found in the OWASP Cheat Sheet series 333 (https://cheatsheetseries.owasp.org/), such as setting an HTTP-only 334 and Secure cookie to authenticate the session between the browser and 335 Application Server. 337 In this scenario, the session between the browser and Application 338 Server SHOULD be a session cookie provided by the Application Server. 340 6.3. JavaScript Applications without a Backend 342 +---------------+ +--------------+ 343 | | | | 344 | Authorization | | Resource | 345 | Server | | Server | 346 | | | | 347 +---------------+ +--------------+ 349 ^ + ^ + 350 | | | | 351 |(B) |(C) |(D) |(E) 352 | | | | 353 | | | | 354 + v + v 356 +-----------------+ +-------------------------------+ 357 | | (A) | | 358 | Static Web Host | +-----> | Browser | 359 | | | | 360 +-----------------+ +-------------------------------+ 362 In this architecture, the JavaScript code is first loaded from a 363 static web host into the browser (A), and the application then runs 364 in the browser. This application is considered a public client, 365 since there is no way to issue it a client secret and there is no 366 other secure client authentication mechanism available in the 367 browser. 369 The code in the browser initiates the authorization code flow with 370 the PKCE extension (described in Section 7) (B) above, and obtains an 371 access token via a POST request (C). The JavaScript app is then 372 responsible for storing the access token (and optional refresh token) 373 securely using appropriate browser APIs. 375 When the JavaScript application in the browser wants to make a 376 request to the Resource Server, it can include the access token in 377 the request (D) and make the request directly. 379 In this scenario, the Authorization Server and Resource Server MUST 380 support the necessary CORS headers to enable the JavaScript code to 381 make this POST request from the domain on which the script is 382 executing. (See Section 9.6 for additional details.) 384 7. Authorization Code Flow 386 Public browser-based apps that use the authorization code grant type 387 described in Section 4.1 of OAuth 2.0 [RFC6749] MUST also follow 388 these additional requirements described in this section. 390 7.1. Initiating the Authorization Request from a Browser-Based 391 Application 393 Public browser-based apps MUST implement the Proof Key for Code 394 Exchange (PKCE [RFC7636]) extension when obtaining an access token, 395 and authorization servers MUST support and enforce PKCE for such 396 clients. 398 The PKCE extension prevents an attack where the authorization code is 399 intercepted and exchanged for an access token by a malicious client, 400 by providing the authorization server with a way to verify the same 401 client instance that exchanges the authorization code is the same one 402 that initiated the flow. 404 Browser-based apps MUST prevent CSRF attacks against their redirect 405 URI. This can be accomplished by any of the below: 407 o using PKCE, and confirming that the authorization server supports 408 PKCE 410 o using a unique value for the OAuth 2.0 "state" parameter 412 o if the application is using OpenID Connect, by using the OpenID 413 Connect "nonce" parameter 415 Browser-based apps MUST follow the recommendations in 416 [oauth-security-topics] Section 2.1 to protect themselves during 417 redirect flows. 419 7.2. Handling the Authorization Code Redirect 421 Authorization servers MUST require an exact match of a registered 422 redirect URI. 424 8. Refresh Tokens 426 Refresh tokens provide a way for applications to obtain a new access 427 token when the initial access token expires. With public clients, 428 the risk of a leaked refresh token is greater than leaked access 429 tokens, since an attacker may be able to continue using the stolen 430 refresh token to obtain new access tokens potentially without being 431 detectable by the authorization server. 433 Browser-based applications provide an attacker with several 434 opportunities by which a refresh token can be leaked, just as with 435 access tokens. As such, these applications are considered a higher 436 risk for handling refresh tokens. 438 Authorization servers may choose whether or not to issue refresh 439 tokens to browser-based applications. [oauth-security-topics] 440 describes some additional requirements around refresh tokens on top 441 of the recommendations of [RFC6749]. Applications and authorization 442 servers conforming to this BCP MUST also follow the recommendations 443 in [oauth-security-topics] around refresh tokens if refresh tokens 444 are issued to browser-based apps. 446 In particular, authorization servers: 448 o SHOULD rotate refresh tokens on each use, in order to be able to 449 detect a stolen refresh token if one is replayed (described in 450 [oauth-security-topics] section 4.12) 452 o MUST either set a maximum lifetime on refresh tokens OR expire if 453 the refresh token has not been used within some amount of time 455 o upon issuing a rotated refresh token, MUST NOT extend the lifetime 456 of the new refresh token beyond the lifetime of the initial 457 refresh token if the refresh token has a preestablished expiration 458 time 460 For example: 462 o A user authorizes an application, issuing an access token that 463 lasts 1 hour, and a refresh token that lasts 24 hours 465 o After 1 hour, the initial access token expires, so the application 466 uses the refresh token to get a new access token 468 o The authorization server returns a new access token that lasts 1 469 hour, and a new refresh token that lasts 23 hours 471 o This continues until 24 hours pass from the initial authorization 473 o At this point, when the application attempts to use the refresh 474 token after 24 hours, the request will fail and the application 475 will have to involve the user in a new authorization request 477 By limiting the overall refresh token lifetime to the lifetime of the 478 initial refresh token, this ensures a stolen refresh token cannot be 479 used indefinitely. 481 Authorization servers MAY set different policies around refresh token 482 issuance, lifetime and expiration for browser-based apps compared to 483 other public clients. 485 9. Security Considerations 487 9.1. Registration of Browser-Based Apps 489 Browser-based applications are considered public clients as defined 490 by section 2.1 of OAuth 2.0 [RFC6749], and MUST be registered with 491 the authorization server as such. Authorization servers MUST record 492 the client type in the client registration details in order to 493 identify and process requests accordingly. 495 Authorization servers MUST require that browser-based applications 496 register one or more redirect URIs. 498 9.2. Client Authentication 500 Since a browser-based application's source code is delivered to the 501 end-user's browser, it cannot contain provisioned secrets. As such, 502 a browser-based app with native OAuth support is considered a public 503 client as defined by Section 2.1 of OAuth 2.0 [RFC6749]. 505 Secrets that are statically included as part of an app distributed to 506 multiple users should not be treated as confidential secrets, as one 507 user may inspect their copy and learn the shared secret. For this 508 reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT 509 RECOMMENDED for authorization servers to require client 510 authentication of browser-based applications using a shared secret, 511 as this serves little value beyond client identification which is 512 already provided by the client_id request parameter. 514 Authorization servers that still require a statically included shared 515 secret for SPA clients MUST treat the client as a public client, and 516 not accept the secret as proof of the client's identity. Without 517 additional measures, such clients are subject to client impersonation 518 (see Section 9.3 below). 520 9.3. Client Impersonation 522 As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization 523 server SHOULD NOT process authorization requests automatically 524 without user consent or interaction, except when the identity of the 525 client can be assured. 527 If authorization servers restrict redirect URIs to a fixed set of 528 absolute HTTPS URIs, preventing the use of wildcard domains, wildcard 529 paths, or wildcard query string components, this exact match of 530 registered absolute HTTPS URIs MAY be accepted by authorization 531 servers as proof of identity of the client for the purpose of 532 deciding whether to automatically process an authorization request 533 when a previous request for the client_id has already been approved. 535 9.4. Cross-Site Request Forgery Protections 537 Clients MUST prevent Cross-Site Request Forgery (CSRF) attacks 538 against their redirect URI. Clients can accomplish this by either 539 ensuring the authorization server supports PKCE and relying on the 540 CSRF protection that PKCE provides, or if the client is also an 541 OpenID Connect client, using the OpenID Connect "nonce" parameter, or 542 by using the "state" parameter to carry one-time-use CSRF tokens as 543 described in Section 7.1. 545 See Section 2.1 of [oauth-security-topics] for additional details. 547 9.5. Authorization Server Mix-Up Mitigation 549 The security considerations around the authorization server mix-up 550 that are referenced in Section 8.10 of [RFC8252] also apply to 551 browser-based apps. 553 Clients MUST use a unique redirect URI for each authorization server 554 used by the application. The client MUST store the redirect URI 555 along with the session data (e.g. along with "state") and MUST verify 556 that the URI on which the authorization response was received exactly 557 matches. 559 9.6. Cross-Domain Requests 561 To complete the authorization code flow, the browser-based 562 application will need to exchange the authorization code for an 563 access token at the token endpoint. If the authorization server 564 provides additional endpoints to the application, such as metadata 565 URLs, dynamic client registration, revocation, introspection, 566 discovery or user info endpoints, these endpoints may also be 567 accessed by the browser-based app. Since these requests will be made 568 from a browser, authorization servers MUST support the necessary CORS 569 headers (defined in [Fetch]) to allow the browser to make the 570 request. 572 This specification does not include guidelines for deciding whether a 573 CORS policy for the token endpoint should be a wildcard origin or 574 more restrictive. Note, however, that the browser will attempt to 575 GET or POST to the API endpoint before knowing any CORS policy; it 576 simply hides the succeeding or failing result from JavaScript if the 577 policy does not allow sharing. 579 9.7. Content-Security Policy 581 A browser-based application that wishes to use either long-lived 582 refresh tokens or privileged scopes SHOULD restrict its JavaScript 583 execution to a set of statically hosted scripts via a Content 584 Security Policy ([CSP2]) or similar mechanism. A strong Content 585 Security Policy can limit the potential attack vectors for malicious 586 JavaScript to be executed on the page. 588 9.8. OAuth Implicit Flow 590 The OAuth 2.0 Implicit flow (defined in Section 4.2 of OAuth 2.0 591 [RFC6749]) works by the authorization server issuing an access token 592 in the authorization response (front-channel) without the code 593 exchange step. In this case, the access token is returned in the 594 fragment part of the redirect URI, providing an attacker with several 595 opportunities to intercept and steal the access token. 597 Authorization servers MUST NOT issue access tokens in the 598 authorization response, and MUST issue access tokens only from the 599 token endpoint. 601 9.8.1. Attacks on the Implicit Flow 603 Many attacks on the implicit flow described by [RFC6819] and 604 [oauth-security-topics] do not have sufficient mitigation strategies. 605 The following sections describe the specific attacks that cannot be 606 mitigated while continuing to use the implicit flow. 608 9.8.1.1. Threat: Interception of the Redirect URI 610 If an attacker is able to cause the authorization response to be sent 611 to a URI under their control, they will directly get access to the 612 authorization response including the access token. Several methods 613 of performing this attack are described in detail in 614 [oauth-security-topics]. 616 9.8.1.2. Threat: Access Token Leak in Browser History 618 An attacker could obtain the access token from the browser's history. 619 The countermeasures recommended by [RFC6819] are limited to using 620 short expiration times for tokens, and indicating that browsers 621 should not cache the response. Neither of these fully prevent this 622 attack, they only reduce the potential damage. 624 Additionally, many browsers now also sync browser history to cloud 625 services and to multiple devices, providing an even wider attack 626 surface to extract access tokens out of the URL. 628 This is discussed in more detail in Section 4.3.2 of 629 [oauth-security-topics]. 631 9.8.1.3. Threat: Manipulation of Scripts 633 An attacker could modify the page or inject scripts into the browser 634 through various means, including when the browser's HTTPS connection 635 is being man-in-the-middled by, for example, a corporate network. 636 While this type of attack is typically out of scope of basic security 637 recommendations to prevent, in the case of browser-based apps it is 638 much easier to perform this kind of attack, where an injected script 639 can suddenly have access to everything on the page. 641 The risk of a malicious script running on the page may be amplified 642 when the application uses a known standard way of obtaining access 643 tokens, namely that the attacker can always look at the 644 "window.location" variable to find an access token. This threat 645 profile is different from an attacker specifically targeting an 646 individual application by knowing where or how an access token 647 obtained via the authorization code flow may end up being stored. 649 9.8.1.4. Threat: Access Token Leak to Third Party Scripts 651 It is relatively common to use third-party scripts in browser-based 652 apps, such as analytics tools, crash reporting, and even things like 653 a Facebook or Twitter "like" button. In these situations, the author 654 of the application may not be able to be fully aware of the entirety 655 of the code running in the application. When an access token is 656 returned in the fragment, it is visible to any third-party scripts on 657 the page. 659 9.8.2. Countermeasures 661 In addition to the countermeasures described by [RFC6819] and 662 [oauth-security-topics], using the authorization code with PKCE 663 extension prevents the attacks described above by avoiding returning 664 the access token in the redirect response at all. 666 When PKCE is used, if an authorization code is stolen in transport, 667 the attacker is unable to do anything with the authorization code. 669 9.8.3. Disadvantages of the Implicit Flow 671 There are several additional reasons the Implicit flow is 672 disadvantageous compared to using the standard Authorization Code 673 flow. 675 o OAuth 2.0 provides no mechanism for a client to verify that a 676 particular access token was intended for that client, which could 677 lead to misuse and possible impersonation attacks if a malicious 678 party hands off an access token it retrieved through some other 679 means to the client. 681 o Returning an access token in the front-channel redirect gives the 682 authorization server no assurance that the access token will 683 actually end up at the application, since there are many ways this 684 redirect may fail or be intercepted. 686 o Supporting the implicit flow requires additional code, more upkeep 687 and understanding of the related security considerations, while 688 limiting the authorization server to just the authorization code 689 flow reduces the attack surface of the implementation. 691 o If the JavaScript application gets wrapped into a native app, then 692 [RFC8252] also requires the use of the authorization code flow 693 with PKCE anyway. 695 In OpenID Connect, the id_token is sent in a known format (as a JWT), 696 and digitally signed. Returning an id_token using the Implicit flow 697 ("response_type=id_token") requires the client validate the JWT 698 signature, as malicious parties could otherwise craft and supply 699 fraudulent id_tokens. Performing OpenID Connect using the 700 authorization code flow provides the benefit of the client not 701 needing to verify the JWT signature, as the ID token will have been 702 fetched over an HTTPS connection directly from the authorization 703 server. Additionally, in many cases an application will request both 704 an ID token and an access token, so it is simplier and provides fewer 705 attack vectors to obtain both via the authorization code flow. 707 9.8.4. Historic Note 709 Historically, the Implicit flow provided an advantage to single-page 710 apps since JavaScript could always arbitrarily read and manipulate 711 the fragment portion of the URL without triggering a page reload. 712 This was necessary in order to remove the access token from the URL 713 after it was obtained by the app. 715 Modern browsers now have the Session History API (described in 716 "Session history and navigation" of [HTML]), which provides a 717 mechanism to modify the path and query string component of the URL 718 without triggering a page reload. This means modern browser-based 719 apps can use the unmodified OAuth 2.0 authorization code flow, since 720 they have the ability to remove the authorization code from the query 721 string without triggering a page reload thanks to the Session History 722 API. 724 9.9. Additional Security Considerations 726 The OWASP Foundation (https://www.owasp.org/) maintains a set of 727 security recommendations and best practices for web applications, and 728 it is RECOMMENDED to follow these best practices when creating an 729 OAuth 2.0 Browser-Based application. 731 10. IANA Considerations 733 This document does not require any IANA actions. 735 11. References 737 11.1. Normative References 739 [CSP2] West, M., "Content Security Policy", October 2018. 741 [Fetch] whatwg, "Fetch", 2018. 743 [oauth-security-topics] 744 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 745 "OAuth 2.0 Security Best Current Practice", July 2019. 747 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 748 Requirement Levels", BCP 14, RFC 2119, 749 DOI 10.17487/RFC2119, March 1997, 750 . 752 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 753 RFC 6749, DOI 10.17487/RFC6749, October 2012, 754 . 756 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 757 Framework: Bearer Token Usage", RFC 6750, 758 DOI 10.17487/RFC6750, October 2012, 759 . 761 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 762 Threat Model and Security Considerations", RFC 6819, 763 DOI 10.17487/RFC6819, January 2013, 764 . 766 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 767 for Code Exchange by OAuth Public Clients", RFC 7636, 768 DOI 10.17487/RFC7636, September 2015, 769 . 771 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 772 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 773 . 775 11.2. Informative References 777 [HTML] whatwg, "HTML", 2020. 779 Appendix A. Server Support Checklist 781 OAuth authorization servers that support browser-based apps MUST: 783 1. Require "https" scheme redirect URIs. 785 2. Require exact matching of registered redirect URIs. 787 3. Support PKCE [RFC7636]. Required to protect authorization code 788 grants sent to public clients. See Section 7.1 790 4. Support cross-domain requests at the token endpoint in order to 791 allow browsers to make the authorization code exchange request. 792 See Section 9.6 794 5. Not assume that browser-based clients can keep a secret, and 795 SHOULD NOT issue secrets to applications of this type. 797 6. Not support the Resource Owner Password grant for browser-based 798 clients. 800 7. Follow the [oauth-security-topics] recommendations on refresh 801 tokens, as well as the additional requirements described in 802 Section 8. 804 Appendix B. Document History 806 [[ To be removed from the final specification ]] 808 -07 810 o Clarify PKCE requirements apply only to issuing access tokens 812 o Change "MUST" to "SHOULD" for refresh token rotation 814 o Editorial clarifications 816 -06 818 o Added refresh token requirements to AS summary 820 o Editorial clarifications 822 -05 824 o Incorporated editorial and substantive feedback from Mike Jones 826 o Added references to "nonce" as another way to prevent CSRF attacks 828 o Updated headers in the Implicit Flow section to better represent 829 the relationship between the paragraphs 831 -04 833 o Disallow the use of the Password Grant 835 o Add PKCE support to summary list for authorization server 836 requirements 838 o Rewrote refresh token section to allow refresh tokens if they are 839 time-limited, rotated on each use, and requiring that the rotated 840 refresh token lifetimes do not extend past the lifetime of the 841 initial refresh token, and to bring it in line with the Security 842 BCP 844 o Updated recommendations on using state to reflect the Security BCP 846 o Updated server support checklist to reflect latest changes 847 o Updated the same-domain JS architecture section to emphasize the 848 architecture rather than domain 850 o Editorial clarifications in the section that talks about OpenID 851 Connect ID tokens 853 -03 855 o Updated the historic note about the fragment URL clarifying that 856 the Session History API means browsers can use the unmodified 857 authorization code flow 859 o Rephrased "Authorization Code Flow" intro paragraph to better lead 860 into the next two sections 862 o Softened "is likely a better decision to avoid using OAuth 863 entirely" to "it may be..." for common-domain deployments 865 o Updated abstract to not be limited to public clients, since the 866 later sections talk about confidential clients 868 o Removed references to avoiding OpenID Connect for same-domain 869 architectures 871 o Updated headers to better describe architectures (Apps Served from 872 a Static Web Server -> JavaScript Applications without a Backend) 874 o Expanded "same-domain architecture" section to better explain the 875 problems that OAuth has in this scenario 877 o Referenced Security BCP in implicit flow attacks where possible 879 o Minor typo corrections 881 -02 883 o Rewrote overview section incorporating feedback from Leo Tohill 885 o Updated summary recommendation bullet points to split out 886 application and server requirements 888 o Removed the allowance on hostname-only redirect URI matching, now 889 requiring exact redirect URI matching 891 o Updated section 6.2 to drop reference of SPA with a backend 892 component being a public client 894 o Expanded the architecture section to explicitly mention three 895 architectural patterns available to JS apps 897 -01 899 o Incorporated feedback from Torsten Lodderstedt 901 o Updated abstract 903 o Clarified the definition of browser-based apps to not exclude 904 applications cached in the browser, e.g. via Service Workers 906 o Clarified use of the state parameter for CSRF protection 908 o Added background information about the original reason the 909 implicit flow was created due to lack of CORS support 911 o Clarified the same-domain use case where the SPA and API share a 912 cookie domain 914 o Moved historic note about the fragment URL into the Overview 916 Appendix C. Acknowledgements 918 The authors would like to acknowledge the work of William Denniss and 919 John Bradley, whose recommendation for native apps informed many of 920 the best practices for browser-based applications. The authors would 921 also like to thank Hannes Tschofenig and Torsten Lodderstedt, the 922 attendees of the Internet Identity Workshop 27 session at which this 923 BCP was originally proposed, and the following individuals who 924 contributed ideas, feedback, and wording that shaped and formed the 925 final specification: 927 Annabelle Backman, Brian Campbell, Brock Allen, Christian Mainka, 928 Daniel Fett, George Fletcher, Hannes Tschofenig, Janak Amarasena, 929 John Bradley, Joseph Heenan, Justin Richer, Karl McGuinness, Leo 930 Tohill, Mike Jones, Tomek Stojecki, Torsten Lodderstedt, and Vittorio 931 Bertocci. 933 Authors' Addresses 935 Aaron Parecki 936 Okta 938 Email: aaron@parecki.com 939 URI: https://aaronparecki.com 940 David Waite 941 Ping Identity 943 Email: david@alkaline-solutions.com