idnits 2.17.1 draft-ideskog-assisted-token-01.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 (24 November 2019) is 1609 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: 27 May 2020 24 November 2019 7 OAuth 2.0 Assisted Token 8 draft-ideskog-assisted-token-01 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 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on 27 May 2020. 39 Copyright Notice 41 Copyright (c) 2019 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 46 license-info) in effect on the date of publication of this document. 47 Please review these documents carefully, as they describe your rights 48 and restrictions with respect to this document. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 54 3. Assisted Token Endpoint . . . . . . . . . . . . . . . . . . . 5 55 3.1. Access Token Scope . . . . . . . . . . . . . . . . . . . 6 56 3.2. Cross-Origin Support . . . . . . . . . . . . . . . . . . 7 57 4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 4.1. Assisted Token Request . . . . . . . . . . . . . . . . . 7 59 4.2. Assisted Token Response . . . . . . . . . . . . . . . . . 8 60 4.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 61 5. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 10 62 6. Authorization Server Metadata . . . . . . . . . . . . . . . . 10 63 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 64 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 11 65 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 11 66 7.2. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 11 67 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 11 68 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 69 8.1. Framing . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 8.2. Handle Tokens . . . . . . . . . . . . . . . . . . . . . . 13 71 8.3. Warning Against Untrusted Scripts . . . . . . . . . . . . 13 72 8.4. Origin of Event and Authorization Server . . . . . . . . 13 73 8.5. Token Storage . . . . . . . . . . . . . . . . . . . . . . 14 74 8.6. Visibility of User Agent's Address Bar . . . . . . . . . 14 75 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15 76 10. Normative References . . . . . . . . . . . . . . . . . . . . 15 77 11. Informative References . . . . . . . . . . . . . . . . . . . 16 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17 79 Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 82 1. Introduction 84 The OAuth 2.0 protocol flow for Single-page Applications (SPA) 85 defined in this memo, often referred to as the assisted token flow, 86 provides clients written in scripting languages, like JavaScript, 87 with a simplified integration (compared to the implicit or 88 authorization code flow) and ensures that end users are not 89 redirected away from the current page in order to obtain 90 authorization from the resource owner. The communication between the 91 client and the authorization server takes place within an HTML iframe 92 element or child window that is only displayed when interactive user 93 interaction is required; this is the case when authentication and/or 94 authorization are necessary. To communicate the result from this 95 iframe or child window to the client application, HTML's postMessage 96 interface is used instead of the redirection endpoint defined in 97 Section 3.1.2 of [RFC6749]. This difference is important for many 98 SPAs which take time to reload and may not be able to recreate the 99 same state prior to the user being redirected to the authorization 100 server. 102 Another goal of the assisted token flow is to simplify integration of 103 the client with the authorization server. Though [RFC6749] resulted 104 in a much simpler integration for client applications compared to its 105 predecessor, [RFC5849], developers still struggle with the many 106 inputs required to perform the various OAuth flows. For this reason, 107 the assisted token flow introduces a new endpoint called the assisted 108 token endpoint rather than extending and reusing the token endpoint 109 defined in Section 3.2 of [RFC6749]. As a result, client developers 110 do not need to specify a response_type parameter in the authorization 111 request. This coupled with the use of HTML's postMessage interface 112 for communication between the client and the authorization server 113 means that the redirect_uri and state parameters are also 114 unnecessary. Consequently, client developers only need to provide a 115 client_id, create a dynamic iframe or open a child window, and handle 116 the postMessage that is fired by the authorization server in order to 117 implement OAuth. 119 This interaction is shown in Figure 1. 121 +----------------------------+ +---------------+ 122 | Client | | Authorization | 123 | +--------------------------+ | Server | 124 | | +-----------+ | | 125 | |--(A)-------->| |--(B)-- Client ------>| | 126 | | | | Identifier | | 127 | | | Hidden | | | 128 | | | iframe |<-(C)-- HTML with ----| | 129 | |<-(D)- Token -| | postMessage | | 130 | | or | | including | | 131 | | error +-----------+ access token | | 132 | +--------------------------+ or error | | 133 | | | | 134 +----------------------------+ +---------------+ 136 Figure 1: Assisted Token Flow 138 The assisted token flow illustrated in Figure 1 includes the 139 following steps: 141 (A) The client creates a hidden iframe element using a scripting 142 language like JavaScript. The src attribute of this iframe is 143 the URL of the assisted token endpoint of the authorization 144 server. 146 (B) The query string of the src attribute on the iframe includes, at 147 a minimum, the client identifier. 149 (C) If the user is already logged in and has granted consent to the 150 client, the authorization server immediately returns an HTML 151 document that includes a script that is executing; this fires an 152 event which is communicated to the client using an HTML 153 window.postMessage. 155 (D) The client handles this event -- the payload of which is either 156 an access token or an error; the client then closes the dynamic 157 iframe without revealing it to the user. 159 If the resource owner has not authenticated or has not authorized the 160 client, then interaction between the resource owner and the 161 authorization server is required to obtain these. In such a case, 162 the HTML in step (C) of Figure 1 will include an error indicating 163 that user involvement is required. This will be handled by the 164 client in step (D) and login and/or consent will commence. This 165 process is illustrated in Figure 2. 167 +----------------------------+ +---------------+ 168 | Client | | Authorization | 169 | +--------------------------+ | Server | 170 | | +-----------+ Client | | 171 | |--(E)-------->| |--(F)-- Identifier -->| | 172 | | | Visible | | | 173 | | | iframe |--(G)-- User -------->| | 174 | | | or child | authenticates | | 175 | |<-(I)- Token -| window | | | 176 | | | |<-(H)-- HTML with ----| | 177 | | +-----------+ postMessage | | 178 | +--------------------------+ including | | 179 | | access token | | 180 +----------------------------+ +---------------+ 182 Figure 2: Assisted Token Login and/or Consent Flow 184 The flow shown in Figure 2 includes the following steps: 186 (E) The client creates a "visible" iframe or pops open a child 187 window after receiving an indication from the authorization 188 server that user interaction is required. As in the previous 189 flow, the src attribute value of this iframe or the input to the 190 open method of the user agents's window object is the URL of the 191 authorization server's assisted token endpoint. 193 (F) The query string of this URL includes, at a minimum, the client 194 identifier. 196 (G) The authorization server prompts the resource owner to 197 authenticate and/or authorize the client. 199 (H) The authorization server returns an HTML document that includes 200 a script that is executed; this fires an event which is 201 communicated to the client using an HTML window.postMessage. 203 (I) The client handles this event -- the payload of which is an 204 access token; the client then closes the iframe or child window 205 that it previously opened to facilitate user interaction. 207 2. Terminology 209 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 210 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 211 "OPTIONAL" in this document are to be interpreted as described in 212 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 213 capitals, as shown here. 215 Handle Token 216 An opaque token that refers to internal data of the 217 authorization server (e.g., the user ID, scope of the token, 218 etc.) as described in Section 3.1 of [RFC6819]. 220 All other terms used in this document are as defined in [RFC6749]. 221 Unless otherwise noted, all the protocol parameter names and values 222 are case sensitive. 224 3. Assisted Token Endpoint 226 The means through which the client obtains the location of the 227 assisted token endpoint is either by using the authorization server's 228 metadata as set forth in Section 6, the service documentation, or 229 some other method that is beyond the scope of this specification. 231 The endpoint URI MAY include an "application/x-www-form-urlencoded" 232 formatted (per Appendix B of [RFC6749]) query component (see 233 Section 3.4 of [RFC3986]), which MUST be retained when adding 234 additional query parameters. The endpoint URI MUST NOT include a 235 fragment component. 237 Since requests to the assisted token endpoint result in the 238 transmission of clear-text credentials (in the HTTP request and 239 response), the authorization server MUST require the use of TLS as 240 described in Section 1.6 of [RFC6749] when sending requests to the 241 assisted token endpoint. 243 The client MUST use the HTTP "GET" method when making access token 244 requests to this endpoint. 246 Parameters sent without a value MAY be treated as if they were 247 omitted from the request. The authorization server MUST ignore 248 unrecognized request parameters. Request and response parameters 249 MUST NOT be included more than once. 251 After completing its interaction with the resource owner, the 252 authorization server will fire an event using the HTML postMessage 253 interface. This message MUST NOT be posted to all origins, denoted 254 by "*". Instead, the authorization server MUST post this message 255 only to the client's allowed origin(s) previously established with 256 the authorization server during the client registration process. 258 3.1. Access Token Scope 260 Like the authorization and token endpoints, the assisted token 261 endpoint allows the client to specify the scope of the access request 262 using the "scope" request parameter. In turn, the authorization 263 server uses the "scope" response parameter to inform the client of 264 the scope of the access token issued. Unlike the typical behavior of 265 those endpoints, however, access tokens issued by the authorization 266 server using the assisted token endpoint MUST use the client's pre- 267 configured scope or the authorization server's pre-defined default if 268 none have been configured for the client. 270 If the client did not include a "scope" request parameter or if the 271 issued access token scope is different from the one requested by the 272 client, the authorization server MUST include the "scope"response 273 parameter to inform the client of the actual scope granted. Even 274 when the scope of the issued access token is the same as the one 275 requested by the client, the authorization server SHOULD include the 276 "scope" response parameter. 278 The format, constraints, and grammar of the scope parameter value is 279 as defined in Section 3.3 of [RFC6749]. 281 The authorization server SHOULD NOT return an error if a scope has 282 not been pre-configured for the client; only if the authorization 283 server does not have a pre-defined default scope. 285 3.2. Cross-Origin Support 287 The assisted token endpoint MAY support CORS as defined in 288 [W3C.WD-cors-20120403]. 290 4. Protocol 292 4.1. Assisted Token Request 294 The assisted token request is an HTTP GET request constructed by the 295 client with the following parameters provided on the query string: 297 client_id 298 REQUIRED. The client identifier as described in Section 2.2 299 of [RFC6749]. 301 for_origin 302 OPTIONAL. The origin of the client in case multiple allowed 303 origins are configured with the authorization server and 304 support for user agents that do not support [CSP-2] but only 305 "X-Frame-Options" (as defined in [RFC7034]). See Section 8.1 306 for details. 308 prompt 309 OPTIONAL. Space delimited, case sensitive list of [ASCII] 310 string values that can be used to determine the login state 311 of the resource owner at the authorization server. The 312 defined values are: 314 none 315 The authorization server MUST NOT display any 316 authentication or consent user interface pages. An 317 error is returned if the user is not already 318 authenticated or if the client has not received 319 consent (either explicitly by the resource owner or 320 by the authorization server's configuration of the 321 client) or if the authorization server cannot fulfill 322 other conditions for processing. This can be used as 323 a method to probing for existing authentication and/ 324 or consent. 326 consent 327 The authorization server SHOULD prompt the user for 328 consent before returning information to the client. 329 If it cannot obtain consent, it MUST return an error. 331 Other values may be provided in this list; the authorization 332 server MUST ignore them without producing an error if it 333 cannot understand them. 335 scope 336 OPTIONAL. The scope of the access request as described in 337 Section 3.1. 339 4.2. Assisted Token Response 341 The response from the assisted token endpoint is an HTML document 342 that executes a script which invokes the HTML postMessage interface 343 to send a message to either the parent window (in the case shown in 344 Figure 1) or the opener (in the case illustrated in Figure 2). The 345 origin that this event is posted to is that of the client. The 346 contents of this message is a JSON object with the following fields: 348 access_token 349 REQUIRED. The access token issued by the authorization 350 server. 352 expires_in 353 RECOMMENDED. The lifetime in seconds of the access token. 355 scope 356 REQUIRED. The scope of the access token as described in 357 Section 3.1. 359 sub 360 RECOMMENDED. A locally unique and never reassigned 361 identifier within the authorization server for the user, 362 which is intended to be consumed by the client. The sub 363 value is a case sensitive string. 365 token_type 366 REQUIRED. The type of the token issued as described in 367 Section 7.1 of [RFC6749]. Value is case insensitive. 369 4.3. Error Response 371 As with a successful response, an error is returned to the client 372 using an the HTML postMessage interface. Such an error is returned 373 whenever the resource owner denies the access request or whenever the 374 request fails for reasons other than the origin of the client being 375 disallowed to frame the assisted token endpoint. The error message 376 includes a JSON object with the following fields: 378 error 379 REQUIRED. A single [ASCII] error code from the following: 381 invalid_request 382 The request is missing a required parameter, includes 383 an invalid parameter value, includes a parameter more 384 than once, or is otherwise malformed. 386 unauthorized_client 387 The client is not authorized to request an access 388 token using this method. 390 access_denied 391 The resource owner or authorization server denied the 392 request. 394 consent_required 395 The client includes a prompt value of consent, but 396 consent by the resource owner was required. 398 interaction_required 399 The client included a prompt value of none, but 400 either the user needed to authenticate or consent to 401 the client's access or some other requirement of the 402 authorization server prevented it from providing 403 access without some form of user interaction. 405 unsupported_response_type 406 The authorization server does not support obtaining 407 an access token using this method. 409 invalid_scope 410 The requested scope is invalid, unknown, or 411 malformed. 413 server_error 414 The authorization server encountered an unexpected 415 condition that prevented it from fulfilling the 416 request. (This error code is needed because a 500 417 Internal Server Error HTTP status code cannot be 418 returned to the client directly in the child frame.) 420 temporarily_unavailable 421 The authorization server is currently unable to 422 handle the request due to a temporary overloading or 423 maintenance of the server. (This error code is 424 needed because a 503 Service Unavailable HTTP status 425 code cannot be returned to the client directly in the 426 child frame.) 428 Values for the "error" parameter MUST NOT include characters 429 outside the set %x20-21 / %x23-5B / %x5D-7E. 431 error_description 432 OPTIONAL. Human-readable [ASCII] text providing additional 433 information, used to assist the client developer in 434 understanding the error that occurred. Values for the 435 "error_description" parameter MUST NOT include characters 436 outside the set %x20-21 / %x23-5B / %x5D-7E. 438 error_uri 439 OPTIONAL. A URI identifying a human-readable web page with 440 information about the error, used to provide the client 441 developer with additional information about the error. 442 Values for the "error_uri" parameter MUST conform to the URI- 443 reference syntax and thus MUST NOT include characters outside 444 the set %x21 / %x23-5B / %x5D-7E. 446 5. Client Metadata 448 The authorization server MAY allow dynamic clients to request the use 449 of the assisted token flow when registering. Such a client may 450 indicate that it will interact with the authorization server using 451 the assisted token flow by including the string element 452 "urn:ietf:params:oauth:grant-type:assisted_token" in the array 453 associated with the "grant_types" metadata field sent to the client 454 registration endpoint (as defined in Section 3 of [RFC7591]). If the 455 authorization server allows the client to register with this grant 456 type, the "grant_types" included in the response MUST include the 457 value "urn:ietf:params:oauth:grant-type:assisted_token". The 458 inclusion of this value in the "grant_types" field is done despite 459 the fact that the client will not use this grant type at the token 460 endpoint but rather the assisted token endpoint (see Section 3). 462 The following client metadata field is defined by this specification. 463 It MAY be included in a registration request, as set forth in 464 Section 2 of [RFC7591]. 466 allowed_origins 467 Array of origin strings for use in sending messages from the 468 authorization server to the client using the HTML's 469 postMessage interface. 471 6. Authorization Server Metadata 473 Support for the assisted token flow MUST be declared in the 474 authorization server's metadata (as defined in [RFC8414]) with the 475 following metadata: 477 assisted_token_endpoint 478 REQUIRED. URL of the authorization server's assisted token 479 endpoint defined in Section 3. 481 grant_types_supported 482 REQUIRED. A JSON array specified in Section 2 of [RFC8414] 483 which should contain the value "urn:ietf:params:oauth:grant- 484 type:assisted_token" as defined in Section 5. 486 7. IANA Considerations 488 7.1. OAuth URI Registration 490 This specification registers the following values in the IANA "OAuth 491 URI" registry (https://www.iana.org/assignments/oauth-parameters/ 492 oauth-parameters.xhtml#uri) [IANA.OAuth.Parameters] established by 493 [RFC6755]. 495 7.1.1. Registry Contents 497 * URN: urn:ietf:params:oauth:grant-type:assisted_token 499 * Common Name: Assisted token flow grant type for OAuth 2.0 501 * Change controller: IESG 503 * Specification Document: Section 5 of [[ this specification ]] 505 7.2. OAuth 2.0 Authorization Server Metadata 507 This specification registers the following values in the IANA "OAuth 508 2.0 Authorization Server Metadata" registry 509 (https://www.iana.org/assignments/oauth-parameters/oauth- 510 parameters.xhtml#authorization-server-metadata) 511 [IANA.OAuth.Parameters] established by [RFC8414]. 513 7.2.1. Registry Contents 515 * Metadata name: assisted_token_endpoint 517 * Metadata Description: The Assisted Token Endpoint. 519 * Change controller: IESG 521 * Specification Document: Section 6 of [[ this specification ]] 523 8. Security Considerations 525 In addition to all the security considerations discussed in 526 [RFC6819], the following security considerations SHOULD be taken into 527 account. 529 8.1. Framing 531 Due to the use of an iframe to host the assisted token endpoint, the 532 authorization server MUST take precautions to ensure that only 533 trusted origins are allowed to frame it. The authorization server 534 MUST prevent any origin from framing the assisted token endpoint 535 except ones that an administrator has explicitly allowed. It may do 536 this in any manner that is available to the application. 538 One such mechanism that MAY be deployed is Content Security Policy 539 [CSP-2]. This protocol SHOULD be used on the assisted token endpoint 540 (and, if applicable, other endpoints used to authenticated the user 541 in a specific deployment) to prevent framing from unauthorized 542 origins. Using CSP allows the authorization server to specify 543 multiple origins in a single response header field and to constrain 544 these using flexible patterns (see [CSP-2] for details). This 545 standard provides a robust mechanism for protecting against click- 546 jacking when combining policies that restrict "child-src" with the 547 sources of scripts that are allowed to execute by using "script-src" 548 policies. 550 Because some user agents do not support [CSP-2], this technique 551 SHOULD be combined with others. In particular, the authorization 552 server SHOULD return an "X-Frame-Options" response header on the 553 assisted token endpoint (and, if applicable, other endpoints used to 554 authenticate the user in a specific deployment). As defined in 555 [RFC7034], this header will cause user agents that support it (but 556 not CSP) to block framing from any origin that is not specified in 557 this header's value. Because this header's value can only include 558 one origin, the framer should use the "for_origin" parameter (as 559 specified in Section 4.1) to include its own origin. 561 Some user agents do not support [RFC7034] nor [CSP-2]. Therefore, 562 the authorization server SHOULD include a frame-busting script like 563 that shown in Figure 7 of [FRAME-BUSTING]. Such a script would use 564 JavaScript to break out of any unauthorized origin that is framing 565 the assisted token endpoint. The authorization server MAY simply 566 break out of all frames in case [RFC7034] and [CSP-2] are unsupported 567 by the user agent, though this would render the assisted token flow 568 non-functional. The choice of whether or not this drastic 569 countermeasure should be employed depends on the user agents being 570 targetted in a certain deployment. 572 8.2. Handle Tokens 574 Because the client applications that use the assisted token flow are 575 written in scripting languages like JavaScript and are hosted in Web 576 pages, users may keep such applications open in their user agents for 577 a prolonged period of time. During such period, the token issued to 578 the client may expire or be revoked. To ensure that such expired 579 tokens left remnant in the user agent are benign, a Handle Token 580 SHOULD always be issued by the assisted token endpoint. This ensures 581 that no identity data is exposed (even when the token is not yet 582 expired) and that a revoked token does not increase risks. 584 8.3. Warning Against Untrusted Scripts 586 As admitted in Section 8 of [RFC6454], preventing exfiltration of 587 cookies, tokens, and other such credentials in web browsers has 588 historically proven difficult to implement. Instead, the same-origin 589 policy has emerged as the cornerstone of security for such user 590 agents. Using this security model, it is not possible to prevent 591 access to a token issued to a client if that client includes 592 nefarious scripts from untrustworthy sources that have access to the 593 Document Object Model (DOM) where the token is stored. For this 594 reason, the authorization server MUST warn client application 595 developers who interact with the assisted token endpoint _not_ to use 596 untrusted scripts in their applications. This warning SHOULD at 597 least be conveyed through the documentation but MAY also be provided 598 through other mechanisms. 600 8.4. Origin of Event and Authorization Server 602 As described in Section 4.1, the authorization server will return an 603 access token to the client using HTML's postMessage interface. The 604 receiver of this message is provided with an event object that 605 contains an origin property. A client application MUST compare this 606 with that of the authorization server before consuming the message. 607 Otherwise, it runs the risk of processing messages posted from 608 untrusted origins. An example of a proper message handler is shown 609 in the following non-normative, JavaScript listing: 611 619 Figure 3: Comparing the origin of the postMessage event with that 620 of the authorization server 622 8.5. Token Storage 624 Most client applications that use the assisted token flow will 625 maintain the access token issued by the authorization server in a 626 persisted state; this will commonly be an HTTP cookie or local 627 storage. This is necessary, for instance, to create a pleasing user 628 experience when a user navigates away from the application in their 629 web browser and then returns. To ensure that the token is stored 630 safely, the authorization server MAY provide application developers 631 with guidance in the accompanying documentation on how to safely 632 persist tokens. The authorization server MAY also provide script 633 libraries that perform this action according to best common 634 practices. The authorization server MAY also store the token in an 635 HTTP cookie in its own DNS domain (rather than that of the client) 636 using the assisted token endpoint's path. In some cases, this would 637 elevate any storage requirements from the client application 638 developer. Besides simplifying the programming model for developers, 639 this technique allows the authorization server to check the validity 640 of the token and determine if the token has expired or if the 641 associated grant has been revoked in subsequent requests to the 642 assisted token endpoint; this will be possible because the requests 643 will include the token in the HTTP Cookie request header. In such 644 cases, the authorization server can take the appropriate action, such 645 as authenticating the user anew or request consent, before issuing a 646 new token. If the token is stored by the application, however, this 647 kind of verification cannot be performed by the authorization server 648 without an explicit request to validate a stored token. 650 8.6. Visibility of User Agent's Address Bar 652 When the authorization server and client are provided by separate 653 parties, it is important that the resource owner is able to 654 distinguish the two. The only safe way of doing so is by examination 655 of the user agent's address bar where the validity of the certificate 656 and location can be made. In such situations, whenever user 657 interaction is required, the client SHOULD open the assisted token 658 endpoint in a new browser window rather than a hidden iframe. The 659 authorization serer MAY take any measures deemed appropriate in a 660 deployment to ensure that the client has not framed the user's manual 661 interaction; however, the necessity for interactive user 662 authentication and/or consent SHOULD be possible for the client to 663 determine in a hidden iframe. 665 9. Privacy Considerations 667 In some deployments, the assisted token endpoint may be served from a 668 distinct domain from that of the client. In such cases, the client 669 will be a third-party domain, and the resource owner's user agent may 670 prevent the authorization server from storing any third-party 671 cookies. If the authorization server requires state to be persisted 672 when performing the assisted token flow, it SHOULD provide a privacy- 673 preserving mechanism to store and retrieve its state even when the 674 assisted token endpoint is hosted on a distinct domain from that of 675 the client. The technical details of how to accomplish this are 676 implementation specific, and are beyond the scope of this 677 specification. If the authorization server does not support clients 678 that are hosted from a third-party domain, it MUST indicate this to 679 the client through some mechanism (e.g., its associated 680 documentation). 682 10. Normative References 684 [ASCII] American National Standards Institute, "Coded Character 685 Set -- 7-bit American Standard Code for Information 686 Interchange", ANSI X3.4, 1986. 688 [IANA.OAuth.Parameters] 689 IANA, "OAuth Parameters", 690 . 692 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 693 Requirement Levels", BCP 14, RFC 2119, 694 DOI 10.17487/RFC2119, March 1997, 695 . 697 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 698 Resource Identifier (URI): Generic Syntax", STD 66, 699 RFC 3986, DOI 10.17487/RFC3986, January 2005, 700 . 702 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 703 RFC 6749, DOI 10.17487/RFC6749, October 2012, 704 . 706 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 707 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 708 RFC 7591, DOI 10.17487/RFC7591, July 2015, 709 . 711 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 712 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 713 May 2017, . 715 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 716 Authorization Server Metadata", RFC 8414, 717 DOI 10.17487/RFC8414, June 2018, 718 . 720 11. Informative References 722 [CSP-2] West, M., Barth, A., and D. Veditz, "Content Security 723 Policy Level 2", July 2015, . 725 [FRAME-BUSTING] 726 Rydstedt, G., Bursztein, E., Boneh, D., and C. Jackson, 727 "Busting frame busting: a study of clickjacking 728 vulnerabilities at popular sites", July 2010, 729 . 732 [RFC5849] Hammer-Lahav, E., Ed., "The OAuth 1.0 Protocol", RFC 5849, 733 DOI 10.17487/RFC5849, April 2010, 734 . 736 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 737 DOI 10.17487/RFC6454, December 2011, 738 . 740 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 741 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 742 . 744 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 745 Threat Model and Security Considerations", RFC 6819, 746 DOI 10.17487/RFC6819, January 2013, 747 . 749 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame- 750 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013, 751 . 753 [W3C.WD-cors-20120403] 754 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 755 Web Consortium LastCall WD-cors-20120403, 3 April 2012, 756 . 758 Appendix A. Acknowledgements 760 The following individuals contributed ideas, feedback, and wording to 761 this specification: 763 Mark Dobrinic, Karl McGuinness, Renato Athaydes, Daniel Lindau 765 Appendix B. Document History 767 [[ to be removed by the RFC editor before publication as an RFC ]] 769 This section is to be removed before publishing as an RFC. 771 -01 773 * Updated to v. 3 XML format 775 -00 777 * Initial draft. 779 Authors' Addresses 781 Jacob Ideskog 782 Curity AB 784 Email: jacob@curity.io 786 Travis Spencer 787 Curity AB 789 Email: travis@curity.io