OAuth Working Group T. Yamaguchi
Internet-Draft DeNA Co.,Ltd.
Intended status: Standards Track N. Sakimura, Ed.
Expires: April 20, 2016 Nomura Research Institute
N. Matake
GREE
October 18, 2015
OAuth 2.0 Web Message Response Mode
draft-sakimura-oauth-wmrm-00
Abstract
This specification defines a new response mode for RFC6749 that uses
HTML5 Web Messaging (a.k.a window.postMessage()) instead of the
redirect for the Authorization Response from the Authorization
Endpoint. It defines two modes: simple mode and relay mode. Relay
mode can be used to protect the access token in the implicit grant
case by confining it within the origins of authorization server or
resource server and preventing it from being read by the client.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 20, 2016.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
Yamaguchi, et al. Expires April 20, 2016 [Page 1]
Internet-Draft oauth-wmrm October 2015
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
2. Terms and definitions . . . . . . . . . . . . . . . . . . . . 3
2.1. Main Window . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Authenticated Window . . . . . . . . . . . . . . . . . . 3
2.3. Unauthenticated Window . . . . . . . . . . . . . . . . . 3
2.4. Message Targeted Window . . . . . . . . . . . . . . . . . 3
3. Symbols and abbreviated terms . . . . . . . . . . . . . . . . 4
4. Protocol Flows . . . . . . . . . . . . . . . . . . . . . . . 4
4.1. Simple mode . . . . . . . . . . . . . . . . . . . . . . . 4
4.1.1. Simple mode:no prompt . . . . . . . . . . . . . . . . 4
4.1.2. Simple mode:with prompt . . . . . . . . . . . . . . . 5
4.2. Relay Mode . . . . . . . . . . . . . . . . . . . . . . . 5
4.2.1. Relay mode:no prompt . . . . . . . . . . . . . . . . 5
4.2.2. Simple mode:with prompt . . . . . . . . . . . . . . . 7
5. Authorization . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Authorization Request . . . . . . . . . . . . . . . . . . 7
5.2. Authorization Response . . . . . . . . . . . . . . . . . 12
6. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 15
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 16
8. Security Considerations . . . . . . . . . . . . . . . . . . . 16
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16
10. Revision History . . . . . . . . . . . . . . . . . . . . . . 16
11. Normative References . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction
This specification defines a new response mode for RFC6749 that uses
HTML5 Web Messaging (a.k.a window.postMessage()) instead of the
redirect for the Authorization Response from the Authorization
Endpoint.
This specification provides two modes
1. Simple mode returns the Authorization Response directly to the
client web page.
Yamaguchi, et al. Expires April 20, 2016 [Page 2]
Internet-Draft oauth-wmrm October 2015
2. Relay mode does not return the Authorization Response directly to
the client web page but returns it to a child frame created by
the client web page via the client web page.
1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
2. Terms and definitions
For the purposes of this specification, the following terms and
definitions apply.
2.1. Main Window
window object that the client created
2.2. Authenticated Window
A window object in the iframe created by the Main Window(Section 2.1)
or its child iframe.
It is used to relay the Authorization Request from the client to the
Authorization Server. The request is expected to have prompt=none
defined in OpenID Connect Core.
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.
2.3. Unauthenticated Window
A popup window object created by the Main Window(Section 2.1), via
window.open(), to send the Authorization Request to the Authorization
Endpoint.
It is used when the user is not in the Authenticated state on the
Authorization Server or the client has not received the authorization
yet.
2.4. Message Targeted Window
A window object in the iframe created by the Main Window(Section 2.1)
that receives Authorization Response in Relay Mode (Section 4.2).
Yamaguchi, et al. Expires April 20, 2016 [Page 3]
Internet-Draft oauth-wmrm October 2015
3. Symbols and abbreviated terms
Authz Authorization
4. Protocol Flows
As stated above, this response mode provides two modes.
4.1. Simple mode
In the Simple mode, the protocol flows as follows.
4.1.1. Simple mode:no prompt
The authorization request and response sequence when using
Authenticated Window will be like this.
1.Create 2.Authz
+--------+ iframe +---------------+ Request +--------------+
| +-----------> +----------> |
| Main | |Authenticated | |Authorization |
| Window | |Window | |Endpoint |
| <-----------+ <----------+ |
+--------+ 3.Send +---------------+ 3.Authz +--------------+
web message Response
as Authz via JavaScript code
Response
Figure 1: Simple mode (Authenticated Window)
Below is the description of the each steps in the above sequence
diagram.
1. Main Window creates the Unauthenticated Windows as an iframe to
send Authorization Request and sets the URI of the Authorization
Request as the src value of the iframe.
2. The Authorization Request that is specified by the src value of
the iframe of the Unauthenticated Window, which was set by the
Main Window, is sent to Authorization Endpoint.
3. Authorization Server determines if the End User is logged in
state and checks if it can return the Authorization Response
without interacting with the User. If it determines that it can,
it will render the HTML5 that includes the JavaScript code that
sends the Authorization Response.
Yamaguchi, et al. Expires April 20, 2016 [Page 4]
Internet-Draft oauth-wmrm October 2015
4. The Authorization Response is passed to the Main Window from the
Unauthenticated Window using Web Message through the JavaScript.
4.1.2. Simple mode:with prompt
When using Unauthenticated Window, the Authorization sequence would
be as follows:
1.window.open() 2.Authz
+--------+ +---------------+ Request +--------------+
| +-----------> +----------> +-----+
| Main | |Unauthenticated| |Authorization | |3.User
| Window | |Window | |Endpoint | |Interaction
| <-----------+ <----------+ <-----+
+--------+ 5.Send +---------------+ 4.Authz +--------------+
web message Response
as Authz via JavaScript code
Response
Figure 2: Simple mode (Unauthenticated Window)
It is almost identical to the sequence that used Authenticated Window
except:
1. The way the window object that is used to send the Authorization
Request is different. i.e., iframe v.s. window.open().
2. End User may interact with the Authorization Server before the
Authorization Response is being sent.
3. The relationship of the window that accesses the Authorization
Endpoint and the Main Window is different. i.e., window.parent
v.s. window.opener.
4.2. Relay Mode
The protocol flow of the Relay mode will be as follows.
4.2.1. Relay mode:no prompt
The authorization sequence that uses Unauthenticated Window will be:
Yamaguchi, et al. Expires April 20, 2016 [Page 5]
Internet-Draft oauth-wmrm October 2015
+-----------------------+
| |
+-------> Message Target Window <-------+
| | | |
| +-----------------------+ 7.Send web message as
1.Create iframe Authz Response
| |
+--+-----+ 2.Create iframe +--------+-----+ +---------+
| +----------------------> Un- +---------> |
| Main | | Authenticated| 3.Authz | Authz |
| Window <----------------------+ Window | Request | Endpoint|
| | 5.Send web message | | | |
+------+-+ as Relay Request +--^-------^---+ +---+-----+
| | | |
+---------------------------+ +-----------------+
6.Relay Response 4.Authz Response
by Javascript code
Figure 3: Relay Mode (Authenticated Window)
1. Create iframe (Message Target Window) through Main Window. It
will receive the Authorization Response.
2. Create iframe (Unautenticated Window) through Main Window. The
Authorization Request URI is set as the src value of the iframe.
This iframe is used to send the Authorization Request.
3. Authorization Request specified in the src value by the Main
Window is sent to the Authorization Endpoint.
4. Authorization Server checks the login status of the End User and
whether it can return the Authorization Response without the End
User interaction. If it is, then it will render the HTML5 that
includes JavaScript code that sends Relay Request and
Authorization Response.
5. Unauthenticated Window sends Relay Request as a Web Message to
the Main Window throught the JavaScript code.
6. Main Window returns the Relay Response.
7. Unauthenticated window obtains the window object of the Message
Target Window via the MessageEvent object in the Relay Response
and send Authorization Response as a Web Message.
Yamaguchi, et al. Expires April 20, 2016 [Page 6]
Internet-Draft oauth-wmrm October 2015
4.2.2. Simple mode:with prompt
The authorization sequence that uses the Authenticated Window follows
almost the same sequence.
+-----------------------+
| |
+-------> Message Target Window <-------+
| | | |
| +-----------------------+ 7.Send web message as
1.window.open() Authz Response
| |
+--+-----+ 2.Create iframe +--------+-----+ +---------+
| +----------------------> Un- +---------> +---+
| Main | | authenticated| 3.Authz | Authz | |3.User
| Window <----------------------+ Window | Request | Endpoint| |Interaction
| | 5.Send web message | | | <---+
+------+-+ as Relay Request +--^-------^---+ +---+-----+
| | | |
+---------------------------+ +-----------------+
6.Relay Response 4.Authz Response
by Javascript code
Figure 4: Relay Mode (Authenticated Window)
The differences are, just like in the Simple Mode:
1. The way the window object that is used to send the Authorization
Request is different. i.e., iframe v.s. window.open().
2. End User may interact with the Authorization Server before the
Authorization Response is being sent.
3. The relationship of the window that accesses the Authorization
Endpoint and the Main Window is different. i.e., window.parent
v.s. window.opener.
5. Authorization
5.1. Authorization Request
Web Messaging Response Mode defines the following Authorization
Request parameters.
response_mode REQUIRED. ASCII string "web_message".
Yamaguchi, et al. Expires April 20, 2016 [Page 7]
Internet-Draft oauth-wmrm October 2015
redirect_uri REQUIRED. The origin URI of the URI of the Main
Window. If web_message_uri is not specified, Authorization
Responsewill be sent to the origin specifed by the redirect_uri.
web_message_uri OPTIONAL. The origin URI that Message Target Window
references. When it is specified, Authorization Response will not
be returned to the redirect_uri but Relay Request/Responses are
used.
web_message_target OPTIONAL or REQUIRED. The DOM id value that
points to the Message Target Window. REQUIRED if web_message_uri
is used. Authorization Response obtains the window object of
Message Target Window via Relay Request/Relay Response with the
Main Window. If it is not specified, Authorization Responsewill
be sent to the calling window.
Main WIndow creates an event listener before sending the
Authorization Request, and sends Authorization Request that uses
these parameters to either Authenticated Window or Unauthenticated
Window.
The following example depicts the Authorization Request to the
Unauthenticated Window in the Simple Mode.
Yamaguchi, et al. Expires April 20, 2016 [Page 8]
Internet-Draft oauth-wmrm October 2015
function connect(request, callback) {
var authorizationEndpoint = (function(url) {
var a = document.createElement("a");
a.setAttribute("href", url);
return a;
})("https://as.example.com/authorize");
authorizationEndpoint.search = buildQueryString(request, {
"redirect_uri": location.origin,
"response_mode": "web_message"
});
window.addEventListener("message", function(evt) {
if (evt.origin != "https://as.example.com")
return;
if (!evt.data.type)
return;
switch (evt.data.type) {
case "authorization_response":
evt.source.close();
(evt.data.error) ? callback(null, evt.data): callback(evt.data, null);
window.removeEventListener("message", arguments.callee, false);
break;
default:
}
}, false);
var unauthentecatedWindow = window.open(authorizationEndpoint.getAttribute("href"), "_new");
return unauthenticatedWindow;
}
Figure 5: Registration of the event listener (Unauthenticated Window
in the Simple mode)
Actual authorization request will look like:
GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom
&response_mode=web_message HTTP/1.1
Host: as.example.com:443
Figure 6: Authorization Request
Following depicts the Authorization Request to Authenticated Window
in Relay Mode.
Yamaguchi, et al. Expires April 20, 2016 [Page 9]
Internet-Draft oauth-wmrm October 2015
function getConnectedStatus(request, callback) {
var authorizationEndpoint = (function(url) {
var a = document.createElement("a");
a.setAttribute("href", url);
return a;
})("https://as.example.com/authorize");
authorizationEndpoint.search = buildQueryString(request, {
"redirect_uri": location.origin,
"response_mode": "web_message",
"web_message_uri": "https://api.example.com",
"web_message_target": "apiFrame"
});
window.addEventListener("message", function(evt) {
if (evt.origin != "https://as.example.com")
return;
if (!evt.data.type)
return;
switch (evt.data.type) {
case "relay_request":
evt.source.postMessage("message", {
type: "relay_response"
}, false);
(evt.data.error) ? callback(null, evt.data): callback(evt.data, null);
window.removeEventListener("message", arguments.callee, false);
break;
default:
}
}, false);
var authenticatedWindow = (function(url) {
var iframe = document.getElementById("apiFrame");
if (!iframe) {
iframe = document.createElement("iframe");
iframe.setAttribute("width", 0);
iframe.setAttribute("height", 0);
}
iframe.setAttribute("href", url);
return iframe.contentWindow;
})(authorizationEndpoint.getAttribute("href"));
return authenticatedWindow;
}
Figure 7: Registration of the event listener that receives
Authorization Response (Authenticated Window in Relay Mode)
Actual authorization request will look like:
Yamaguchi, et al. Expires April 20, 2016 [Page 10]
Internet-Draft oauth-wmrm October 2015
GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom
&response_mode=web_message
&web_message_uri=https%3A%2F%2Fapi%2Eexample%2Ecom
&web_message_target=apiFrame HTTP/1.1
Host: as.example.com:443
Figure 8: Authorization Request (Authenticated Window)
Message Target Window in Relay mode creates an event listener to
receive Authorization Response.
(function(window, document, undefined) {
window.addEventListener("message", function(evt) {
if (evt.origin != "https://as.example.com")
return;
if (!evt.data.type)
return;
switch (evt.data.type) {
case "authorization_response":
if (evt.source.parent == evt.source) {
evt.source.close();
}
processAuthorizationResponse(evt.data);
break;
default:
}
}, false);
})(this, this.document);
Figure 9: Receiving Authorization Response in Message Target Window
Web Messages between Authenticated Window or Unauthenticated Window
and Main Window or Message Target Window takes the following fields.
+----------+--------+----------+------------------------------------+
| field | type | required | description |
+----------+--------+----------+------------------------------------+
| type | string | true | prepare_authorization_response OR |
| | | | authorization_response |
| response | object | false | used when |
| | | | type=authorization_response |
+----------+--------+----------+------------------------------------+
Table 1: Web Messages Structure
Type attribute values are described in the following table.
Yamaguchi, et al. Expires April 20, 2016 [Page 11]
Internet-Draft oauth-wmrm October 2015
+------+-------------+-------------+-------------------+------------+
| mode | sender | receiver | type | descriptio |
| | | | | n |
+------+-------------+-------------+-------------------+------------+
| Simp | Authenticat | Main Window | authorization_res | response |
| le | ed Window | | ponse | including |
| Mode | or Unauthen | | | Authorizat |
| | ticated | | | ion |
| | Window | | | Response |
| Rela | Authenticat | Main Window | relay_request | Request to |
| y | ed Window | | | get the |
| Mode | or Unauthen | | | reference |
| | ticated | | | to the |
| | Window | | | window |
| | | | | object of |
| | | | | the Main |
| | | | | Window |
| Rela | Main Window | Authenticat | relay_response | The |
| y | | ed Window | | response |
| Mode | | or Unauthen | | to the rel |
| | | ticated | | ay_request |
| | | Window | | |
| Rela | Authenticat | Message | authorization_res | Response |
| y | ed Window | Target | ponse | that |
| Mode | or Unauthen | Window | | includes A |
| | ticated | | | uthorizati |
| | Window | | | on |
| | | | | Response |
+------+-------------+-------------+-------------------+------------+
Table 2: Type attributes
5.2. Authorization Response
Authorization Server needs to render the JavaScript code to return
the Authorization Response when response_mode was web_message at the
time of Authorization Request at Authorization Endpoint.
Authorization Server MUST verify the following before returning
Authorization Response.
(1) The origin specified by redirect_uri is white-listed.
(2) The origin specified by web_message_uri is white-listed.
If verified, it MUST return the response including the JavaScript
code such as:
Yamaguchi, et al. Expires April 20, 2016 [Page 12]
Internet-Draft oauth-wmrm October 2015
<!DOCTYPE html>
<html>
<head>
<title>Authorization Response</title>
</head>
<body>
<script type="text/javascript">
(function(window, document, undefined) {
// Begin : these values rendered by server
var redirectURI = "https://client.example.com";
var webMessageRequest = {};
var authorizationResponse = {
type: "authorization_response",
response: {
code: "SplxlOBeZQQYbYS6WxSbIA",
state: "xyz"
}
};
// End
var mainWin = (window.opener != window) ? window.opener : window.parent;
// For relay mode
if (webMessageRequest["web_message_uri"] && webMessageRequest["web_message_target"]) {
window.addEventListener("message", function(evt) {
if (evt.origin != redirectURI)
return; // replay mode
switch (evt.data.type) {
case "relay_response":
messageTargetWindow =
evt.source.document.getElementById(webMessageRequest["web_message_target"]);
if (messageTargetWindow) {
messageTargetWindow.postMessage({
type: "authorization_response",
response: authorizationResponse
}, webMessageRequest["web_message_uri"]);
}
default:
}
}
mainWin.postMessage({
type: "relay_request"
}, redirectURI);
} else {
mainWin.postMessage({
type: "authorization_response",
response: authorizationResponse
}, redirectURI);
Yamaguchi, et al. Expires April 20, 2016 [Page 13]
Internet-Draft oauth-wmrm October 2015
}
})(this, this.document);
</script>
</body>
</html>
Figure 10: Authorization Response with web messaging response mode
If web_message_uri and web_message_target request parameters are
specified in Authorization Request, window object sent by
postMessage() is not to be set to window.opener or window.parent but
to a specific frame, responses such as follows should be returned.
<!DOCTYPE html>
<html>
<head>
<title>Authorization Response</title>
</head>
<body>
<script type="text/javascript">
(function(window, document, undefined) {
// Begin : these values rendered by server
var redirectURI = "https://client.example.com";
var webMessageRequest = {
web_message_uri: "https://api.example.com",
web_message_target: "apiFrame"
};
var authorizationResponse = {
type: "authorization_response",
response: {
code: "SplxlOBeZQQYbYS6WxSbIA",
state: "xyz"
}
};
// End
var mainWin = (window.opener != window) ? window.opener : window.parent;
// For relay mode
if (webMessageRequest["web_message_uri"] && webMessageRequest["web_message_target"]) {
window.addEventListener("message", function(evt) {
if (evt.origin != redirectURI)
return; // replay mode
switch (evt.data.type) {
case "relay_response":
Yamaguchi, et al. Expires April 20, 2016 [Page 14]
Internet-Draft oauth-wmrm October 2015
messageTargetWindow =
evt.source.document.getElementById(webMessageRequest["web_message_target"]);
if (messageTargetWindow) {
messageTargetWindow.postMessage({
type: "authorization_response",
response: authorizationResponse
}, webMessageRequest["web_message_uri"]);
}
default:
}
}
mainWin.postMessage({
type: "relay_request"
}, redirectURI);
} else {
mainWin.postMessage({
type: "authorization_response",
response: authorizationResponse
}, redirectURI);
}
})(this, this.document);
</script>
</body>
</html>
Figure 11: Authorization Response w/ web messaging response mode and
web_message_target
6. Client Metadata
The following field is added to RFC7519.
+------------------+-------+----------------------------------------+
| field | type | description |
+------------------+-------+----------------------------------------+
| web_message_uris | array | List of origins that are allowed as |
| | | web_message_uri in the Authorization |
| | | Request. |
+------------------+-------+----------------------------------------+
Table 3: Client Metadata Addition
Yamaguchi, et al. Expires April 20, 2016 [Page 15]
Internet-Draft oauth-wmrm October 2015
7. IANA Considerations
Followings are added to OAuth Dynamic Client Registration Metadata
Registry.
o Client Metadata Name: "web_message_uris"
o Client Metadata Description: List of origins that are allowed as
web_message_uri in the Authorization Request.
o Change Controller: IESG
o Specification Document(s): This document
8. Security Considerations
In addition to the all the security considerations discussed in OAuth
2.0 [RFC6819], the following security considerations SHOULD be taken
into account.
9. Acknowledgements
Follwoing people contributed to the creation of this document .
10. Revision History
-00
o Initial Draft.
11. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013,
<http://www.rfc-editor.org/info/rfc6819>.
[RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
RFC 7591, DOI 10.17487/RFC7591, July 2015,
<http://www.rfc-editor.org/info/rfc7591>.
Yamaguchi, et al. Expires April 20, 2016 [Page 16]
Internet-Draft oauth-wmrm October 2015
[Web.Messaging]
Hickson, I., "HTML5 Web Messaging", May 2015.
Authors' Addresses
Toru Yamaguchi
DeNA Co.,Ltd.
2-21-1, Shibuya
Shibuya-ku, Tokyo 150-8510
Japan
Phone: +81-3-4366-7243
Email: toru.yamaguchi@dena.com
URI: http://dena.com
Nat Sakimura (editor)
Nomura Research Institute
1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg.
Chiyoda-ku, Tokyo 100-0005
Japan
Phone: +81-3-5533-2111
Email: n-sakimura@nri.co.jp
URI: http://nat.sakimura.org/
Nov Matake
GREE
Email: nov@matake.jp
URI: http://matake.jp
Yamaguchi, et al. Expires April 20, 2016 [Page 17]