idnits 2.17.1 draft-sakimura-oauth-wmrm-00.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 : ---------------------------------------------------------------------------- ** There are 23 instances of too long lines in the document, the longest one being 44 characters in excess of 72. == There are 6 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: It is expected to be used when the End User is in the "authenticated" state at the Authorization Server so that prompt=none succeeds. Authorization Server SHOULD not send Set-Cookie header in the response. -- The document date (October 18, 2015) is 3112 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC7591' is defined on line 713, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 6819 Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group T. Yamaguchi 3 Internet-Draft DeNA Co.,Ltd. 4 Intended status: Standards Track N. Sakimura, Ed. 5 Expires: April 20, 2016 Nomura Research Institute 6 N. Matake 7 GREE 8 October 18, 2015 10 OAuth 2.0 Web Message Response Mode 11 draft-sakimura-oauth-wmrm-00 13 Abstract 15 This specification defines a new response mode for RFC6749 that uses 16 HTML5 Web Messaging (a.k.a window.postMessage()) instead of the 17 redirect for the Authorization Response from the Authorization 18 Endpoint. It defines two modes: simple mode and relay mode. Relay 19 mode can be used to protect the access token in the implicit grant 20 case by confining it within the origins of authorization server or 21 resource server and preventing it from being read by the client. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on April 20, 2016. 40 Copyright Notice 42 Copyright (c) 2015 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 59 2. Terms and definitions . . . . . . . . . . . . . . . . . . . . 3 60 2.1. Main Window . . . . . . . . . . . . . . . . . . . . . . . 3 61 2.2. Authenticated Window . . . . . . . . . . . . . . . . . . 3 62 2.3. Unauthenticated Window . . . . . . . . . . . . . . . . . 3 63 2.4. Message Targeted Window . . . . . . . . . . . . . . . . . 3 64 3. Symbols and abbreviated terms . . . . . . . . . . . . . . . . 4 65 4. Protocol Flows . . . . . . . . . . . . . . . . . . . . . . . 4 66 4.1. Simple mode . . . . . . . . . . . . . . . . . . . . . . . 4 67 4.1.1. Simple mode:no prompt . . . . . . . . . . . . . . . . 4 68 4.1.2. Simple mode:with prompt . . . . . . . . . . . . . . . 5 69 4.2. Relay Mode . . . . . . . . . . . . . . . . . . . . . . . 5 70 4.2.1. Relay mode:no prompt . . . . . . . . . . . . . . . . 5 71 4.2.2. Simple mode:with prompt . . . . . . . . . . . . . . . 7 72 5. Authorization . . . . . . . . . . . . . . . . . . . . . . . . 7 73 5.1. Authorization Request . . . . . . . . . . . . . . . . . . 7 74 5.2. Authorization Response . . . . . . . . . . . . . . . . . 12 75 6. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 15 76 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 16 77 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 78 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 79 10. Revision History . . . . . . . . . . . . . . . . . . . . . . 16 80 11. Normative References . . . . . . . . . . . . . . . . . . . . 16 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 83 1. Introduction 85 This specification defines a new response mode for RFC6749 that uses 86 HTML5 Web Messaging (a.k.a window.postMessage()) instead of the 87 redirect for the Authorization Response from the Authorization 88 Endpoint. 90 This specification provides two modes 92 1. Simple mode returns the Authorization Response directly to the 93 client web page. 95 2. Relay mode does not return the Authorization Response directly to 96 the client web page but returns it to a child frame created by 97 the client web page via the client web page. 99 1.1. Requirements Language 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in RFC 2119 [RFC2119]. 105 2. Terms and definitions 107 For the purposes of this specification, the following terms and 108 definitions apply. 110 2.1. Main Window 112 window object that the client created 114 2.2. Authenticated Window 116 A window object in the iframe created by the Main Window(Section 2.1) 117 or its child iframe. 119 It is used to relay the Authorization Request from the client to the 120 Authorization Server. The request is expected to have prompt=none 121 defined in OpenID Connect Core. 123 It is expected to be used when the End User is in the "authenticated" 124 state at the Authorization Server so that prompt=none succeeds. 125 Authorization Server SHOULD not send Set-Cookie header in the 126 response. 128 2.3. Unauthenticated Window 130 A popup window object created by the Main Window(Section 2.1), via 131 window.open(), to send the Authorization Request to the Authorization 132 Endpoint. 134 It is used when the user is not in the Authenticated state on the 135 Authorization Server or the client has not received the authorization 136 yet. 138 2.4. Message Targeted Window 140 A window object in the iframe created by the Main Window(Section 2.1) 141 that receives Authorization Response in Relay Mode (Section 4.2). 143 3. Symbols and abbreviated terms 145 Authz Authorization 147 4. Protocol Flows 149 As stated above, this response mode provides two modes. 151 4.1. Simple mode 153 In the Simple mode, the protocol flows as follows. 155 4.1.1. Simple mode:no prompt 157 The authorization request and response sequence when using 158 Authenticated Window will be like this. 160 1.Create 2.Authz 161 +--------+ iframe +---------------+ Request +--------------+ 162 | +-----------> +----------> | 163 | Main | |Authenticated | |Authorization | 164 | Window | |Window | |Endpoint | 165 | <-----------+ <----------+ | 166 +--------+ 3.Send +---------------+ 3.Authz +--------------+ 167 web message Response 168 as Authz via JavaScript code 169 Response 171 Figure 1: Simple mode (Authenticated Window) 173 Below is the description of the each steps in the above sequence 174 diagram. 176 1. Main Window creates the Unauthenticated Windows as an iframe to 177 send Authorization Request and sets the URI of the Authorization 178 Request as the src value of the iframe. 180 2. The Authorization Request that is specified by the src value of 181 the iframe of the Unauthenticated Window, which was set by the 182 Main Window, is sent to Authorization Endpoint. 184 3. Authorization Server determines if the End User is logged in 185 state and checks if it can return the Authorization Response 186 without interacting with the User. If it determines that it can, 187 it will render the HTML5 that includes the JavaScript code that 188 sends the Authorization Response. 190 4. The Authorization Response is passed to the Main Window from the 191 Unauthenticated Window using Web Message through the JavaScript. 193 4.1.2. Simple mode:with prompt 195 When using Unauthenticated Window, the Authorization sequence would 196 be as follows: 198 1.window.open() 2.Authz 199 +--------+ +---------------+ Request +--------------+ 200 | +-----------> +----------> +-----+ 201 | Main | |Unauthenticated| |Authorization | |3.User 202 | Window | |Window | |Endpoint | |Interaction 203 | <-----------+ <----------+ <-----+ 204 +--------+ 5.Send +---------------+ 4.Authz +--------------+ 205 web message Response 206 as Authz via JavaScript code 207 Response 209 Figure 2: Simple mode (Unauthenticated Window) 211 It is almost identical to the sequence that used Authenticated Window 212 except: 214 1. The way the window object that is used to send the Authorization 215 Request is different. i.e., iframe v.s. window.open(). 217 2. End User may interact with the Authorization Server before the 218 Authorization Response is being sent. 220 3. The relationship of the window that accesses the Authorization 221 Endpoint and the Main Window is different. i.e., window.parent 222 v.s. window.opener. 224 4.2. Relay Mode 226 The protocol flow of the Relay mode will be as follows. 228 4.2.1. Relay mode:no prompt 230 The authorization sequence that uses Unauthenticated Window will be: 232 +-----------------------+ 233 | | 234 +-------> Message Target Window <-------+ 235 | | | | 236 | +-----------------------+ 7.Send web message as 237 1.Create iframe Authz Response 238 | | 239 +--+-----+ 2.Create iframe +--------+-----+ +---------+ 240 | +----------------------> Un- +---------> | 241 | Main | | Authenticated| 3.Authz | Authz | 242 | Window <----------------------+ Window | Request | Endpoint| 243 | | 5.Send web message | | | | 244 +------+-+ as Relay Request +--^-------^---+ +---+-----+ 245 | | | | 246 +---------------------------+ +-----------------+ 247 6.Relay Response 4.Authz Response 248 by Javascript code 250 Figure 3: Relay Mode (Authenticated Window) 252 1. Create iframe (Message Target Window) through Main Window. It 253 will receive the Authorization Response. 255 2. Create iframe (Unautenticated Window) through Main Window. The 256 Authorization Request URI is set as the src value of the iframe. 257 This iframe is used to send the Authorization Request. 259 3. Authorization Request specified in the src value by the Main 260 Window is sent to the Authorization Endpoint. 262 4. Authorization Server checks the login status of the End User and 263 whether it can return the Authorization Response without the End 264 User interaction. If it is, then it will render the HTML5 that 265 includes JavaScript code that sends Relay Request and 266 Authorization Response. 268 5. Unauthenticated Window sends Relay Request as a Web Message to 269 the Main Window throught the JavaScript code. 271 6. Main Window returns the Relay Response. 273 7. Unauthenticated window obtains the window object of the Message 274 Target Window via the MessageEvent object in the Relay Response 275 and send Authorization Response as a Web Message. 277 4.2.2. Simple mode:with prompt 279 The authorization sequence that uses the Authenticated Window follows 280 almost the same sequence. 282 +-----------------------+ 283 | | 284 +-------> Message Target Window <-------+ 285 | | | | 286 | +-----------------------+ 7.Send web message as 287 1.window.open() Authz Response 288 | | 289 +--+-----+ 2.Create iframe +--------+-----+ +---------+ 290 | +----------------------> Un- +---------> +---+ 291 | Main | | authenticated| 3.Authz | Authz | |3.User 292 | Window <----------------------+ Window | Request | Endpoint| |Interaction 293 | | 5.Send web message | | | <---+ 294 +------+-+ as Relay Request +--^-------^---+ +---+-----+ 295 | | | | 296 +---------------------------+ +-----------------+ 297 6.Relay Response 4.Authz Response 298 by Javascript code 300 Figure 4: Relay Mode (Authenticated Window) 302 The differences are, just like in the Simple Mode: 304 1. The way the window object that is used to send the Authorization 305 Request is different. i.e., iframe v.s. window.open(). 307 2. End User may interact with the Authorization Server before the 308 Authorization Response is being sent. 310 3. The relationship of the window that accesses the Authorization 311 Endpoint and the Main Window is different. i.e., window.parent 312 v.s. window.opener. 314 5. Authorization 316 5.1. Authorization Request 318 Web Messaging Response Mode defines the following Authorization 319 Request parameters. 321 response_mode REQUIRED. ASCII string "web_message". 323 redirect_uri REQUIRED. The origin URI of the URI of the Main 324 Window. If web_message_uri is not specified, Authorization 325 Responsewill be sent to the origin specifed by the redirect_uri. 327 web_message_uri OPTIONAL. The origin URI that Message Target Window 328 references. When it is specified, Authorization Response will not 329 be returned to the redirect_uri but Relay Request/Responses are 330 used. 332 web_message_target OPTIONAL or REQUIRED. The DOM id value that 333 points to the Message Target Window. REQUIRED if web_message_uri 334 is used. Authorization Response obtains the window object of 335 Message Target Window via Relay Request/Relay Response with the 336 Main Window. If it is not specified, Authorization Responsewill 337 be sent to the calling window. 339 Main WIndow creates an event listener before sending the 340 Authorization Request, and sends Authorization Request that uses 341 these parameters to either Authenticated Window or Unauthenticated 342 Window. 344 The following example depicts the Authorization Request to the 345 Unauthenticated Window in the Simple Mode. 347 function connect(request, callback) { 348 var authorizationEndpoint = (function(url) { 349 var a = document.createElement("a"); 350 a.setAttribute("href", url); 351 return a; 352 })("https://as.example.com/authorize"); 353 authorizationEndpoint.search = buildQueryString(request, { 354 "redirect_uri": location.origin, 355 "response_mode": "web_message" 356 }); 357 window.addEventListener("message", function(evt) { 358 if (evt.origin != "https://as.example.com") 359 return; 360 if (!evt.data.type) 361 return; 362 switch (evt.data.type) { 363 case "authorization_response": 364 evt.source.close(); 365 (evt.data.error) ? callback(null, evt.data): callback(evt.data, null); 366 window.removeEventListener("message", arguments.callee, false); 367 break; 368 default: 369 } 370 }, false); 371 var unauthentecatedWindow = window.open(authorizationEndpoint.getAttribute("href"), "_new"); 372 return unauthenticatedWindow; 373 } 375 Figure 5: Registration of the event listener (Unauthenticated Window 376 in the Simple mode) 378 Actual authorization request will look like: 380 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 381 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom 382 &response_mode=web_message HTTP/1.1 383 Host: as.example.com:443 385 Figure 6: Authorization Request 387 Following depicts the Authorization Request to Authenticated Window 388 in Relay Mode. 390 function getConnectedStatus(request, callback) { 391 var authorizationEndpoint = (function(url) { 392 var a = document.createElement("a"); 393 a.setAttribute("href", url); 394 return a; 395 })("https://as.example.com/authorize"); 396 authorizationEndpoint.search = buildQueryString(request, { 397 "redirect_uri": location.origin, 398 "response_mode": "web_message", 399 "web_message_uri": "https://api.example.com", 400 "web_message_target": "apiFrame" 401 }); 402 window.addEventListener("message", function(evt) { 403 if (evt.origin != "https://as.example.com") 404 return; 405 if (!evt.data.type) 406 return; 407 switch (evt.data.type) { 408 case "relay_request": 409 evt.source.postMessage("message", { 410 type: "relay_response" 411 }, false); 412 (evt.data.error) ? callback(null, evt.data): callback(evt.data, null); 413 window.removeEventListener("message", arguments.callee, false); 414 break; 415 default: 416 } 417 }, false); 418 var authenticatedWindow = (function(url) { 419 var iframe = document.getElementById("apiFrame"); 420 if (!iframe) { 421 iframe = document.createElement("iframe"); 422 iframe.setAttribute("width", 0); 423 iframe.setAttribute("height", 0); 424 } 425 iframe.setAttribute("href", url); 426 return iframe.contentWindow; 427 })(authorizationEndpoint.getAttribute("href")); 428 return authenticatedWindow; 429 } 431 Figure 7: Registration of the event listener that receives 432 Authorization Response (Authenticated Window in Relay Mode) 434 Actual authorization request will look like: 436 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 437 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom 438 &response_mode=web_message 439 &web_message_uri=https%3A%2F%2Fapi%2Eexample%2Ecom 440 &web_message_target=apiFrame HTTP/1.1 441 Host: as.example.com:443 443 Figure 8: Authorization Request (Authenticated Window) 445 Message Target Window in Relay mode creates an event listener to 446 receive Authorization Response. 448 (function(window, document, undefined) { 449 window.addEventListener("message", function(evt) { 450 if (evt.origin != "https://as.example.com") 451 return; 452 if (!evt.data.type) 453 return; 454 switch (evt.data.type) { 455 case "authorization_response": 456 if (evt.source.parent == evt.source) { 457 evt.source.close(); 458 } 459 processAuthorizationResponse(evt.data); 460 break; 461 default: 462 } 463 }, false); 464 })(this, this.document); 466 Figure 9: Receiving Authorization Response in Message Target Window 468 Web Messages between Authenticated Window or Unauthenticated Window 469 and Main Window or Message Target Window takes the following fields. 471 +----------+--------+----------+------------------------------------+ 472 | field | type | required | description | 473 +----------+--------+----------+------------------------------------+ 474 | type | string | true | prepare_authorization_response OR | 475 | | | | authorization_response | 476 | response | object | false | used when | 477 | | | | type=authorization_response | 478 +----------+--------+----------+------------------------------------+ 480 Table 1: Web Messages Structure 482 Type attribute values are described in the following table. 484 +------+-------------+-------------+-------------------+------------+ 485 | mode | sender | receiver | type | descriptio | 486 | | | | | n | 487 +------+-------------+-------------+-------------------+------------+ 488 | Simp | Authenticat | Main Window | authorization_res | response | 489 | le | ed Window | | ponse | including | 490 | Mode | or Unauthen | | | Authorizat | 491 | | ticated | | | ion | 492 | | Window | | | Response | 493 | Rela | Authenticat | Main Window | relay_request | Request to | 494 | y | ed Window | | | get the | 495 | Mode | or Unauthen | | | reference | 496 | | ticated | | | to the | 497 | | Window | | | window | 498 | | | | | object of | 499 | | | | | the Main | 500 | | | | | Window | 501 | Rela | Main Window | Authenticat | relay_response | The | 502 | y | | ed Window | | response | 503 | Mode | | or Unauthen | | to the rel | 504 | | | ticated | | ay_request | 505 | | | Window | | | 506 | Rela | Authenticat | Message | authorization_res | Response | 507 | y | ed Window | Target | ponse | that | 508 | Mode | or Unauthen | Window | | includes A | 509 | | ticated | | | uthorizati | 510 | | Window | | | on | 511 | | | | | Response | 512 +------+-------------+-------------+-------------------+------------+ 514 Table 2: Type attributes 516 5.2. Authorization Response 518 Authorization Server needs to render the JavaScript code to return 519 the Authorization Response when response_mode was web_message at the 520 time of Authorization Request at Authorization Endpoint. 522 Authorization Server MUST verify the following before returning 523 Authorization Response. 525 (1) The origin specified by redirect_uri is white-listed. 527 (2) The origin specified by web_message_uri is white-listed. 529 If verified, it MUST return the response including the JavaScript 530 code such as: 532 533 535 536 Authorization Response 537 539 540 584 586 588 Figure 10: Authorization Response with web messaging response mode 590 If web_message_uri and web_message_target request parameters are 591 specified in Authorization Request, window object sent by 592 postMessage() is not to be set to window.opener or window.parent but 593 to a specific frame, responses such as follows should be returned. 595 596 598 599 Authorization Response 600 602 603 650 652 654 Figure 11: Authorization Response w/ web messaging response mode and 655 web_message_target 657 6. Client Metadata 659 The following field is added to RFC7519. 661 +------------------+-------+----------------------------------------+ 662 | field | type | description | 663 +------------------+-------+----------------------------------------+ 664 | web_message_uris | array | List of origins that are allowed as | 665 | | | web_message_uri in the Authorization | 666 | | | Request. | 667 +------------------+-------+----------------------------------------+ 669 Table 3: Client Metadata Addition 671 7. IANA Considerations 673 Followings are added to OAuth Dynamic Client Registration Metadata 674 Registry. 676 o Client Metadata Name: "web_message_uris" 678 o Client Metadata Description: List of origins that are allowed as 679 web_message_uri in the Authorization Request. 681 o Change Controller: IESG 683 o Specification Document(s): This document 685 8. Security Considerations 687 In addition to the all the security considerations discussed in OAuth 688 2.0 [RFC6819], the following security considerations SHOULD be taken 689 into account. 691 9. Acknowledgements 693 Follwoing people contributed to the creation of this document . 695 10. Revision History 697 -00 699 o Initial Draft. 701 11. Normative References 703 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 704 Requirement Levels", BCP 14, RFC 2119, 705 DOI 10.17487/RFC2119, March 1997, 706 . 708 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 709 Threat Model and Security Considerations", RFC 6819, 710 DOI 10.17487/RFC6819, January 2013, 711 . 713 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 714 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 715 RFC 7591, DOI 10.17487/RFC7591, July 2015, 716 . 718 [Web.Messaging] 719 Hickson, I., "HTML5 Web Messaging", May 2015. 721 Authors' Addresses 723 Toru Yamaguchi 724 DeNA Co.,Ltd. 725 2-21-1, Shibuya 726 Shibuya-ku, Tokyo 150-8510 727 Japan 729 Phone: +81-3-4366-7243 730 Email: toru.yamaguchi@dena.com 731 URI: http://dena.com 733 Nat Sakimura (editor) 734 Nomura Research Institute 735 1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg. 736 Chiyoda-ku, Tokyo 100-0005 737 Japan 739 Phone: +81-3-5533-2111 740 Email: n-sakimura@nri.co.jp 741 URI: http://nat.sakimura.org/ 743 Nov Matake 744 GREE 746 Email: nov@matake.jp 747 URI: http://matake.jp