idnits 2.17.1 draft-ietf-oauth-browser-based-apps-03.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 (July 24, 2019) is 1739 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: January 25, 2020 Ping Identity 6 July 24, 2019 8 OAuth 2.0 for Browser-Based Apps 9 draft-ietf-oauth-browser-based-apps-03 11 Abstract 13 This specification details the security considerations that must be 14 taken into account when developing browser-based applications, as 15 well as best practices for how they can securely implement 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 January 25, 2020. 34 Copyright Notice 36 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . . 4 56 6. Application Architecture Patterns . . . . . . . . . . . . . . 5 57 6.1. Apps Served from a Common Domain as the Resource Server . 5 58 6.2. JavaScript Applications with a Backend . . . . . . . . . 6 59 6.3. JavaScript Applications without a Backend . . . . . . . . 8 60 7. Authorization Code Flow . . . . . . . . . . . . . . . . . . . 9 61 7.1. Initiating the Authorization Request from a Browser-Based 62 Application . . . . . . . . . . . . . . . . . . . . . . . 9 63 7.2. Handling the Authorization Code Redirect . . . . . . . . 9 64 8. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . . . 10 65 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 66 9.1. Registration of Browser-Based Apps . . . . . . . . . . . 10 67 9.2. Client Authentication . . . . . . . . . . . . . . . . . . 10 68 9.3. Client Impersonation . . . . . . . . . . . . . . . . . . 11 69 9.4. Cross-Site Request Forgery Protections . . . . . . . . . 11 70 9.5. Authorization Server Mix-Up Mitigation . . . . . . . . . 11 71 9.6. Cross-Domain Requests . . . . . . . . . . . . . . . . . . 12 72 9.7. Content-Security Policy . . . . . . . . . . . . . . . . . 12 73 9.8. OAuth Implicit Grant Authorization Flow . . . . . . . . . 12 74 9.8.1. Threat: Interception of the Redirect URI . . . . . . 13 75 9.8.2. Threat: Access Token Leak in Browser History . . . . 13 76 9.8.3. Threat: Manipulation of Scripts . . . . . . . . . . . 13 77 9.8.4. Threat: Access Token Leak to Third Party Scripts . . 13 78 9.8.5. Countermeasures . . . . . . . . . . . . . . . . . . . 14 79 9.8.6. Disadvantages of the Implicit Flow . . . . . . . . . 14 80 9.8.7. Historic Note . . . . . . . . . . . . . . . . . . . . 15 81 9.9. Additional Security Considerations . . . . . . . . . . . 15 82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 83 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 84 11.1. Normative References . . . . . . . . . . . . . . . . . . 15 85 11.2. Informative References . . . . . . . . . . . . . . . . . 16 86 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 16 87 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 88 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 91 1. Introduction 93 This specification describes the current best practices for 94 implementing OAuth 2.0 authorization flows in applications running 95 entirely in a browser. 97 For native application developers using OAuth 2.0 and OpenID Connect, 98 an IETF BCP (best current practice) was published that guides 99 integration of these technologies. This document is formally known 100 as [RFC8252] or BCP 212, but nicknamed "AppAuth" after the OpenID 101 Foundation-sponsored set of libraries that assist developers in 102 adopting these practices. 104 [RFC8252] makes specific recommendations for how to securely 105 implement OAuth in native applications, including incorporating 106 additional OAuth extensions where needed. 108 OAuth 2.0 for Browser-Based Apps addresses the similarities between 109 implementing OAuth for native apps as well as browser-based apps, and 110 includes additional considerations when running in a browser. This 111 is primarily focused on OAuth, except where OpenID Connect provides 112 additional considerations. 114 2. Notational Conventions 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 118 "OPTIONAL" in this document are to be interpreted as described in 119 [RFC2119]. 121 3. Terminology 123 In addition to the terms defined in referenced specifications, this 124 document uses the following terms: 126 "OAuth": In this document, "OAuth" refers to OAuth 2.0, [RFC6749]. 128 "Browser-based application": An application that is dynamically 129 downloaded and executed in a web browser, usually written in 130 JavaScript. Also sometimes referred to as a "single-page 131 application", or "SPA". 133 4. Overview 135 At the time that OAuth 2.0 RFC 6749 was created, browser-based 136 JavaScript applications needed a solution that strictly complied with 137 the same-origin policy. Common deployments of OAuth 2.0 involved an 138 application running on a different domain than the authorization 139 server, so it was historically not possible to use the authorization 140 code flow which would require a cross-origin POST request. This was 141 the principal motivation for the definition of the implicit flow, 142 which returns the access token in the front channel via the fragment 143 part of the URL, bypassing the need for a cross-origin POST request. 145 However, there are several drawbacks to the implicit flow, generally 146 involving vulnerabilities associated with the exposure of the access 147 token in the URL. See Section 9.8 for an analysis of these attacks 148 and the drawbacks of using the implicit flow in browsers. Additional 149 attacks and security considerations can be found in 150 [oauth-security-topics]. 152 In recent years, widespread adoption of Cross-Origin Resource Sharing 153 (CORS), which enables exceptions to the same-origin policy, allows 154 browser-based apps to use the OAuth 2.0 authorization code flow and 155 make a POST request to exchange the authorization code for an access 156 token at the token endpoint. In this flow, the access token is never 157 exposed in the less secure front-channel. Furthermore, adding PKCE 158 to the flow assures that even if an authorization code is 159 intercepted, it is unusable by an attacker. 161 For this reason, and from other lessons learned, the current best 162 practice for browser-based applications is to use the OAuth 2.0 163 authorization code flow with PKCE. 165 Applications should: 167 o Use the OAuth 2.0 authorization code flow with the PKCE extension 169 o Use the OAuth 2.0 state parameter to carry one-time use CSRF 170 tokens 172 o Register one or more redirect URIs, and not vary the redirect URI 173 per authorization request 175 OAuth 2.0 servers must: 177 o Require exact matching of registered redirect URIs 179 5. First-Party Applications 181 While OAuth was initially created to allow third-party applications 182 to access an API on behalf of a user, it has proven to be useful in a 183 first-party scenario as well. First-party apps are applications 184 where the same organization provides both the API and the 185 application. 187 For example, a web email client provided by the operator of the email 188 account, or a mobile banking application created by bank itself. 189 (Note that there is no requirement that the application actually be 190 developed by the same company; a mobile banking application developed 191 by a contractor that is branded as the bank's application is still 192 considered a first-party application.) The first-party app 193 consideration is about the user's relationship to the application and 194 the service. 196 To conform to this best practice, first-party applications using 197 OAuth or OpenID Connect MUST use the OAuth Authorization Code flow as 198 described later in this document or use the OAuth Password grant. 200 It is strongly RECOMMENDED that applications use the Authorization 201 Code flow over the Password grant for several reasons. By 202 redirecting to the authorization server, this provides the 203 authorization server the opportunity to prompt the user for multi- 204 factor authentication options, take advantage of single-sign-on 205 sessions, or use third-party identity providers. In contrast, the 206 Password grant does not provide any built-in mechanism for these, and 207 must be extended with custom code. 209 6. Application Architecture Patterns 211 There are three primary architectural patterns available when 212 building browser-based applications. 214 o a JavaScript application served from a common domain as the 215 resource server 217 o a JavaScript application with a backend 219 o a JavaScript application with no backend, accessing resource 220 servers directly 222 These three architectures have different use cases and 223 considerations. 225 6.1. Apps Served from a Common Domain as the Resource Server 227 For simple system architectures, such as when the JavaScript 228 application is served from a domain that can share cookies with the 229 domain of the API (resource server), OAuth adds additional attack 230 vectors that could be avoided with a different solution. 232 In particular, using any redirect-based mechanism of obtaining an 233 access token enables the redirect-based attacks described in 234 [oauth-security-topics], but if the application, AS and API share a 235 domain, then it is unnecessary to use a redirect mechanism to 236 communicate between them. 238 An additional concern with handling access tokens in a browser is 239 that there is no secure storage mechanism where JavaScript code can 240 keep the access token to be later used in an API request. Using an 241 OAuth flow results in the JavaScript code getting an access token, 242 needing to store it somewhere, and then retrieve it to make an API 243 request. Instead, it is more secure to use an HTTP-only cookie 244 between the JavaScript application and API so that the JavaScript 245 code can't access the cookie value itself. 247 In this situation, it is best to avoid letting the JavaScript code 248 ever see the access token, and instead use a mechanism such as the 249 "JavaScript Applications with a Backend" pattern described below, to 250 keep access tokens out of the browser. 252 If your JavaScript application has no backend, but still shares a 253 domain with the resource server, then it may be best to avoid using 254 OAuth entirely. 256 OAuth was created primarily for third-party or federated access to 257 APIs, so it may not be the best solution in a same-domain scenario. 259 6.2. JavaScript Applications with a Backend 260 +-------------+ 261 | | 262 |Authorization| 263 | Server | 264 | | 265 +-------------+ 267 ^ + 268 |(A) |(B) 269 | | 270 + v 272 +-------------+ +--------------+ 273 | | +---------> | | 274 | Application | (C) | Resource | 275 | Server | | Server | 276 | | <---------+ | | 277 +-------------+ (D) +--------------+ 279 ^ + 280 | | 281 | | browser 282 | | cookie 283 | | 284 + v 286 +-------------+ 287 | | 288 | Browser | 289 | | 290 +-------------+ 292 In this architecture, the JavaScript code is loaded from a dynamic 293 Application Server that also has the ability to execute code itself. 294 This enables the ability to keep all of the steps involved in 295 obtaining an access token outside of the JavaScript application. 297 (Common examples of this architecture are an Angular front-end with a 298 .NET backend, or a React front-end with a Spring Boot backend.) 300 The Application Server SHOULD be considered a confidential client, 301 and issued its own client secret. The Application Server SHOULD use 302 the OAuth 2.0 authorization code grant to initiate a request for an 303 access token. Upon handling the redirect from the Authorization 304 Server, the Application Server will request an access token using the 305 authorization code returned (A), which will be returned to the 306 Application Server (B). The Application Server utilizes its own 307 session with the browser to store the access token. 309 When the JavaScript application in the browser wants to make a 310 request to the Resource Server, it MUST instead make the request to 311 the Application Server, and the Application Server will make the 312 request with the access token to the Resource Server (C), and forward 313 the response (D) back to the browser. 315 Security of the connection between code running in the browser and 316 this Application Server is assumed to utilize browser-level 317 protection mechanisms. Details are out of scope of this document, 318 but many recommendations can be found at the OWASP Foundation 319 (https://www.owasp.org/), such as setting an HTTP-only and Secure 320 cookie to authenticate the session between the browser and 321 Application Server. 323 In this scenario, the session between the browser and Application 324 Server MAY be either a session cookie provided by the Application 325 Server, OR the access token itself. Note that if the access token is 326 used as the session identifier, this exposes the access token to the 327 end user even if it is not available to the JavaScript application, 328 so some authorization servers may wish to limit the capabilities of 329 these clients to mitigate risk. 331 6.3. JavaScript Applications without a Backend 333 +---------------+ +--------------+ 334 | | | | 335 | Authorization | | Resource | 336 | Server | | Server | 337 | | | | 338 +---------------+ +--------------+ 340 ^ + ^ + 341 | | | | 342 |(B) |(C) |(D) |(E) 343 | | | | 344 | | | | 345 + v + v 347 +-----------------+ +-------------------------------+ 348 | | (A) | | 349 | Static Web Host | +-----> | Browser | 350 | | | | 351 +-----------------+ +-------------------------------+ 353 In this architecture, the JavaScript code is first loaded from a 354 static web host into the browser (A). The application then runs in 355 the browser, and is considered a public client since it has no 356 ability to be issued a client secret. 358 The code in the browser then initiates the authorization code flow 359 with the PKCE extension (described in Section 7) (B) above, and 360 obtains an access token via a POST request (C). The JavaScript app 361 is then responsible for storing the access token securely using 362 appropriate browser APIs. 364 When the JavaScript application in the browser wants to make a 365 request to the Resource Server, it can include the access token in 366 the request (D) and make the request directly. 368 In this scenario, the Authorization Server and Resource Server MUST 369 support the necessary CORS headers to enable the JavaScript code to 370 make this POST request from the domain on which the script is 371 executing. (See Section 9.6 for additional details.) 373 7. Authorization Code Flow 375 Public browser-based apps that use the authorization code grant type 376 described in Section 4.1 of OAuth 2.0 [RFC6749] MUST also follow 377 these additional requirements described in this section. 379 7.1. Initiating the Authorization Request from a Browser-Based 380 Application 382 Public browser-based apps MUST implement the Proof Key for Code 383 Exchange (PKCE [RFC7636]) extension to OAuth, and authorization 384 servers MUST support PKCE for such clients. 386 The PKCE extension prevents an attack where the authorization code is 387 intercepted and exchanged for an access token by a malicious client, 388 by providing the authorization server with a way to verify the same 389 client instance that exchanges the authorization code is the same one 390 that initiated the flow. 392 Browser-based apps MUST use the OAuth 2.0 "state" parameter to 393 protect themselves against Cross-Site Request Forgery and 394 authorization code swap attacks and MUST use a unique value for each 395 authorization request, and MUST verify the returned state in the 396 authorization response matches the original state the app created. 398 7.2. Handling the Authorization Code Redirect 400 Authorization servers MUST require an exact match of a registered 401 redirect URI. 403 8. Refresh Tokens 405 Refresh tokens provide a way for applications to obtain a new access 406 token when the initial access token expires. [oauth-security-topics] 407 describes some additional requirements around refresh tokens on top 408 of the recommendations of [RFC6749]. 410 For public clients, the risk of a leaked refresh token is much 411 greater than leaked access tokens, since an attacker can potentially 412 continue using the stolen refresh token to obtain new access tokens 413 without being detectable by the authorization server. Additionally, 414 browser-based applications provide many attack vectors by which a 415 refresh token can be leaked. As such, these applications are 416 considered a higher risk for handling refresh tokens. 418 Authorization servers SHOULD NOT issue refresh tokens to browser- 419 based applications. 421 If an authorization server does choose to issue refresh tokens to 422 browser-based applications, then it MUST issue a new refresh token 423 with every access token refresh response. Doing this mitigates the 424 risk of a leaked refresh token, as a leaked refresh token can be 425 detected if both the attacker and the legitimate client attempt to 426 use the same refresh token. Authorization servers MUST follow the 427 additional refresh token replay mitigation techniques described in 428 [oauth-security-topics]. 430 9. Security Considerations 432 9.1. Registration of Browser-Based Apps 434 Browser-based applications are considered public clients as defined 435 by section 2.1 of OAuth 2.0 [RFC6749], and MUST be registered with 436 the authorization server as such. Authorization servers MUST record 437 the client type in the client registration details in order to 438 identify and process requests accordingly. 440 Authorization servers MUST require that browser-based applications 441 register one or more redirect URIs. 443 9.2. Client Authentication 445 Since a browser-based application's source code is delivered to the 446 end-user's browser, it cannot contain provisioned secrets. As such, 447 a browser-based app with native OAuth support is considered a public 448 client as defined by Section 2.1 of OAuth 2.0 [RFC6749]. 450 Secrets that are statically included as part of an app distributed to 451 multiple users should not be treated as confidential secrets, as one 452 user may inspect their copy and learn the shared secret. For this 453 reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT 454 RECOMMENDED for authorization servers to require client 455 authentication of browser-based applications using a shared secret, 456 as this serves little value beyond client identification which is 457 already provided by the client_id request parameter. 459 Authorization servers that still require a statically included shared 460 secret for SPA clients MUST treat the client as a public client, and 461 not accept the secret as proof of the client's identity. Without 462 additional measures, such clients are subject to client impersonation 463 (see Section 9.3 below). 465 9.3. Client Impersonation 467 As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization 468 server SHOULD NOT process authorization requests automatically 469 without user consent or interaction, except when the identity of the 470 client can be assured. Even when the user has previously approved an 471 authorization request for a given client_id, the request SHOULD be 472 processed as if no previous request had been approved, unless the 473 identity of the client can be proven. 475 If authorization servers restrict redirect URIs to a fixed set of 476 absolute HTTPS URIs without wildcard domains, paths, or query string 477 components, this exact match of registered absolute HTTPS URIs MAY be 478 accepted by authorization servers as proof of identity of the client 479 for the purpose of deciding whether to automatically process an 480 authorization request when a previous request for the client_id has 481 already been approved. 483 9.4. Cross-Site Request Forgery Protections 485 Section 5.3.5 of [RFC6819] recommends using the "state" parameter to 486 link client requests and responses to prevent CSRF (Cross-Site 487 Request Forgery) attacks. To conform to this best practice, use of 488 the "state" parameter is REQUIRED, as described in Section 7.1. 490 9.5. Authorization Server Mix-Up Mitigation 492 The security considerations around the authorization server mix-up 493 that are referenced in Section 8.10 of [RFC8252] also apply to 494 browser-based apps. 496 Clients MUST use a unique redirect URI for each authorization server 497 used by the application. The client MUST store the redirect URI 498 along with the session data (e.g. along with "state") and MUST verify 499 that the URI on which the authorization response was received exactly 500 matches. 502 9.6. Cross-Domain Requests 504 To complete the authorization code flow, the browser-based 505 application will need to exchange the authorization code for an 506 access token at the token endpoint. If the authorization server 507 provides additional endpoints to the application, such as metadata 508 URLs, dynamic client registration, revocation, introspection, 509 discovery or user info endpoints, these endpoints may also be 510 accessed by the browser-based app. Since these requests will be made 511 from a browser, authorization servers MUST support the necessary CORS 512 headers (defined in [Fetch]) to allow the browser to make the 513 request. 515 This specification does not include guidelines for deciding whether a 516 CORS policy for the token endpoint should be a wildcard origin or 517 more restrictive. Note, however, that the browser will attempt to 518 GET or POST to the API endpoint before knowing any CORS policy; it 519 simply hides the succeeding or failing result from JavaScript if the 520 policy does not allow sharing. 522 9.7. Content-Security Policy 524 A browser-based application that wishes to use either long-lived 525 refresh tokens or privileged scopes SHOULD restrict its JavaScript 526 execution to a set of statically hosted scripts via a Content 527 Security Policy ([CSP2]) or similar mechanism. A strong Content 528 Security Policy can limit the potential attack vectors for malicious 529 JavaScript to be executed on the page. 531 9.8. OAuth Implicit Grant Authorization Flow 533 The OAuth 2.0 Implicit grant authorization flow (defined in 534 Section 4.2 of OAuth 2.0 [RFC6749]) works by receiving an access 535 token in the HTTP redirect (front-channel) immediately without the 536 code exchange step. In this case, the access token is returned in 537 the fragment part of the redirect URI, providing an attacker with 538 several opportunities to intercept and steal the access token. 539 Several attacks on the implicit flow are described by [RFC6819] and 540 [oauth-security-topics], not all of which have sufficient mitigation 541 strategies. 543 9.8.1. Threat: Interception of the Redirect URI 545 If an attacker is able to cause the authorization response to be sent 546 to a URI under his control, he will directly get access to the 547 fragment carrying the access token. A method of performing this 548 attack is described in detail in [oauth-security-topics]. 550 9.8.2. Threat: Access Token Leak in Browser History 552 An attacker could obtain the access token from the browser's history. 553 The countermeasures recommended by [RFC6819] are limited to using 554 short expiration times for tokens, and indicating that browsers 555 should not cache the response. Neither of these fully prevent this 556 attack, they only reduce the potential damage. 558 Additionally, many browsers now also sync browser history to cloud 559 services and to multiple devices, providing an even wider attack 560 surface to extract access tokens out of the URL. 562 This is discussed in more detail in Section 4.3.2 of 563 [oauth-security-topics]. 565 9.8.3. Threat: Manipulation of Scripts 567 An attacker could modify the page or inject scripts into the browser 568 via various means, including when the browser's HTTPS connection is 569 being man-in-the-middled by for example a corporate network. While 570 this type of attack is typically out of scope of basic security 571 recommendations to prevent, in the case of browser-based apps it is 572 much easier to perform this kind of attack, where an injected script 573 can suddenly have access to everything on the page. 575 The risk of a malicious script running on the page is far greater 576 when the application uses a known standard way of obtaining access 577 tokens, namely that the attacker can always look at the 578 window.location to find an access token. This threat profile is very 579 different compared to an attacker specifically targeting an 580 individual application by knowing where or how an access token 581 obtained via the authorization code flow may end up being stored. 583 9.8.4. Threat: Access Token Leak to Third Party Scripts 585 It is relatively common to use third-party scripts in browser-based 586 apps, such as analytics tools, crash reporting, and even things like 587 a Facebook or Twitter "like" button. In these situations, the author 588 of the application may not be able to be fully aware of the entirety 589 of the code running in the application. When an access token is 590 returned in the fragment, it is visible to any third-party scripts on 591 the page. 593 9.8.5. Countermeasures 595 In addition to the countermeasures described by [RFC6819] and 596 [oauth-security-topics], using the authorization code with PKCE 597 avoids these attacks. 599 When PKCE is used, if an authorization code is stolen in transport, 600 the attacker is unable to do anything with the authorization code. 602 9.8.6. Disadvantages of the Implicit Flow 604 There are several additional reasons the Implicit flow is 605 disadvantageous compared to using the standard Authorization Code 606 flow. 608 o OAuth 2.0 provides no mechanism for a client to verify that an 609 access token was issued to it, which could lead to misuse and 610 possible impersonation attacks if a malicious party hands off an 611 access token it retrieved through some other means to the client. 613 o Returning an access token in the front channel redirect gives the 614 authorization server little assurance that the access token will 615 actually end up at the application, since there are many ways this 616 redirect may fail or be intercepted. 618 o Supporting the implicit flow requires additional code, more upkeep 619 and understanding of the related security considerations, while 620 limiting the authorization server to just the authorization code 621 flow reduces the attack surface of the implementation. 623 o If the JavaScript application gets wrapped into a native app, then 624 [RFC8252] also requires the use of the authorization code flow 625 with PKCE anyway. 627 In OpenID Connect, the id_token is sent in a known format (as a JWT), 628 and digitally signed. Performing OpenID Connect using the 629 authorization code flow also provides the additional benefit of the 630 client not needing to verify the JWT signature, as the token will 631 have been fetched over an HTTPS connection directly from the 632 authorization server. However, returning an id_token using the 633 Implicit flow requires the client validate the JWT signature, as 634 malicious parties could otherwise craft and supply fraudulent 635 id_tokens. 637 9.8.7. Historic Note 639 Historically, the Implicit flow provided an advantage to single-page 640 apps since JavaScript could always arbitrarily read and manipulate 641 the fragment portion of the URL without triggering a page reload. 642 This was necessary in order to remove the access token from the URL 643 after it was obtained by the app. 645 Modern browsers now have the Session History API (described in 646 "Session history and navigation" of [HTML]), which provides a 647 mechanism to modify the path and query string component of the URL 648 without triggering a page reload. This means modern browser-based 649 apps can use the unmodified OAuth 2.0 authorization code flow, since 650 they have the ability to remove the authorization code from the query 651 string without triggering a page reload thanks to the Session History 652 API. 654 9.9. Additional Security Considerations 656 The OWASP Foundation (https://www.owasp.org/) maintains a set of 657 security recommendations and best practices for web applications, and 658 it is RECOMMENDED to follow these best practices when creating an 659 OAuth 2.0 Browser-Based application. 661 10. IANA Considerations 663 This document does not require any IANA actions. 665 11. References 667 11.1. Normative References 669 [CSP2] West, M., Barth, A., and D. Veditz, "Content Security 670 Policy", December 2016. 672 [Fetch] whatwg, "Fetch", 2018. 674 [oauth-security-topics] 675 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 676 "OAuth 2.0 Security Best Current Practice", July 2019. 678 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 679 Requirement Levels", BCP 14, RFC 2119, 680 DOI 10.17487/RFC2119, March 1997, 681 . 683 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 684 RFC 6749, DOI 10.17487/RFC6749, October 2012, 685 . 687 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 688 Threat Model and Security Considerations", RFC 6819, 689 DOI 10.17487/RFC6819, January 2013, 690 . 692 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 693 for Code Exchange by OAuth Public Clients", RFC 7636, 694 DOI 10.17487/RFC7636, September 2015, 695 . 697 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 698 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 699 . 701 11.2. Informative References 703 [HTML] whatwg, "HTML", 2018. 705 Appendix A. Server Support Checklist 707 OAuth servers that support browser-based apps MUST: 709 1. Require "https" scheme redirect URIs. 711 2. Require exact matching of registered redirect URIs. 713 3. Support PKCE [RFC7636]. Required to protect authorization code 714 grants sent to public clients. See Section 7.1 716 4. Support cross-domain requests at the token endpoint in order to 717 allow browsers to make the authorization code exchange request. 718 See Section 9.6 720 5. Not assume that browser-based clients can keep a secret, and 721 SHOULD NOT issue secrets to applications of this type. 723 Appendix B. Document History 725 [[ To be removed from the final specification ]] 727 -03 728 o Updated the historic note about the fragment URL clarifying that 729 the Session History API means browsers can use the unmodified 730 authorization code flow 732 o Rephrased "Authorization Code Flow" intro paragraph to better lead 733 into the next two sections 735 o Softened "is likely a better decision to avoid using OAuth 736 entirely" to "it may be..." for common-domain deployments 738 o Updated abstract to not be limited to public clients, since the 739 later sections talk about confidential clients 741 o Removed references to avoiding OpenID Connect for same-domain 742 architectures 744 o Updated headers to better describe architectures (Apps Served from 745 a Static Web Server -> JavaScript Applications without a Backend) 747 o Expanded "same-domain architecture" section to better explain the 748 problems that OAuth has in this scenario 750 o Referenced Security BCP in implicit flow attacks where possible 752 o Minor typo corrections 754 -02 756 o Rewrote overview section incorporating feedback from Leo Tohill 758 o Updated summary recommendation bullet points to split out 759 application and server requirements 761 o Removed the allowance on hostname-only redirect URI matching, now 762 requiring exact redirect URI matching 764 o Updated section 6.2 to drop reference of SPA with a backend 765 component being a public client 767 o Expanded the architecture section to explicitly mention three 768 architectural patterns available to JS apps 770 -01 772 o Incorporated feedback from Torsten Lodderstedt 774 o Updated abstract 775 o Clarified the definition of browser-based apps to not exclude 776 applications cached in the browser, e.g. via Service Workers 778 o Clarified use of the state parameter for CSRF protection 780 o Added background information about the original reason the 781 implicit flow was created due to lack of CORS support 783 o Clarified the same-domain use case where the SPA and API share a 784 cookie domain 786 o Moved historic note about the fragment URL into the Overview 788 Appendix C. Acknowledgements 790 The authors would like to acknowledge the work of William Denniss and 791 John Bradley, whose recommendation for native apps informed many of 792 the best practices for browser-based applications. The authors would 793 also like to thank Hannes Tschofenig and Torsten Lodderstedt, the 794 attendees of the Internet Identity Workshop 27 session at which this 795 BCP was originally proposed, and the following individuals who 796 contributed ideas, feedback, and wording that shaped and formed the 797 final specification: 799 Annabelle Backman, Brian Campbell, Brock Allen, Christian Mainka, 800 Daniel Fett, George Fletcher, Hannes Tschofenig, Janak Amarasena, 801 John Bradley, Joseph Heenan, Justin Richer, Karl McGuinness, Leo 802 Tohill, Tomek Stojecki, Torsten Lodderstedt, and Vittorio Bertocci. 804 Authors' Addresses 806 Aaron Parecki 807 Okta 809 Email: aaron@parecki.com 810 URI: https://aaronparecki.com 812 David Waite 813 Ping Identity 815 Email: david@alkaline-solutions.com