idnits 2.17.00 (12 Aug 2021) /tmp/idnits56138/draft-ietf-oauth-browser-based-apps-09.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 document date (7 March 2022) is 68 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 (~~), 0 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Parecki 3 Internet-Draft Okta 4 Intended status: Best Current Practice D. Waite 5 Expires: 8 September 2022 Ping Identity 6 7 March 2022 8 OAuth 2.0 for Browser-Based Apps 9 draft-ietf-oauth-browser-based-apps-09 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 8 September 2022. 34 Copyright Notice 36 Copyright (c) 2022 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 (https://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Revised BSD License text as 45 described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Revised BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 52 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 5. First-Party Applications . . . . . . . . . . . . . . . . . . 5 55 6. Application Architecture Patterns . . . . . . . . . . . . . . 6 56 6.1. Browser-Based Apps that Can Share Data with the Resource 57 Server . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 6.2. JavaScript Applications with a Backend . . . . . . . . . 7 59 6.3. JavaScript Applications without a Backend . . . . . . . . 8 60 7. Authorization Code Flow . . . . . . . . . . . . . . . . . . . 10 61 7.1. Initiating the Authorization Request from a Browser-Based 62 Application . . . . . . . . . . . . . . . . . . . . . . . 10 63 7.2. Handling the Authorization Code Redirect . . . . . . . . 10 64 8. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . . . 10 65 9. Security Considerations . . . . . . . . . . . . . . . . . . . 12 66 9.1. Registration of Browser-Based Apps . . . . . . . . . . . 12 67 9.2. Client Authentication . . . . . . . . . . . . . . . . . . 12 68 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 13 69 9.4. Cross-Site Request Forgery Protections . . . . . . . . . 13 70 9.5. Authorization Server Mix-Up Mitigation . . . . . . . . . 13 71 9.6. Cross-Domain Requests . . . . . . . . . . . . . . . . . . 14 72 9.7. Content Security Policy . . . . . . . . . . . . . . . . . 14 73 9.8. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 14 74 9.8.1. Attacks on the Implicit Flow . . . . . . . . . . . . 15 75 9.8.2. Countermeasures . . . . . . . . . . . . . . . . . . . 16 76 9.8.3. Disadvantages of the Implicit Flow . . . . . . . . . 16 77 9.8.4. Historic Note . . . . . . . . . . . . . . . . . . . . 17 78 9.9. Additional Security Considerations . . . . . . . . . . . 17 79 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 80 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 81 11.1. Normative References . . . . . . . . . . . . . . . . . . 17 82 11.2. Informative References . . . . . . . . . . . . . . . . . 18 83 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 19 84 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19 85 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 22 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 88 1. Introduction 90 This specification describes the current best practices for 91 implementing OAuth 2.0 authorization flows in applications executing 92 in a browser. 94 For native application developers using OAuth 2.0 and OpenID Connect, 95 an IETF BCP (best current practice) was published that guides 96 integration of these technologies. This document is formally known 97 as [RFC8252] or BCP 212, but nicknamed "AppAuth" after the OpenID 98 Foundation-sponsored set of libraries that assist developers in 99 adopting these practices. [RFC8252] makes specific recommendations 100 for how to securely implement OAuth in native applications, including 101 incorporating additional OAuth extensions where needed. 103 OAuth 2.0 for Browser-Based Apps addresses the similarities between 104 implementing OAuth for native apps and browser-based apps, and 105 includes additional considerations when running in a browser. This 106 is primarily focused on OAuth, except where OpenID Connect provides 107 additional considerations. 109 Many of these recommendations are derived from the OAuth 2.0 Security 110 Best Current Practice [oauth-security-topics] and browser-based apps 111 are expected to follow those recommendations as well. This draft 112 expands on and further restricts various recommendations in 113 [oauth-security-topics]. 115 2. Notational Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 119 "OPTIONAL" in this document are to be interpreted as described in 120 [RFC2119]. 122 3. Terminology 124 In addition to the terms defined in referenced specifications, this 125 document uses the following terms: 127 "OAuth": In this document, "OAuth" refers to OAuth 2.0, [RFC6749] 128 and [RFC6750]. 130 "Browser-based application": An application that is dynamically 131 downloaded and executed in a web browser, usually written in 132 JavaScript. Also sometimes referred to as a "single-page 133 application", or "SPA". 135 4. Overview 137 At the time that OAuth 2.0 [RFC6749] and [RFC6750] were created, 138 browser-based JavaScript applications needed a solution that strictly 139 complied with the same-origin policy. Common deployments of OAuth 140 2.0 involved an application running on a different domain than the 141 authorization server, so it was historically not possible to use the 142 Authorization Code flow which would require a cross-origin POST 143 request. This was one of the motivations for the definition of the 144 Implicit flow, which returns the access token in the front channel 145 via the fragment part of the URL, bypassing the need for a cross- 146 origin POST request. 148 However, there are several drawbacks to the Implicit flow, generally 149 involving vulnerabilities associated with the exposure of the access 150 token in the URL. See Section 9.8 for an analysis of these attacks 151 and the drawbacks of using the Implicit flow in browsers. Additional 152 attacks and security considerations can be found in 153 [oauth-security-topics]. 155 In recent years, widespread adoption of Cross-Origin Resource Sharing 156 (CORS), which enables exceptions to the same-origin policy, allows 157 browser-based apps to use the OAuth 2.0 Authorization Code flow and 158 make a POST request to exchange the authorization code for an access 159 token at the token endpoint. In this flow, the access token is never 160 exposed in the less secure front channel. Furthermore, adding PKCE 161 to the flow ensures that even if an authorization code is 162 intercepted, it is unusable by an attacker. 164 For this reason, and from other lessons learned, the current best 165 practice for browser-based applications is to use the OAuth 2.0 166 Authorization Code flow with PKCE. 168 Browser-based applications: 170 * MUST use the OAuth 2.0 Authorization Code flow with the PKCE 171 extension when obtaining an access token 173 * MUST Protect themselves against CSRF attacks by either: 175 - ensuring the authorization server supports PKCE, or 177 - by using the OAuth 2.0 "state" parameter or the OpenID Connect 178 "nonce" parameter to carry one-time use CSRF tokens 180 * MUST Register one or more redirect URIs, and use only exact 181 registered redirect URIs in authorization requests 183 OAuth 2.0 authorization servers supporting browser-based 184 applications: 186 * MUST Require exact matching of registered redirect URIs 188 * MUST Support the PKCE extension 190 * MUST NOT issue access tokens in the authorization response 192 * If issuing refresh tokens to browser-based applications, then: 194 - MUST rotate refresh tokens on each use or use sender- 195 constrained refresh tokens, and 197 - MUST set a maximum lifetime on refresh tokens or expire if they 198 are not used in some amount of time 200 5. First-Party Applications 202 While OAuth was initially created to allow third-party applications 203 to access an API on behalf of a user, it has proven to be useful in a 204 first-party scenario as well. First-party apps are applications 205 where the same organization provides both the API and the 206 application. 208 Examples of first-party applications are a web email client provided 209 by the operator of the email account, or a mobile banking application 210 created by bank itself. (Note that there is no requirement that the 211 application actually be developed by the same company; a mobile 212 banking application developed by a contractor that is branded as the 213 bank's application is still considered a first-party application.) 214 The first-party app consideration is about the user's relationship to 215 the application and the service. 217 To conform to this best practice, first-party applications using 218 OAuth or OpenID Connect MUST use a redirect-based flow (such as the 219 OAuth Authorization Code flow) as described later in this document. 221 The resource owner password credentials grant MUST NOT be used, as 222 described in [oauth-security-topics] Section 2.4. Instead, by using 223 the Authorization Code flow and redirecting the user to the 224 authorization server, this provides the authorization server the 225 opportunity to prompt the user for multi-factor authentication 226 options, take advantage of single sign-on sessions, or use third- 227 party identity providers. In contrast, the resource owner password 228 credentials grant does not provide any built-in mechanism for these, 229 and would instead be extended with custom code. 231 6. Application Architecture Patterns 233 There are three primary architectural patterns available when 234 building browser-based applications. 236 * a JavaScript application that has methods of sharing data with 237 resource servers, such as using common-domain cookies 239 * a JavaScript application with a backend component 241 * a JavaScript application with no backend, accessing resource 242 servers directly 244 These three architectures have different use cases and 245 considerations. 247 6.1. Browser-Based Apps that Can Share Data with the Resource Server 249 For simple system architectures, such as when the JavaScript 250 application is served from a domain that can share cookies with the 251 domain of the API (resource server), OAuth adds additional attack 252 vectors that could be avoided with a different solution. 254 In particular, using any redirect-based mechanism of obtaining an 255 access token enables the redirect-based attacks described in 256 [oauth-security-topics] Section 4, but if the application, 257 authorization server and resource server share a domain, then it is 258 unnecessary to use a redirect mechanism to communicate between them. 260 An additional concern with handling access tokens in a browser is 261 that as of the date of this publication, there is no secure storage 262 mechanism where JavaScript code can keep the access token to be later 263 used in an API request. Using an OAuth flow results in the 264 JavaScript code getting an access token, needing to store it 265 somewhere, and then retrieve it to make an API request. 267 Instead, a more secure design is to use an HTTP-only cookie between 268 the JavaScript application and API so that the JavaScript code can't 269 access the cookie value itself. The Secure cookie attribute should 270 be used to ensure the cookie is not included in unencrypted HTTP 271 requests. Additionally, the SameSite cookie attribute can be used to 272 counter CSRF attacks, but should not be considered the extent of the 273 CSRF protection, as described in [draft-ietf-httpbis-rfc6265bis] 275 OAuth was originally created for third-party or federated access to 276 APIs, so it may not be the best solution in a common-domain 277 deployment. That said, there are still some advantages in using 278 OAuth even in a common-domain architecture: 280 * Allows more flexibility in the future, such as if you were to 281 later add a new domain to the system. With OAuth already in 282 place, adding a new domain wouldn't require any additional 283 rearchitecting. 285 * Being able to take advantage of existing library support rather 286 than writing bespoke code for the integration. 288 * Centralizing login and multifactor support, account management, 289 and recovery at the OAuth server, rather than making it part of 290 the application logic. 292 Using OAuth for browser-based apps in a first-party same-domain 293 scenario provides these advantages, and can be accomplished by either 294 of the two architectural patterns described below. 296 6.2. JavaScript Applications with a Backend 298 +-------------+ +--------------+ +---------------+ 299 | | | | | | 300 |Authorization| | Token | | Resource | 301 | Endpoint | | Endpoint | | Server | 302 | | | | | | 303 +-------------+ +--------------+ +---------------+ 305 ^ ^ ^ 306 | (D)| (G)| 307 | v v 308 | 309 | +--------------------------------+ 310 | | | 311 | | Application | 312 (B)| | Server | 313 | | | 314 | +--------------------------------+ 315 | 316 | ^ ^ + ^ + 317 | (A)| (C)| (E)| (F)| |(H) 318 v v + v + v 320 +-------------------------------------------------+ 321 | | 322 | Browser | 323 | | 324 +-------------------------------------------------+ 325 In this architecture, commonly referred to as "backend for frontend" 326 or "BFF", the JavaScript code is loaded from a dynamic Application 327 Server (A) that also has the ability to execute code itself. This 328 enables the ability to keep all of the steps involved in obtaining an 329 access token outside of the JavaScript application. 331 Note that this application backend is not the Resource Server, it is 332 still considered part of the OAuth client and would be accessing data 333 at a separate resource server. 335 In this case, the Application Server initiates the OAuth flow itself, 336 by redirecting the browser to the authorization endpoint (B). When 337 the user is redirected back, the browser delivers the authorization 338 code to the application server (C), where it can then exchange it for 339 an access token at the token endpoint (D) using its client secret. 340 The application server then keeps the access token and refresh token 341 stored internally, and creates a separate session with the browser- 342 based app via a traditional browser cookie (E). 344 When the JavaScript application in the browser wants to make a 345 request to the Resource Server, it instead makes the request to the 346 Application Server (F), and the Application Server will make the 347 request with the access token to the Resource Server (G), and forward 348 the response (H) back to the browser. 350 (Common examples of this architecture are an Angular front-end with a 351 .NET backend, or a React front-end with a Spring Boot backend.) 353 The Application Server SHOULD be considered a confidential client, 354 and issued its own client secret. The Application Server SHOULD use 355 the OAuth 2.0 Authorization Code grant with PKCE to initiate a 356 request for an access token. Detailed recommendations for 357 confidential clients can be found in [oauth-security-topics] 358 Section 2.1.1. 360 In this scenario, the connection between the browser and Application 361 Server SHOULD be a session cookie provided by the Application Server. 363 Security of the connection between code running in the browser and 364 this Application Server is assumed to utilize browser-level 365 protection mechanisms. Details are out of scope of this document, 366 but many recommendations can be found in the OWASP Cheat Sheet series 367 (https://cheatsheetseries.owasp.org/), such as setting an HTTP-only 368 and Secure cookie to authenticate the session between the browser and 369 Application Server. 371 6.3. JavaScript Applications without a Backend 372 +---------------+ +--------------+ 373 | | | | 374 | Authorization | | Resource | 375 | Server | | Server | 376 | | | | 377 +---------------+ +--------------+ 379 ^ ^ ^ + 380 | | | | 381 |(B) |(C) |(D) |(E) 382 | | | | 383 | | | | 384 + v + v 386 +-----------------+ +-------------------------------+ 387 | | (A) | | 388 | Static Web Host | +-----> | Browser | 389 | | | | 390 +-----------------+ +-------------------------------+ 392 In this architecture, the JavaScript code is first loaded from a 393 static web host into the browser (A), and the application then runs 394 in the browser. This application is considered a public client, 395 since there is no way to issue it a client secret and there is no 396 other secure client authentication mechanism available in the 397 browser. 399 The code in the browser initiates the Authorization Code flow with 400 the PKCE extension (described in Section 7) (B) above, and obtains an 401 access token via a POST request (C). The JavaScript application is 402 then responsible for storing the access token (and optional refresh 403 token) as securely as possible using appropriate browser APIs. As of 404 the date of this publication there is no browser API that allows to 405 store tokens in a completely secure way. 407 When the JavaScript application in the browser wants to make a 408 request to the Resource Server, it can interact with the Resource 409 Server directly. It includes the access token in the request (D) and 410 receives the Resource Server's response (E). 412 In this scenario, the Authorization Server and Resource Server MUST 413 support the necessary CORS headers to enable the JavaScript code to 414 make this POST request from the domain on which the script is 415 executing. (See Section 9.6 for additional details.) 417 7. Authorization Code Flow 419 Browser-based applications that are public clients and use the 420 Authorization Code grant type described in Section 4.1 of OAuth 2.0 421 [RFC6749] MUST also follow these additional requirements described in 422 this section. 424 7.1. Initiating the Authorization Request from a Browser-Based 425 Application 427 Browser-based applications that are public clients MUST implement the 428 Proof Key for Code Exchange (PKCE [RFC7636]) extension when obtaining 429 an access token, and authorization servers MUST support and enforce 430 PKCE for such clients. 432 The PKCE extension prevents an attack where the authorization code is 433 intercepted and exchanged for an access token by a malicious client, 434 by providing the authorization server with a way to verify the client 435 instance that exchanges the authorization code is the same one that 436 initiated the flow. 438 Browser-based applications MUST prevent CSRF attacks against their 439 redirect URI. This can be accomplished by any of the below: 441 * using PKCE, and confirming that the authorization server supports 442 PKCE 444 * using a unique value for the OAuth 2.0 "state" parameter 446 * if the application is using OpenID Connect, by using the OpenID 447 Connect "nonce" parameter 449 7.2. Handling the Authorization Code Redirect 451 Authorization servers MUST require an exact match of a registered 452 redirect URI. As described in [oauth-security-topics] Section 4.1.1. 453 this helps to prevent attacks targeting the authorization code. 455 8. Refresh Tokens 457 Refresh tokens provide a way for applications to obtain a new access 458 token when the initial access token expires. With public clients, 459 the risk of a leaked refresh token is greater than leaked access 460 tokens, since an attacker may be able to continue using the stolen 461 refresh token to obtain new access tokens potentially without being 462 detectable by the authorization server. 464 Browser-based applications provide an attacker with several 465 opportunities by which a refresh token can be leaked, just as with 466 access tokens. As such, these applications are considered a higher 467 risk for handling refresh tokens. 469 Authorization servers may choose whether or not to issue refresh 470 tokens to browser-based applications. [oauth-security-topics] 471 describes some additional requirements around refresh tokens on top 472 of the recommendations of [RFC6749]. Applications and authorization 473 servers conforming to this BCP MUST also follow the recommendations 474 in [oauth-security-topics] around refresh tokens if refresh tokens 475 are issued to browser-based applications. 477 In particular, authorization servers: 479 * MUST either rotate refresh tokens on each use OR use sender- 480 constrained refresh tokens as described in [oauth-security-topics] 481 Section 4.13.2 483 * MUST either set a maximum lifetime on refresh tokens OR expire if 484 the refresh token has not been used within some amount of time 486 * MUST NOT extend the lifetime of the new refresh token beyond the 487 lifetime of the initial refresh token 489 * upon issuing a rotated refresh token, MUST NOT extend the lifetime 490 of the new refresh token beyond the lifetime of the initial 491 refresh token if the refresh token has a preestablished expiration 492 time 494 For example: 496 * A user authorizes an application, issuing an access token that 497 lasts 1 hour, and a refresh token that lasts 24 hours 499 * After 1 hour, the initial access token expires, so the application 500 uses the refresh token to get a new access token 502 * The authorization server returns a new access token that lasts 1 503 hour, and a new refresh token that lasts 23 hours 505 * This continues until 24 hours pass from the initial authorization 507 * At this point, when the application attempts to use the refresh 508 token after 24 hours, the request will fail and the application 509 will have to involve the user in a new authorization request 511 By limiting the overall refresh token lifetime to the lifetime of the 512 initial refresh token, this ensures a stolen refresh token cannot be 513 used indefinitely. 515 Authorization servers MAY set different policies around refresh token 516 issuance, lifetime and expiration for browser-based applications 517 compared to other public clients. 519 9. Security Considerations 521 9.1. Registration of Browser-Based Apps 523 Browser-based applications are considered public clients as defined 524 by Section 2.1 of OAuth 2.0 [RFC6749], and MUST be registered with 525 the authorization server as such. Authorization servers MUST record 526 the client type in the client registration details in order to 527 identify and process requests accordingly. 529 Authorization servers MUST require that browser-based applications 530 register one or more redirect URIs. 532 9.2. Client Authentication 534 Since a browser-based application's source code is delivered to the 535 end-user's browser, it cannot contain provisioned secrets. As such, 536 a browser-based app with native OAuth support is considered a public 537 client as defined by Section 2.1 of OAuth 2.0 [RFC6749]. 539 Secrets that are statically included as part of an app distributed to 540 multiple users should not be treated as confidential secrets, as one 541 user may inspect their copy and learn the shared secret. For this 542 reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT 543 RECOMMENDED for authorization servers to require client 544 authentication of browser-based applications using a shared secret, 545 as this serves little value beyond client identification which is 546 already provided by the client_id request parameter. 548 Authorization servers that still require a statically included shared 549 secret for SPA clients MUST treat the client as a public client, and 550 not accept the secret as proof of the client's identity. Without 551 additional measures, such clients are subject to client impersonation 552 (see Section 9.3 below). 554 9.3. Client Impersonation 556 As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization 557 server SHOULD NOT process authorization requests automatically 558 without user consent or interaction, except when the identity of the 559 client can be assured. 561 If authorization servers restrict redirect URIs to a fixed set of 562 absolute HTTPS URIs, preventing the use of wildcard domains, wildcard 563 paths, or wildcard query string components, this exact match of 564 registered absolute HTTPS URIs MAY be accepted by authorization 565 servers as proof of identity of the client for the purpose of 566 deciding whether to automatically process an authorization request 567 when a previous request for the client_id has already been approved. 569 9.4. Cross-Site Request Forgery Protections 571 Clients MUST prevent Cross-Site Request Forgery (CSRF) attacks 572 against their redirect URI. Clients can accomplish this by either 573 ensuring the authorization server supports PKCE and relying on the 574 CSRF protection that PKCE provides, or if the client is also an 575 OpenID Connect client, using the OpenID Connect "nonce" parameter, or 576 by using the "state" parameter to carry one-time-use CSRF tokens as 577 described in Section 7.1. 579 See Section 2.1 of [oauth-security-topics] for additional details. 581 9.5. Authorization Server Mix-Up Mitigation 583 Authorization server mix-up attacks mark a severe threat to every 584 client that supports at least two authorization servers. To conform 585 to this BCP such clients MUST apply countermeasures to defend against 586 mix-up attacks. 588 It is RECOMMENDED to defend against mix-up attacks by identifying and 589 validating the issuer of the authorization response. This can be 590 achieved either by using the "iss" response parameter, as defined in 591 [oauth-iss-auth-resp], or by using the "iss" Claim of the ID token 592 when OpenID Connect is used. 594 Alternative countermeasures, such as using distinct redirect URIs for 595 each issuer, SHOULD only be used if identifying the issuer as 596 described is not possible. 598 Section 4.4 of [oauth-security-topics] provides additional details 599 about mix-up attacks and the countermeasures mentioned above. 601 9.6. Cross-Domain Requests 603 To complete the Authorization Code flow, the browser-based 604 application will need to exchange the authorization code for an 605 access token at the token endpoint. If the authorization server 606 provides additional endpoints to the application, such as metadata 607 URLs, dynamic client registration, revocation, introspection, 608 discovery or user info endpoints, these endpoints may also be 609 accessed by the browser-based app. Since these requests will be made 610 from a browser, authorization servers MUST support the necessary CORS 611 headers (defined in [Fetch]) to allow the browser to make the 612 request. 614 This specification does not include guidelines for deciding whether a 615 CORS policy for the token endpoint should be a wildcard origin or 616 more restrictive. Note, however, that the browser will attempt to 617 GET or POST to the API endpoint before knowing any CORS policy; it 618 simply hides the succeeding or failing result from JavaScript if the 619 policy does not allow sharing. 621 9.7. Content Security Policy 623 A browser-based application that wishes to use either long-lived 624 refresh tokens or privileged scopes SHOULD restrict its JavaScript 625 execution to a set of statically hosted scripts via a Content 626 Security Policy ([CSP2]) or similar mechanism. A strong Content 627 Security Policy can limit the potential attack vectors for malicious 628 JavaScript to be executed on the page. 630 9.8. OAuth Implicit Flow 632 The OAuth 2.0 Implicit flow (defined in Section 4.2 of OAuth 2.0 633 [RFC6749]) works by the authorization server issuing an access token 634 in the authorization response (front channel) without the code 635 exchange step. In this case, the access token is returned in the 636 fragment part of the redirect URI, providing an attacker with several 637 opportunities to intercept and steal the access token. 639 Authorization servers MUST NOT issue access tokens in the 640 authorization response, and MUST issue access tokens only from the 641 token endpoint. 643 9.8.1. Attacks on the Implicit Flow 645 Many attacks on the Implicit flow described by [RFC6819] and 646 Section 4.1.2 of [oauth-security-topics] do not have sufficient 647 mitigation strategies. The following sections describe the specific 648 attacks that cannot be mitigated while continuing to use the Implicit 649 flow. 651 9.8.1.1. Threat: Manipulation of the Redirect URI 653 If an attacker is able to cause the authorization response to be sent 654 to a URI under their control, they will directly get access to the 655 authorization response including the access token. Several methods 656 of performing this attack are described in detail in 657 [oauth-security-topics]. 659 9.8.1.2. Threat: Access Token Leak in Browser History 661 An attacker could obtain the access token from the browser's history. 662 The countermeasures recommended by [RFC6819] are limited to using 663 short expiration times for tokens, and indicating that browsers 664 should not cache the response. Neither of these fully prevent this 665 attack, they only reduce the potential damage. 667 Additionally, many browsers now also sync browser history to cloud 668 services and to multiple devices, providing an even wider attack 669 surface to extract access tokens out of the URL. 671 This is discussed in more detail in Section 4.3.2 of 672 [oauth-security-topics]. 674 9.8.1.3. Threat: Manipulation of Scripts 676 An attacker could modify the page or inject scripts into the browser 677 through various means, including when the browser's HTTPS connection 678 is being intercepted by, for example, a corporate network. While 679 man-in-the-middle attacks are typically out of scope of basic 680 security recommendations to prevent, in the case of browser-based 681 apps they are much easier to perform. An injected script can enable 682 an attacker to have access to everything on the page. 684 The risk of a malicious script running on the page may be amplified 685 when the application uses a known standard way of obtaining access 686 tokens, namely that the attacker can always look at the 687 window.location variable to find an access token. This threat 688 profile is different from an attacker specifically targeting an 689 individual application by knowing where or how an access token 690 obtained via the Authorization Code flow may end up being stored. 692 9.8.1.4. Threat: Access Token Leak to Third-Party Scripts 694 It is relatively common to use third-party scripts in browser-based 695 apps, such as analytics tools, crash reporting, and even things like 696 a Facebook or Twitter "like" button. In these situations, the author 697 of the application may not be able to be fully aware of the entirety 698 of the code running in the application. When an access token is 699 returned in the fragment, it is visible to any third-party scripts on 700 the page. 702 9.8.2. Countermeasures 704 In addition to the countermeasures described by [RFC6819] and 705 [oauth-security-topics], using the Authorization Code flow with PKCE 706 extension prevents the attacks described above by avoiding returning 707 the access token in the redirect response at all. 709 When PKCE is used, if an authorization code is stolen in transport, 710 the attacker is unable to do anything with the authorization code. 712 9.8.3. Disadvantages of the Implicit Flow 714 There are several additional reasons the Implicit flow is 715 disadvantageous compared to using the standard Authorization Code 716 flow. 718 * OAuth 2.0 provides no mechanism for a client to verify that a 719 particular access token was intended for that client, which could 720 lead to misuse and possible impersonation attacks if a malicious 721 party hands off an access token it retrieved through some other 722 means to the client. 724 * Returning an access token in the front-channel redirect gives the 725 authorization server no assurance that the access token will 726 actually end up at the application, since there are many ways this 727 redirect may fail or be intercepted. 729 * Supporting the Implicit flow requires additional code, more upkeep 730 and understanding of the related security considerations, while 731 limiting the authorization server to just the Authorization Code 732 flow reduces the attack surface of the implementation. 734 * If the JavaScript application gets wrapped into a native app, then 735 [RFC8252] also requires the use of the Authorization Code flow 736 with PKCE anyway. 738 In OpenID Connect, the ID Token is sent in a known format (as a JWT), 739 and digitally signed. Returning an ID token using the Implicit flow 740 (response_type=id_token) requires the client validate the JWT 741 signature, as malicious parties could otherwise craft and supply 742 fraudulent ID tokens. Performing OpenID Connect using the 743 Authorization Code flow provides the benefit of the client not 744 needing to verify the JWT signature, as the ID token will have been 745 fetched over an HTTPS connection directly from the authorization 746 server. Additionally, in many cases an application will request both 747 an ID token and an access token, so it is simplier and provides fewer 748 attack vectors to obtain both via the Authorization Code flow. 750 9.8.4. Historic Note 752 Historically, the Implicit flow provided an advantage to browser- 753 based apps since JavaScript could always arbitrarily read and 754 manipulate the fragment portion of the URL without triggering a page 755 reload. This was necessary in order to remove the access token from 756 the URL after it was obtained by the app. 758 Modern browsers now have the Session History API (described in 759 "Session history and navigation" of [HTML]), which provides a 760 mechanism to modify the path and query string component of the URL 761 without triggering a page reload. This means modern browser-based 762 apps can use the unmodified OAuth 2.0 Authorization Code flow, since 763 they have the ability to remove the authorization code from the query 764 string without triggering a page reload thanks to the Session History 765 API. 767 9.9. Additional Security Considerations 769 The OWASP Foundation (https://www.owasp.org/) maintains a set of 770 security recommendations and best practices for web applications, and 771 it is RECOMMENDED to follow these best practices when creating an 772 OAuth 2.0 Browser-Based application. 774 10. IANA Considerations 776 This document does not require any IANA actions. 778 11. References 780 11.1. Normative References 782 [CSP2] West, M., "Content Security Policy", October 2018. 784 [draft-ietf-httpbis-rfc6265bis] 785 Chen, L., Englehardt, S., West, M., and J. Wilander, 786 "Cookies: HTTP State Management Mechanism", October 2021. 788 [Fetch] whatwg, ., "Fetch", 2018. 790 [oauth-iss-auth-resp] 791 Meyer zu Selhausen, K. and D. Fett, "OAuth 2.0 792 Authorization Server Issuer Identifier in Authorization 793 Response", January 2021. 795 [oauth-security-topics] 796 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 797 "OAuth 2.0 Security Best Current Practice", April 2021. 799 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 800 Requirement Levels", BCP 14, RFC 2119, 801 DOI 10.17487/RFC2119, March 1997, 802 . 804 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 805 RFC 6749, DOI 10.17487/RFC6749, October 2012, 806 . 808 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 809 Framework: Bearer Token Usage", RFC 6750, 810 DOI 10.17487/RFC6750, October 2012, 811 . 813 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 814 Threat Model and Security Considerations", RFC 6819, 815 DOI 10.17487/RFC6819, January 2013, 816 . 818 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 819 for Code Exchange by OAuth Public Clients", RFC 7636, 820 DOI 10.17487/RFC7636, September 2015, 821 . 823 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 824 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 825 . 827 11.2. Informative References 829 [HTML] whatwg, ., "HTML", 2020. 831 Appendix A. Server Support Checklist 833 OAuth authorization servers that support browser-based apps MUST: 835 1. Require "https" scheme redirect URIs. 837 2. Require exact matching of registered redirect URIs. 839 3. Support PKCE [RFC7636]. Required to protect authorization code 840 grants sent to public clients. See Section 7.1 842 4. Support cross-domain requests at the token endpoint in order to 843 allow browsers to make the authorization code exchange request. 844 See Section 9.6 846 5. Not assume that browser-based clients can keep a secret, and 847 SHOULD NOT issue secrets to applications of this type. 849 6. Not support the Resource Owner Password grant for browser-based 850 clients. 852 7. Follow the [oauth-security-topics] recommendations on refresh 853 tokens, as well as the additional requirements described in 854 Section 8. 856 Appendix B. Document History 858 [[ To be removed from the final specification ]] 860 -09 862 * Provide additional context for the same-domain architecture 863 pattern 865 * Added reference to draft-ietf-httpbis-rfc6265bis to clarify that 866 SameSite is not the only CSRF protection measure needed 868 * Editorial improvements 870 -08 872 * Added a note to use the "Secure" cookie attribute in addition to 873 SameSite etc 875 * Updates to bring this draft in sync with the latest Security BCP 877 * Updated text for mix-up countermeasures to reference the new "iss" 878 extension 880 * Changed "SHOULD" for refresh token rotation to MUST either use 881 rotation or sender-constraining to match the Security BCP 883 * Fixed references to other specs and extensions 885 * Editorial improvements in descriptions of the different 886 architectures 888 -07 890 * Clarify PKCE requirements apply only to issuing access tokens 892 * Change "MUST" to "SHOULD" for refresh token rotation 894 * Editorial clarifications 896 -06 898 * Added refresh token requirements to AS summary 900 * Editorial clarifications 902 -05 904 * Incorporated editorial and substantive feedback from Mike Jones 906 * Added references to "nonce" as another way to prevent CSRF attacks 908 * Updated headers in the Implicit Flow section to better represent 909 the relationship between the paragraphs 911 -04 913 * Disallow the use of the Password Grant 915 * Add PKCE support to summary list for authorization server 916 requirements 918 * Rewrote refresh token section to allow refresh tokens if they are 919 time-limited, rotated on each use, and requiring that the rotated 920 refresh token lifetimes do not extend past the lifetime of the 921 initial refresh token, and to bring it in line with the Security 922 BCP 924 * Updated recommendations on using state to reflect the Security BCP 926 * Updated server support checklist to reflect latest changes 927 * Updated the same-domain JS architecture section to emphasize the 928 architecture rather than domain 930 * Editorial clarifications in the section that talks about OpenID 931 Connect ID tokens 933 -03 935 * Updated the historic note about the fragment URL clarifying that 936 the Session History API means browsers can use the unmodified 937 authorization code flow 939 * Rephrased "Authorization Code Flow" intro paragraph to better lead 940 into the next two sections 942 * Softened "is likely a better decision to avoid using OAuth 943 entirely" to "it may be..." for common-domain deployments 945 * Updated abstract to not be limited to public clients, since the 946 later sections talk about confidential clients 948 * Removed references to avoiding OpenID Connect for same-domain 949 architectures 951 * Updated headers to better describe architectures (Apps Served from 952 a Static Web Server -> JavaScript Applications without a Backend) 954 * Expanded "same-domain architecture" section to better explain the 955 problems that OAuth has in this scenario 957 * Referenced Security BCP in implicit flow attacks where possible 959 * Minor typo corrections 961 -02 963 * Rewrote overview section incorporating feedback from Leo Tohill 965 * Updated summary recommendation bullet points to split out 966 application and server requirements 968 * Removed the allowance on hostname-only redirect URI matching, now 969 requiring exact redirect URI matching 971 * Updated Section 6.2 to drop reference of SPA with a backend 972 component being a public client 974 * Expanded the architecture section to explicitly mention three 975 architectural patterns available to JS apps 977 -01 979 * Incorporated feedback from Torsten Lodderstedt 981 * Updated abstract 983 * Clarified the definition of browser-based apps to not exclude 984 applications cached in the browser, e.g. via Service Workers 986 * Clarified use of the state parameter for CSRF protection 988 * Added background information about the original reason the 989 implicit flow was created due to lack of CORS support 991 * Clarified the same-domain use case where the SPA and API share a 992 cookie domain 994 * Moved historic note about the fragment URL into the Overview 996 Appendix C. Acknowledgements 998 The authors would like to acknowledge the work of William Denniss and 999 John Bradley, whose recommendation for native apps informed many of 1000 the best practices for browser-based applications. The authors would 1001 also like to thank Hannes Tschofenig and Torsten Lodderstedt, the 1002 attendees of the Internet Identity Workshop 27 session at which this 1003 BCP was originally proposed, and the following individuals who 1004 contributed ideas, feedback, and wording that shaped and formed the 1005 final specification: 1007 Annabelle Backman, Brian Campbell, Brock Allen, Christian Mainka, 1008 Daniel Fett, George Fletcher, Hannes Tschofenig, Janak Amarasena, 1009 John Bradley, Joseph Heenan, Justin Richer, Karl McGuinness, Karsten 1010 Meyer zu Selhausen, Leo Tohill, Mike Jones, Tomek Stojecki, Torsten 1011 Lodderstedt, and Vittorio Bertocci. 1013 Authors' Addresses 1015 Aaron Parecki 1016 Okta 1017 Email: aaron@parecki.com 1018 URI: https://aaronparecki.com 1019 David Waite 1020 Ping Identity 1021 Email: david@alkaline-solutions.com