| 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
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.
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 (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 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.
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
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].
For the purposes of this specification, the following terms and definitions apply.
window object that the client created
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.
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.
A window object in the iframe created by the Main Window(Section 2.1) that receives Authorization Response in Relay Mode (Section 4.2).
As stated above, this response mode provides two modes.
In the Simple mode, the protocol flows as follows.
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.
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:
The protocol flow of the Relay mode will be as follows.
The authorization sequence that uses Unauthenticated Window will be:
+-----------------------+
| |
+-------> 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)
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:
Web Messaging Response Mode defines the following Authorization Request parameters.
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.
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.
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:
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 |
Type attribute values are described in the following table.
| mode | sender | receiver | type | description |
|---|---|---|---|---|
| Simple Mode | Authenticated Window or Unauthenticated Window | Main Window | authorization_response | response including Authorization Response |
| Relay Mode | Authenticated Window or Unauthenticated Window | Main Window | relay_request | Request to get the reference to the window object of the Main Window |
| Relay Mode | Main Window | Authenticated Window or Unauthenticated Window | relay_response | The response to the relay_request |
| Relay Mode | Authenticated Window or Unauthenticated Window | Message Target Window | authorization_response | Response that includes 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.
If verified, it MUST return the response including the JavaScript code such as:
<!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);
}
})(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":
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
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. |
Followings are added to OAuth Dynamic Client Registration Metadata Registry.
In addition to the all the security considerations discussed in OAuth 2.0 [RFC6819], the following security considerations SHOULD be taken into account.
Follwoing people contributed to the creation of this document .
-00
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC6819] | Lodderstedt, T., McGloin, M. and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013. |
| [RFC7591] | Richer, J., Jones, M., Bradley, J., Machulak, M. and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015. |
| [Web.Messaging] | Hickson, I., "HTML5 Web Messaging", May 2015. |