idnits 2.17.1 draft-ideskog-assisted-token-05.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 (9 March 2021) is 1141 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Independent Submission J. Ideskog 3 Internet-Draft T. Spencer 4 Intended status: Informational Curity AB 5 Expires: 10 September 2021 9 March 2021 7 OAuth 2.0 Assisted Token 8 draft-ideskog-assisted-token-05 10 Abstract 12 This document extends the OAuth 2.0 framework to include an 13 additional authorization flow for single page applications called the 14 assisted token flow. It enables OAuth clients written in scripting 15 languages, like JavaScript, to request user authorization using a 16 simplified method compared to other flows. Communication does not 17 rely on redirection of the user agent, but instead leverages HTML's 18 iframe element, child windows, and the postMessage interface. This 19 communication is done using an additional endpoint, the assisted 20 token endpoint. 22 Note 24 To contribute to this draft, please feel free to create a pull 25 request from the original source available at 26 https://github.com/curityio/rfc (https://github.com/curityio/rfc/) or 27 email the authors. 29 This note is to be removed before publishing as an RFC. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on 10 September 2021. 48 Copyright Notice 50 Copyright (c) 2021 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 55 license-info) in effect on the date of publication of this document. 56 Please review these documents carefully, as they describe your rights 57 and restrictions with respect to this document. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 3. Assisted Token Endpoint . . . . . . . . . . . . . . . . . . . 6 64 3.1. Access Token Scope . . . . . . . . . . . . . . . . . . . 7 65 3.2. Cross-Origin Support . . . . . . . . . . . . . . . . . . 7 66 4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 4.1. Assisted Token Request . . . . . . . . . . . . . . . . . 7 68 4.2. Assisted Token Response . . . . . . . . . . . . . . . . . 8 69 4.3. Error Response . . . . . . . . . . . . . . . . . . . . . 9 70 5. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 11 71 6. Authorization Server Metadata . . . . . . . . . . . . . . . . 11 72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 73 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 12 74 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 75 7.2. OAuth Parameters . . . . . . . . . . . . . . . . . . . . 12 76 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 77 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 13 78 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 79 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 80 8.1. Framing . . . . . . . . . . . . . . . . . . . . . . . . . 13 81 8.2. WebAuthn . . . . . . . . . . . . . . . . . . . . . . . . 15 82 8.3. Handle Tokens . . . . . . . . . . . . . . . . . . . . . . 15 83 8.4. Warning Against Untrusted Scripts . . . . . . . . . . . . 15 84 8.5. Origin of Event and Authorization Server . . . . . . . . 16 85 8.6. Token Storage . . . . . . . . . . . . . . . . . . . . . . 16 86 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 87 10. Normative References . . . . . . . . . . . . . . . . . . . . 17 88 11. Informative References . . . . . . . . . . . . . . . . . . . 18 89 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19 90 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 93 1. Introduction 95 The OAuth 2.0 protocol flow for Single-page Applications (SPA) 96 defined in this memo, often referred to as the assisted token flow, 97 provides clients written in scripting languages, like JavaScript, 98 with a simplified integration (compared to the implicit or 99 authorization code flow) and ensures that end users are not 100 redirected away from the current page in order to obtain 101 authorization from the resource owner. The communication between the 102 client and the authorization server takes place within an HTML iframe 103 element or child window that is only displayed when interactive user 104 interaction is required; this is the case when authentication and/or 105 authorization are necessary. To communicate the result from this 106 iframe or child window to the client application, HTML's postMessage 107 interface is used instead of the redirection endpoint defined in 108 Section 3.1.2 of [RFC6749]. This difference is important for many 109 SPAs which take time to reload and may not be able to recreate the 110 same state prior to the user being redirected to the authorization 111 server. 113 Another goal of the assisted token flow is to simplify integration of 114 the client with the authorization server. Though [RFC6749] resulted 115 in a much simpler integration for client applications compared to its 116 predecessor, [RFC5849], developers still struggle with the many 117 inputs required to perform the various OAuth flows. For this reason, 118 the assisted token flow introduces a new endpoint called the assisted 119 token endpoint rather than extending and reusing the token endpoint 120 defined in Section 3.2 of [RFC6749]. As a result, client developers 121 do not need to specify a response_type parameter in the authorization 122 request. This coupled with the use of HTML's postMessage interface 123 for communication between the client and the authorization server 124 means that the redirect_uri and state parameters are also 125 unnecessary. Consequently, client developers only need to provide a 126 client_id, create a dynamic iframe or open a child window, and handle 127 the postMessage that is fired by the authorization server in order to 128 implement OAuth. 130 This interaction is shown in Figure 1. 132 +----------------------------+ +---------------+ 133 | Client | | Authorization | 134 | +--------------------------+ | Server | 135 | | +-----------+ | | 136 | |--(A)-------->| |--(B)-- Client ------>| | 137 | | | | Identifier | | 138 | | | Hidden | | | 139 | | | iframe |<-(C)-- HTML with ----| | 140 | |<-(D)- Token -| | postMessage | | 141 | | or | | including | | 142 | | error +-----------+ access token | | 143 | +--------------------------+ or error | | 144 | | | | 145 +----------------------------+ +---------------+ 147 Figure 1: Assisted Token Flow 149 The assisted token flow illustrated in Figure 1 includes the 150 following steps: 152 (A) The client creates a hidden iframe element using a scripting 153 language like JavaScript. The src attribute of this iframe is 154 the URL of the assisted token endpoint of the authorization 155 server. 157 (B) The query string of the src attribute on the iframe includes, at 158 a minimum, the client identifier. 160 (C) If the user is already logged in and has granted consent to the 161 client, the authorization server immediately returns an HTML 162 document that includes a script that is executing; this fires an 163 event which is communicated to the client using an HTML 164 window.postMessage. 166 (D) The client handles this event -- the payload of which is either 167 an access token or an error; the client then closes the dynamic 168 iframe without revealing it to the user. 170 If the resource owner has not authenticated or has not authorized the 171 client, then interaction between the resource owner and the 172 authorization server is required to obtain these. In such a case, 173 the HTML in step (C) of Figure 1 will include an error indicating 174 that user involvement is required. This will be handled by the 175 client in step (D) and login and/or consent will commence. This 176 process is illustrated in Figure 2. 178 +----------------------------+ +---------------+ 179 | Client | | Authorization | 180 | +--------------------------+ | Server | 181 | | +-----------+ Client | | 182 | |--(E)-------->| |--(F)-- Identifier -->| | 183 | | | Visible | | | 184 | | | iframe |--(G)-- User -------->| | 185 | | | or child | interaction | | 186 | |<-(I)- Token -| window | | | 187 | | | |<-(H)-- HTML with ----| | 188 | | +-----------+ postMessage | | 189 | +--------------------------+ including | | 190 | | access token | | 191 +----------------------------+ +---------------+ 193 Figure 2: Assisted Token Login and/or Consent Flow 195 The flow shown in Figure 2 includes the following steps: 197 (E) The client creates a "visible" iframe or pops open a child 198 window after receiving an indication from the authorization 199 server that user interaction is required. As in the previous 200 flow, the src attribute value of this iframe or the input to the 201 open method of the user agents's window object is the URL of the 202 authorization server's assisted token endpoint. 204 (F) The query string of this URL includes, at a minimum, the client 205 identifier. 207 (G) The authorization server prompts the resource owner to 208 authenticate and/or authorize the client. 210 (H) The authorization server returns an HTML document that includes 211 a script that is executed; this fires an event which is 212 communicated to the client using an HTML window.postMessage. 214 (I) The client handles this event -- the payload of which is an 215 access token; the client then closes the iframe or child window 216 that it previously opened to facilitate user interaction. 218 2. Terminology 220 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 221 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 222 "OPTIONAL" in this document are to be interpreted as described in 223 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 224 capitals, as shown here. 226 Handle Token 227 An opaque token that refers to internal data of the 228 authorization server (e.g., the user ID, scope of the token, 229 etc.) as described in Section 3.1 of [RFC6819]. 231 All other terms used in this document are as defined in [RFC6749]. 232 Unless otherwise noted, all the protocol parameter names and values 233 are case sensitive. 235 3. Assisted Token Endpoint 237 The means through which the client obtains the location of the 238 assisted token endpoint is either by using the authorization server's 239 metadata as set forth in Section 6, the service documentation, or 240 some other method that is beyond the scope of this specification. 242 The endpoint URI MAY include an "application/x-www-form-urlencoded" 243 formatted (per Appendix B of [RFC6749]) query component (see 244 Section 3.4 of [RFC3986]), which MUST be retained when adding 245 additional query parameters. The endpoint URI MUST NOT include a 246 fragment component. 248 Since requests to the assisted token endpoint result in the 249 transmission of clear-text credentials (in the HTTP request and 250 response), the authorization server MUST require the use of TLS as 251 described in Section 1.6 of [RFC6749] when sending requests to the 252 assisted token endpoint. 254 The client MUST use the HTTP "GET" method when making access token 255 requests to this endpoint. 257 Parameters sent without a value MAY be treated as if they were 258 omitted from the request. The authorization server MUST ignore 259 unrecognized request parameters. Request and response parameters 260 MUST NOT be included more than once. 262 After completing its interaction with the resource owner, the 263 authorization server will fire an event using the HTML postMessage 264 interface. This message MUST NOT be posted to all origins, denoted 265 by "*". Instead, the authorization server MUST post this message 266 only to the client's allowed origin(s) previously established with 267 the authorization server during the client registration process. 269 3.1. Access Token Scope 271 Like the authorization and token endpoints, the assisted token 272 endpoint allows the client to specify the scope of the access request 273 using the "scope" request parameter. In turn, the authorization 274 server uses the "scope" response parameter to inform the client of 275 the scope of the access token issued. Unlike the typical behavior of 276 those endpoints, however, access tokens issued by the authorization 277 server using the assisted token endpoint MUST use the client's pre- 278 configured scope or the authorization server's pre-defined default if 279 none have been configured for the client. 281 If the client did not include a "scope" request parameter or if the 282 issued access token scope is different from the one requested by the 283 client, the authorization server MUST include the "scope" response 284 parameter to inform the client of the actual scope granted. Even 285 when the scope of the issued access token is the same as the one 286 requested by the client, the authorization server SHOULD include the 287 "scope" response parameter. 289 The format, constraints, and grammar of the scope parameter value is 290 as defined in Section 3.3 of [RFC6749]. 292 The authorization server SHOULD NOT return an error if a scope has 293 not been pre-configured for the client; only if the authorization 294 server does not have a pre-defined default scope. 296 3.2. Cross-Origin Support 298 The assisted token endpoint MAY support CORS as defined in 299 [W3C.WD-cors-20120403]. 301 4. Protocol 303 4.1. Assisted Token Request 305 The assisted token request is an HTTP GET request constructed by the 306 client with the following parameters provided on the query string: 308 client_id 309 REQUIRED. The client identifier as described in Section 2.2 310 of [RFC6749]. 312 for_origin 313 OPTIONAL. The origin of the client in case multiple allowed 314 origins are configured with the authorization server and 315 support for user agents that do not support [CSP-2] but only 316 "X-Frame-Options" (as defined in [RFC7034]). See Section 8.1 317 for details. 319 prompt 320 OPTIONAL. Space delimited, case sensitive list of [ASCII] 321 string values that can be used to determine the login state 322 of the resource owner at the authorization server. The 323 defined values are: 325 none 326 The authorization server MUST NOT display any 327 authentication or consent user interface pages. An 328 error is returned if the user is not already 329 authenticated or if the client has not received 330 consent (either explicitly by the resource owner or 331 by the authorization server's configuration of the 332 client) or if the authorization server cannot fulfill 333 other conditions for processing. This can be used as 334 a method to probing for existing authentication and/ 335 or consent. 337 consent 338 The authorization server SHOULD prompt the user for 339 consent before returning information to the client. 340 If it cannot obtain consent, it MUST return an error. 342 Other values may be provided in this list; the authorization 343 server MUST ignore them without producing an error if it 344 cannot understand them. 346 scope 347 OPTIONAL. The scope of the access request as described in 348 Section 3.1. 350 4.2. Assisted Token Response 352 The response from the assisted token endpoint is an HTML document 353 that executes a script which invokes the HTML postMessage interface 354 to send a message to either the parent window (in the case shown in 355 Figure 1) or the opener. The origin that this event is posted to is 356 that of the client. The contents of this message is a JSON object 357 with the following fields: 359 access_token 360 REQUIRED. The access token issued by the authorization 361 server. 363 expires_in 364 RECOMMENDED. The lifetime in seconds of the access token. 366 scope 367 REQUIRED. The scope of the access token as described in 368 Section 3.1. 370 sub 371 RECOMMENDED. A locally unique and never reassigned 372 identifier within the authorization server for the user, 373 which is intended to be consumed by the client. The sub 374 value is a case sensitive string. 376 token_type 377 REQUIRED. The type of the token issued as described in 378 Section 7.1 of [RFC6749]. The value is case insensitive. 380 This JSON object MAY contain additional fields. If the client does 381 not understand or recognize such additional fields, it MUST ignore 382 them. 384 4.3. Error Response 386 As with a successful response, an error is returned to the client 387 using an the HTML postMessage interface. Such an error is returned 388 whenever the resource owner denies the access request or whenever the 389 request fails for reasons other than the origin of the client being 390 disallowed to frame the assisted token endpoint. The error message 391 includes a JSON object with the following fields: 393 error 394 REQUIRED. A single [ASCII] error code from the following: 396 invalid_request 397 The request is missing a required parameter, includes 398 an invalid parameter value, includes a parameter more 399 than once, or is otherwise malformed. 401 unauthorized_client 402 The client is not authorized to request an access 403 token using this method. 405 access_denied 406 The resource owner or authorization server denied the 407 request. 409 consent_required 410 The client includes a prompt value of consent, but 411 consent by the resource owner was required. 413 interaction_required 414 The client included a prompt value of none, but 415 either the user needed to authenticate or consent to 416 the client's access or some other requirement of the 417 authorization server prevented it from providing 418 access without some form of user interaction. 420 unsupported_response_type 421 The authorization server does not support obtaining 422 an access token using this method. 424 invalid_scope 425 The requested scope is invalid, unknown, or 426 malformed. 428 server_error 429 The authorization server encountered an unexpected 430 condition that prevented it from fulfilling the 431 request. (This error code is needed because a 500 432 Internal Server Error HTTP status code cannot be 433 returned to the client directly.) 435 temporarily_unavailable 436 The authorization server is currently unable to 437 handle the request due to a temporary overloading or 438 maintenance of the server. (This error code is 439 needed because a 503 Service Unavailable HTTP status 440 code cannot be returned to the client directly.) 442 Values for the "error" parameter MUST NOT include characters 443 outside the set %x20-21 / %x23-5B / %x5D-7E. 445 error_description 446 OPTIONAL. Human-readable [ASCII] text providing additional 447 information, used to assist the client developer in 448 understanding the error that occurred. Values for the 449 "error_description" parameter MUST NOT include characters 450 outside the set %x20-21 / %x23-5B / %x5D-7E. 452 error_uri 453 OPTIONAL. A URI identifying a human-readable web page with 454 information about the error, used to provide the client 455 developer with additional information about the error. 456 Values for the "error_uri" parameter MUST conform to the URI- 457 reference syntax and thus MUST NOT include characters outside 458 the set %x21 / %x23-5B / %x5D-7E. 460 5. Client Metadata 462 The authorization server MAY allow dynamic clients to request the use 463 of the assisted token flow when registering. Such a client may 464 indicate that it will interact with the authorization server using 465 the assisted token flow by including the string element 466 "urn:ietf:params:oauth:grant-type:assisted_token" in the array 467 associated with the "grant_types" metadata field sent to the client 468 registration endpoint (as defined in Section 3 of [RFC7591]). If the 469 authorization server allows the client to register with this grant 470 type, the "grant_types" included in the response MUST include the 471 value "urn:ietf:params:oauth:grant-type:assisted_token". The 472 inclusion of this value in the "grant_types" field is done despite 473 the fact that the client will not use this grant type at the token 474 endpoint but rather the assisted token endpoint (see Section 3). 476 If dynamic clients are allowed to register themselves with the 477 authorization server, then additional verification of the origins 478 include in the request MUST be performed in some manner. The way in 479 which this is accomplished by the authorization server is not defined 480 by this specification. Because this additional verification is 481 required and because clients using the assisted token flow are 482 typically ephemeral in nature, it is NOT RECOMMENDED that the 483 authorization server support dynamic client registration of the 484 "urn:ietf:params:oauth:grant-type:assisted_token" grant type. 486 The following client metadata field is defined by this specification. 487 It MAY be included in a registration request, as set forth in 488 Section 2 of [RFC7591]. 490 allowed_origins 491 Array of origin strings for use in sending messages from the 492 authorization server to the client using the HTML's 493 postMessage interface. 495 6. Authorization Server Metadata 497 Support for the assisted token flow SHOULD be declared in the 498 authorization server's metadata (as defined in [RFC8414]) with the 499 following metadata: 501 assisted_token_endpoint 502 RECOMMENDED. URL of the authorization server's assisted 503 token endpoint defined in Section 3. 505 grant_types_supported 506 RECOMMENDED. A JSON array specified in Section 2 of 507 [RFC8414] which SHOULD contain the value 508 "urn:ietf:params:oauth:grant-type:assisted_token" as defined 509 in Section 5. 511 7. IANA Considerations 513 7.1. OAuth URI Registration 515 This specification registers the following values in the IANA "OAuth 516 URI" registry (https://www.iana.org/assignments/oauth- 517 parameters/#uri) [IANA.OAuth.Parameters] established by [RFC6755]. 519 7.1.1. Registry Contents 521 * URN: urn:ietf:params:oauth:grant-type:assisted_token 523 * Common Name: Assisted token flow grant type for OAuth 2.0 525 * Change controller: CURITY: info@curity.io 527 * Specification Document: Section 5 of [[ this specification ]] 529 7.2. OAuth Parameters 531 This specification registers the following values in the IANA "OAuth 532 Parameter" registry (https://www.iana.org/assignments/oauth- 533 parameters/#parameters) [IANA.OAuth.Parameters] established by 534 [RFC6749]. 536 7.2.1. Registry Contents 538 * for_origin 540 * Parameter usage location: authorization request 542 * Change controller: CURITY: info@curity.io 544 * Specification Document: Section 4 of [[ this specification ]] 546 7.3. OAuth 2.0 Authorization Server Metadata 548 This specification registers the following values in the IANA "OAuth 549 2.0 Authorization Server Metadata" registry 550 (https://www.iana.org/assignments/oauth-parameters/#authorization- 551 server-metadata) [IANA.OAuth.Parameters] established by [RFC8414]. 553 7.3.1. Registry Contents 555 * Metadata name: assisted_token_endpoint 557 * Metadata Description: The Assisted Token Endpoint. 559 * Change controller: CURITY: info@curity.io 561 * Specification Document: Section 6 of [[ this specification ]] 563 8. Security Considerations 565 In addition to all the security considerations discussed in 566 [RFC6819], the following security considerations SHOULD be taken into 567 account. 569 8.1. Framing 571 Due to the use of an iframe to host the assisted token endpoint, the 572 authorization server MUST take precautions to ensure that only 573 trusted origins are allowed to frame it. The authorization server 574 MUST prevent any origin from framing the assisted token endpoint 575 except ones deemed trustworthy. This attestation may come byway of 576 explicit administrative action or automated techniques available to 577 the authorization server. Additional care is REQUIRED if dynamic 578 client registration is supported or clients may be registered in a 579 self-service manner. 581 One such mechanism that MAY be deployed is Content Security Policy 582 [CSP-2]. This protocol SHOULD be used on the assisted token endpoint 583 (and, if applicable, other endpoints used to authenticated the user 584 in a specific deployment) to prevent framing from unauthorized 585 origins. Using CSP allows the authorization server to specify 586 multiple origins in a single response header field and to constrain 587 these using flexible patterns (see [CSP-2] for details). This 588 standard provides a robust mechanism for protecting against click- 589 jacking by using policies that restrict the origin of frames (using 590 "frame-ancestors") together with those that restrict the sources of 591 scripts allowed to execute on an HTML page (by using "script-src"). 592 A non-normative example of such a policy is shown in the following 593 listing: 595 HTTP/1.1 200 OK 596 Content-Security-Policy: frame-ancestors https://a.example.org:8000 597 Content-Security-Policy: script-src 'self' 598 X-Frame-Options: ALLOW-FROM https://a.example.org:8000 599 ... 601 Figure 3: Example CSP that will help protect against click-jacking 603 Because some user agents do not support [CSP-2], this technique 604 SHOULD be combined with others. In particular, the authorization 605 server SHOULD return an "X-Frame-Options" response header on the 606 assisted token endpoint (and, if applicable, other endpoints used to 607 authenticate the user and authorize the client in a specific 608 deployment). As defined in [RFC7034], this header will cause user 609 agents that support it (but not CSP) to block framing from any origin 610 that is not specified in this header's value. Because this header's 611 value can only include one origin, the framer is RECOMMENDED to use 612 the "for_origin" parameter (as specified in Section 4.1) with its own 613 origin as the value. 615 Some user agents do not support [RFC7034] nor [CSP-2]. Therefore, 616 the authorization server SHOULD include a frame-busting script like 617 that shown in Figure 7 of [FRAME-BUSTING]. Such a script would use 618 JavaScript to break out of any unauthorized origin that is framing 619 the assisted token endpoint. The authorization server MAY simply 620 break out of all frames in case [RFC7034] and [CSP-2] are unsupported 621 by the user agent, though this would render the assisted token flow 622 non-functional. The choice of whether or not this drastic 623 countermeasure should be employed depends on the user agents being 624 targeted in a certain deployment. 626 When the authorization server and client are provided by separate 627 parties, it is important that the resource owner is able to 628 distinguish the two. One safe way of doing so is by examination of 629 the user agent's address bar by the resource owner where the validity 630 of the certificate and location can be verified. In such situations, 631 whenever user interaction is required, the client MUST open the 632 assisted token endpoint in a new browser window rather than a hidden 633 iframe. The authorization server MUST take measures deemed 634 appropriate in a deployment to ensure that the client has not framed 635 the user's manual interaction; however, the necessity for interactive 636 user authentication and/or consent SHOULD be possible for the client 637 to determine in a hidden iframe. 639 8.2. WebAuthn 641 [WebAuthn] MAY be used to ensure that the user is authenticated to 642 the authorization server in a safe manner. This protocol offers 643 authentication processes that are resistant to man-in-the-middle 644 attacks. The API defined by this standard can be used to verify that 645 user authentication is performed at the expected origin. This is 646 superior to manual verification of the origin in the address bar of 647 the browser by the resource owner. It also provides a mechanism to 648 restrict the client framing the assisted token endpoint to be in the 649 same origin. When it is not, the use of [WebAuthn] will force the 650 client to use a separate window for user authentication. 652 8.3. Handle Tokens 654 Because the client applications that use the assisted token flow are 655 written in scripting languages like JavaScript and are hosted in Web 656 pages, users may keep such applications open in their user agents for 657 a prolonged period of time. During such period, the token issued to 658 the client may expire or be revoked. To ensure that such expired 659 tokens left remnant in the user agent are benign, a Handle Token 660 SHOULD always be issued by the assisted token endpoint. This ensures 661 that no identity data is exposed (even when the token is not yet 662 expired) and that a revoked token does not increase risks. 664 8.4. Warning Against Untrusted Scripts 666 As admitted in Section 8 of [RFC6454], preventing exfiltration of 667 cookies, tokens, and other such credentials in web browsers has 668 historically proven difficult to implement. Instead, the same-origin 669 policy has emerged as the cornerstone of security for such user 670 agents. Using this security model, it is not possible to prevent 671 access to a token issued to a client if that client includes 672 nefarious scripts from untrustworthy sources that have access to the 673 Document Object Model (DOM) where the token is stored. For this 674 reason, the authorization server MUST warn client application 675 developers who interact with the assisted token endpoint _not_ to use 676 untrusted scripts in their applications. This warning SHOULD at 677 least be conveyed through the documentation but MAY also be provided 678 through other mechanisms. 680 8.5. Origin of Event and Authorization Server 682 As described in Section 4.1, the authorization server will return an 683 access token to the client using HTML's postMessage interface. The 684 receiver of this message is provided with an event object that 685 contains an origin property. A client application MUST compare this 686 with that of the authorization server before consuming the message. 687 Otherwise, it runs the risk of processing messages posted from 688 untrusted origins. An example of a proper message handler is shown 689 in the following non-normative, JavaScript listing: 691 700 Figure 4: Comparing the origin of the postMessage event with that 701 of the authorization server 703 8.6. Token Storage 705 Most client applications that use the assisted token flow will 706 maintain the access token issued by the authorization server in a 707 persisted state; this will commonly be an HTTP cookie or local 708 storage. This is necessary, for instance, to create a pleasing user 709 experience when a user navigates away from the application in their 710 web browser and then returns. To ensure that the token is stored 711 safely, the authorization server MAY provide application developers 712 with guidance in the accompanying documentation on how to safely 713 persist tokens. The authorization server MAY also provide script 714 libraries that perform this action according to best common 715 practices. The authorization server MAY also store the token in an 716 HTTP cookie in its own DNS domain (rather than that of the client) 717 using the assisted token endpoint's path. In some cases, this would 718 elevate any storage requirements from the client application 719 developer. Besides simplifying the programming model for developers, 720 this technique allows the authorization server to check the validity 721 of the token and determine if the token has expired or if the 722 associated grant has been revoked in subsequent requests to the 723 assisted token endpoint; this will be possible because the requests 724 might include the token in the HTTP Cookie request header. In such 725 cases, the authorization server can take the appropriate action, such 726 as authenticating the user anew or request consent, before issuing a 727 new token. If the token is stored by the application, however, this 728 kind of verification cannot be performed by the authorization server 729 without an explicit request to validate a stored token. 731 9. Privacy Considerations 733 In some deployments, the assisted token endpoint may be served from a 734 distinct domain from that of the client. In such cases, the client 735 will be a third-party domain, and the resource owner's user agent may 736 prevent the authorization server from storing any third-party 737 cookies. If the authorization server requires state to be persisted 738 when performing the assisted token flow, it SHOULD provide a privacy- 739 preserving mechanism to store and retrieve its state even when the 740 assisted token endpoint is hosted on a distinct domain from that of 741 the client. The technical details of how to accomplish this are 742 implementation specific, and are beyond the scope of this 743 specification. If the authorization server does not support clients 744 that are hosted from a third-party domain, it MUST indicate this to 745 the client through some mechanism (e.g., its associated 746 documentation). 748 10. Normative References 750 [ASCII] American National Standards Institute, "Coded Character 751 Set -- 7-bit American Standard Code for Information 752 Interchange", ANSI X3.4, 1986. 754 [IANA.OAuth.Parameters] 755 IANA, "OAuth Parameters", 756 . 758 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 759 Requirement Levels", BCP 14, RFC 2119, 760 DOI 10.17487/RFC2119, March 1997, 761 . 763 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 764 Resource Identifier (URI): Generic Syntax", STD 66, 765 RFC 3986, DOI 10.17487/RFC3986, January 2005, 766 . 768 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 769 RFC 6749, DOI 10.17487/RFC6749, October 2012, 770 . 772 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 773 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 774 RFC 7591, DOI 10.17487/RFC7591, July 2015, 775 . 777 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 778 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 779 May 2017, . 781 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 782 Authorization Server Metadata", RFC 8414, 783 DOI 10.17487/RFC8414, June 2018, 784 . 786 11. Informative References 788 [CSP-2] West, M., Barth, A., and D. Veditz, "Content Security 789 Policy Level 2", July 2015, . 791 [FRAME-BUSTING] 792 Rydstedt, G., Bursztein, E., Boneh, D., and C. Jackson, 793 "Busting frame busting: a study of clickjacking 794 vulnerabilities at popular sites", July 2010, 795 . 798 [RFC5849] Hammer-Lahav, E., Ed., "The OAuth 1.0 Protocol", RFC 5849, 799 DOI 10.17487/RFC5849, April 2010, 800 . 802 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 803 DOI 10.17487/RFC6454, December 2011, 804 . 806 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 807 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 808 . 810 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 811 Threat Model and Security Considerations", RFC 6819, 812 DOI 10.17487/RFC6819, January 2013, 813 . 815 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame- 816 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013, 817 . 819 [W3C.WD-cors-20120403] 820 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 821 Web Consortium LastCall WD-cors-20120403, 3 April 2012, 822 . 824 [WebAuthn] Balfanz, D., Czeskis, A., Hodges, J., Jones, J.C., Jones, 825 M., Kumar, A., Liao, A., Lindemann, R., and E. Lundberg, 826 "Web Authentication: An API for accessing Public Key 827 Credentials", World Wide Web Consortium 828 (W3C) Recommendation, 4 March 2019, 829 . 831 Appendix A. Acknowledgements 833 The following individuals contributed ideas, feedback, and wording to 834 this specification: 836 Mark Dobrinic, Karl McGuinness, Renato Athaydes, Daniel Lindau, Louis 837 Jannett 839 Appendix B. Document History 841 [[ to be removed by the RFC editor before publication as an RFC ]] 843 This section is to be removed before publishing as an RFC. 845 -05 847 * Clarified text and figures 849 * Added note about DCR not being recommended 851 * Fixed change controller for IANA registry entries 853 * Clarified and reorganized framing and address bar security 854 considerations based on L. Lannett's feedback 856 * Added WebAuthn security consideration 858 -04 860 * Updated IANA references to use the "short version" without file 861 extension or extra path information. 863 * Updated repository reference. 865 -03 867 * Updated repository links. 869 -02 871 * Updated section 8.1 with regards to the CSP headers. 873 * Updated authorization server metadata in section 6. 875 * Updated IANA Considerations section 7. 877 -01 879 * Updated to v. 3 XML format 881 -00 883 * Initial draft. 885 Authors' Addresses 887 Jacob Ideskog 888 Curity AB 890 Email: jacob@curity.io 892 Travis Spencer 893 Curity AB 895 Email: travis@curity.io