Internet DRAFT - draft-meyerzuselha-oauth-web-message-response-mode
draft-meyerzuselha-oauth-web-message-response-mode
Web Authorization Protocol K. Meyer zu Selhausen
Internet-Draft Hackmanit
Intended status: Standards Track L. Jannett
Expires: 26 May 2024 Ruhr University Bochum
C. Mainka
Hackmanit
23 November 2023
OAuth 2.0 Web Message Response Mode for Popup- and Iframe-based
Authorization Flows
draft-meyerzuselha-oauth-web-message-response-mode-00
Abstract
This specification defines the web message response mode that
authorization servers use for transmitting authorization response
parameters via the user-agent's postMessage API to the client. This
mode is intended for authorization flows that use secondary windows,
which are well-suited for browser-based applications.
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 https://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 26 May 2024.
Copyright Notice
Copyright (c) 2023 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 (https://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
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 1]
Internet-Draft oauth-web-message-response-mode November 2023
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3
2. Web Message Response Mode . . . . . . . . . . . . . . . . . . 3
3. Popup-Based Authorization Flow Using the Web Message Response
Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Iframe-Based Authorization Flow Using the Web Message Response
Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5. Secure Iframe Integration . . . . . . . . . . . . . . . . . . 7
5.1. User-Session in Iframes . . . . . . . . . . . . . . . . . 7
6. Authorization Server Metadata . . . . . . . . . . . . . . . . 7
7. Security Considerations . . . . . . . . . . . . . . . . . . . 7
7.1. Receiver Origin Validation . . . . . . . . . . . . . . . 8
7.2. Initiator Origin Validation and Cross-Site Request Forgery
Protection . . . . . . . . . . . . . . . . . . . . . . . 8
7.3. Data Validation . . . . . . . . . . . . . . . . . . . . . 8
7.4. Cross-Site Leak Protections on the Authorization
Server . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.5. Redirection URI vs. Receiver Origin . . . . . . . . . . . 9
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
9. Normative References . . . . . . . . . . . . . . . . . . . . 9
10. Informative References . . . . . . . . . . . . . . . . . . . 10
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11
Appendix B. Document History . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction
OAuth [RFC6749] uses HTTP redirects to transfer authorization
response parameters from the authorization server via the user-agent
to the client's redirection endpoint. In this case, the
authorization response parameters are encoded in the query string
(response_mode=query) or in the fragment (response_mode=fragment) of
the redirect_uri [oauth.encoding] (Section 2.1). [RFC6749]
(Section 1.7) allows other mechanisms available via the user-agent to
accomplish this redirection, such as response_mode=form_post
[oauth.post].
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 2]
Internet-Draft oauth-web-message-response-mode November 2023
The standardized query, fragment, and form post response modes are
designed for single-window authorization but not for multi-window
authorization flows. A common example is a popup-based authorization
flow, where the client's primary window opens the authorization
server in a secondary window. The secondary window cannot use HTTP
redirects to transfer response parameters back to the client in the
primary window.
This specification defines the web message response mode that uses
the user-agent's postMessage API [whatwg.postmessage] to exchange
messages between two different browser windows. Clients inform the
authorization server to use this response mode for returning the
authorization response by setting the response_mode parameter in the
authorization request to web_message. This response mode facilitates
popup-based and iframe-based authorization flows, in which the
authorization server is called in a secondary window or embedded in a
frame on the client.
1.1. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
This specification uses the terms "client", "user-agent",
"authorization server", "authorization endpoint", "redirection
endpoint", "redirection URI", "authorization request", and
"authorization response" defined by the OAuth 2.0 Authorization
Framework [RFC6749]. It further uses the term "response mode"
defined by the OAuth 2.0 Multiple Response Type Encoding Practices
[oauth.encoding].
This specification defines the following additional terminology.
primary window This is the top-level browsing window that initially
holds the client's website. This window has no parent windows and
it was not opened by any other window.
secondary window This is the window in which the client in the
primary window opens the authorization server.
2. Web Message Response Mode
This specification defines the web message response mode, which is
described with the following response_mode parameter value in the
authorization request [oauth.encoding].
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 3]
Internet-Draft oauth-web-message-response-mode November 2023
web_message In the web message response mode, the authorization
server in the secondary window encodes the authorization response
parameters in a JSON dictionary and transmits it via the user-
agent's postMessage API to the client in the primary window.
If the authorization request includes the value web_message for the
response_mode parameter, the authorization server:
* MUST use the user-agent's postMessage API to return the
authorization response to the client.
* MUST encode the response paramters as key-value string pairs in a
JSON dictionary.
* MUST follow [RFC6749] and the security best practices
[I-D.ietf-oauth-security-topics] when validating the redirection
URI.
* MUST use the full redirection URI (the exact same URI also used in
other response modes such as query, fragment, or form post) as the
postMessage's receiver origin. The user-agent's postMessage API
inherently parses the redirection URI and extracts its origin.
* MUST NOT parse the URI itself to reduce the attack surface
concerning parsing issues.
The client's redirection URI MUST serve as the postMessage's receiver
origin to protect the authorization response from being leaked to
malicious origins.
This example illustrates how an authorization server (identified by
the issuer https://as.example) in a secondary window returns the
authorization response to the client (whose registered redirection
URI is https://client.example/cb) in the primary window using the
postMessage API:
========== NOTE: '\' line wrapping per RFC 8792 ===========
const primaryWindowRef = window.opener // popup-based auth. flow
const primaryWindowRef = window.parent // iframe-based auth. flow
primaryWindowRef.postMessage({"code": "XXXXXXXX","state":"XXXXXXXX",\
"iss": "https://as.example"},"https://client.example/cb")
3. Popup-Based Authorization Flow Using the Web Message Response Mode
In a popup-based authorization flow, the client opens the
authorization endpoint in a secondary window. The authorization
server uses the user-agent's postMessage API to return the
authorization response parameters from the secondary window back to
the client running in the primary window. The flow is depicted in
Figure 1 and described in the following.
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 4]
Internet-Draft oauth-web-message-response-mode November 2023
+------------------------------+
| Primary Window |
| (client.example/login) | +-----------------------+
| | | Secondary Window |
|1) Register message event | | (as.example/authz) |
| handler | | |
| | |3) Authenticate user |
|2) Open authz request with | | and authorize |
| web message response mode | | access |
| parameter in popup window +--->| |
| | |4) Send postMessage |
|5) Validate and process authz |<---+ with authz response |
| response in event handler | | to opener window |
| | | |
+------------------------------+ +-----------------------+
Figure 1: Overview of popup-based authorization flow using the
web message response mode.
1. The client registers a message event handler that receives the
authorization response from the authorization server. The client
MUST validate the message's origin with an exact string matching
the authorization server's origin. As the authorization response
is meant for one-time use, the client MUST remove the message
event handler after receiving the authorization response to
prevent any further authorization attempts.
Example of the registration of a message event handler:
const callback = (e) => {
if (e.origin === "https://as.example") {
// further validation and processing of the authorization response
process(e.data)
window.removeEventListener("message", callback)
}
}
window.addEventListener("message", callback)
2. The client MUST open the authorization request in a secondary
window. Therefore, the client MAY use JavaScript and the user-
agent's window.open API, MAY use an anchor HTML element with a
target attribute, or MAY use any other mechanism suitable for
opening secondary windows. The authorization request MUST
include the response_mode parameter value web_message.
Additional authorization request parameters and techniques, such
as PAR [RFC9126] and RAR [RFC9396], are unaffected by this
specification and might be used with the web message response
mode.
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 5]
Internet-Draft oauth-web-message-response-mode November 2023
Example of using the window.open API to open the authorization
request in a secondary window:
========== NOTE: '\' line wrapping per RFC 8792 ===========
window.open("https://as.example/auth?...&response_mode=web_message",\
"_blank","left=100,top=100,width=320,height=320")
Example of using an anchor tag with a target attribute to open the
authorization request in a secondary window:
========== NOTE: '\' line wrapping per RFC 8792 ===========
<a href="https://as.example/auth?...&response_mode=web_message" \
target="_blank">
3. The authorization server receives the authorization request,
validates its parameters, and proceeds with the end-user
authentication and authorization, which is outside of the scope
of this specification.
4. If the authorization request includes the response_mode parameter
value web_message, the authorization server MUST follow the web
message response mode as described in Section 2 and use the user-
agent's postMessage API to return the authorization response
parameters from the secondary to the secondary window's opener
window. The receiver window MUST be referenced by the secondary
window's opener property.
Example of an authorization server using the postMessage API in a
secondary window to return the authorization response to the client
in the primary window:
========== NOTE: '\' line wrapping per RFC 8792 ===========
window.opener.postMessage({"code": "XXXXXXXX", "state": "XXXXXXXX", \
"iss": "https://as.example"}, "https://client.example/cb")
5. The client's message event handler receives the postMessage that
contains the authorization response parameters. The further
processing and validation of all parameters is out of the scope
of this specification and MUST be compliant to [RFC6749] and the
security best practices [I-D.ietf-oauth-security-topics].
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 6]
Internet-Draft oauth-web-message-response-mode November 2023
4. Iframe-Based Authorization Flow Using the Web Message Response Mode
In addition to secondary windows being popups, iframes can be used.
Iframes enable a seamless authorization flow where the end-user only
sees a single browser tab, without ever leaving the actual client.
The exchange of tokens works technically similar to popups. However,
iframes are more difficult to implement on the authorization server
side.
5. Secure Iframe Integration
An authorization endpoint and consent-page embedded in an iframe MUST
be protected against Clickjacking attacks
[I-D.ietf-oauth-security-topics] (Section 4.16).
If the user's browser supports the Observer v2 API [w3c.observerv2],
the authorization server MAY use it to allow the client to embed the
authorization endpoint and consent-page. Otherwise, the
authorization server MUST implement Clickjacking countermeasures
according to [I-D.ietf-oauth-security-topics] (Section 4.16). The
authorization server MUST prevent framing the authorization endpoint
and consent-page except from origins deemed trustworthy.
5.1. User-Session in Iframes
Modern browsers have started to disable the support for third-party
cookies. Thereby, iframes do not send authentication cookies along
with requests in sub resource requests, such as iframes. Using
iframes as secondary windows therefore requires special exceptions to
bypass this restriction, such as the Storage Access API
[mozilla.storageaccessapi].
6. Authorization Server Metadata
Authorization servers MUST announce their support for the web message
response mode defined in Section 2 by adding web_message to the
response_modes_supported list in their authorization server metadata
as specified in [RFC8414] (Section 2).
7. Security Considerations
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 7]
Internet-Draft oauth-web-message-response-mode November 2023
7.1. Receiver Origin Validation
Authorization servers MUST follow Section 2 and the security best
practices [I-D.ietf-oauth-security-topics] (Section 4.18.2) when
validating the postMessage receiver origin. Otherwise, the
authorization response may leak to an attacker, as described in
[I-D.ietf-oauth-security-topics] (Section 4.18.1.1) and
[I-D.ietf-oauth-security-topics] (Section 4.18.1.2).
7.2. Initiator Origin Validation and Cross-Site Request Forgery
Protection
In redirect-based authorization flows, there is no inherent mechanism
available that enables a client to verify that the trusted
authorization server initiates a redirection. Instead, [RFC6749]
introduces the state parameter to counter so-called Cross-Site
Request Forgery (CSRF) attacks [I-D.ietf-oauth-security-topics]
(Section 4.7) against the client's redirection endpoint by
maintaining a state between the authorization request and response.
The postMessage API provides an inherent mechanism to verify the
initiator of a postMessage. The client MUST use this mechanism as
described in Section 2 and the security best practices
[I-D.ietf-oauth-security-topics] (Section 4.18.2) to verify that the
trusted authorization server is the initiator of the postMessage.
Otherwise, an attacker can inject a maliciously crafted authorization
response to the client [I-D.ietf-oauth-security-topics]
(Section 4.18.1.3). This verification prevents some variants of CSRF
attacks, where the attacker wants to log in a victim to the attacker
account.
However, attackers can also use CSRF attacks to log in a victim to
the victim's own account. This attack variant cannot be mitigated
with the checks mentioned above. Instead, a proper CSRF
countermeasure, as described in [I-D.ietf-oauth-security-topics]
(Section 4.7.1) MUST be used.
7.3. Data Validation
Even after the initiator origin of the postMessage is validated, the
client MUST check that the postMessage has the expected format
[whatwg.postmessage] (Section 9.3.2.1). In specific, the postMessage
MUST NOT be processed in unsafe JavaScript sinks like eval or
innerHTML to prevent cross-site scripting (XSS) flaws and other
potentially malicious injections. Otherwise, if the authorization
server has been attacked using an XSS flaw, further unchecked
processing of the postMessage could result in the attack being
propagated into the client.
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 8]
Internet-Draft oauth-web-message-response-mode November 2023
7.4. Cross-Site Leak Protections on the Authorization Server
The authorization server is opened in a secondary window that needs
access to its opener window via its opener property to send
postMessages to that referenced window. Thus, the authorization
server cannot use cross-site leak protections like the cross-origin
opener policy [whatwg.coop] to force the creation of a new top-level
browsing context and cross-origin isolate their sites.
However, browsers are working on preventing cross-site leaks without
breaking the popup-based authorization flows with the restrict-
properties directive being added to the cross-origin opener policy
[google.restrictprops]. With this directive, properties that can be
used for cross-site leaks are not available but postMessage
communication between cross-origin windows is still allowed.
Authorization servers MAY set the Cross-Origin-Opener-Policy:
restrict-properties header to protect against cross-site leaks.
7.5. Redirection URI vs. Receiver Origin
In redirect-based authorization flows, the confidentiality of the
authorization response is scoped to the redirection URI that contains
a path. The path separates the authorization response from other,
potentially vulnerable paths within the same web application. In
flows using the web message response mode, the confidentiality of the
authorization response is scoped to the postMessage's receiver origin
that does not contain a path. Thus, cross-site scripting (XSS)
vulnerabilities on _any_ path within the web application's origin
will leak the authorization response to the attacker.
8. IANA Considerations
This draft makes no requests to IANA.
9. Normative References
[I-D.ietf-oauth-security-topics]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"OAuth 2.0 Security Best Current Practice", Work in
Progress, Internet-Draft, draft-ietf-oauth-security-
topics-24, 23 October 2023,
<https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
security-topics-24>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 9]
Internet-Draft oauth-web-message-response-mode November 2023
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/info/rfc8414>.
[oauth.encoding]
de Medeiros, B., Scurtescu, M., Tarjan, P., and M. Jones,
"OAuth 2.0 Multiple Response Type Encoding Practices",
February 2014, <https://openid.net/specs/oauth-v2-
multiple-response-types-1_0.html>.
[whatwg.postmessage]
"HTML Living Standard: Cross-document messaging",
<https://html.spec.whatwg.org/multipage/web-
messaging.html#web-messaging>.
10. Informative References
[I-D.sakimura-oauth-wmrm]
Yamaguchi, T., Sakimura, N., and N. Matake, "OAuth 2.0 Web
Message Response Mode", Work in Progress, Internet-Draft,
draft-sakimura-oauth-wmrm-01, 8 November 2023,
<https://datatracker.ietf.org/doc/html/draft-sakimura-
oauth-wmrm-01>.
[RFC9126] Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D.,
and F. Skokan, "OAuth 2.0 Pushed Authorization Requests",
RFC 9126, DOI 10.17487/RFC9126, September 2021,
<https://www.rfc-editor.org/info/rfc9126>.
[RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0
Rich Authorization Requests", RFC 9396,
DOI 10.17487/RFC9396, May 2023,
<https://www.rfc-editor.org/info/rfc9396>.
[google.restrictprops]
and , "Secure popup interactions with restrict-
properties", 9 August 2023,
<https://developer.chrome.com/blog/coop-restrict-
properties/>.
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 10]
Internet-Draft oauth-web-message-response-mode November 2023
[mozilla.storageaccessapi]
"Storage Access API", 18 October 2023,
<https://developer.mozilla.org/en-US/docs/Web/API/
Storage_Access_API>.
[oauth.post]
Jones, M. and B. Campbell, "OAuth 2.0 Form Post Response
Mode", 27 April 2015, <http://openid.net/specs/oauth-v2-
form-post-response-mode-1_0.html>.
[w3c.observerv2]
and , "Intersection Observer", 4 November 2019,
<https://w3c.github.io/IntersectionObserver/>.
[whatwg.coop]
"HTML Living Standard: Cross-origin opener policies",
<https://html.spec.whatwg.org/multipage/
browsers.html#cross-origin-opener-policies>.
Appendix A. Acknowledgements
We would like to acknowledge the prior work of Toru Yamaguchi, Nat
Sakimura, and Nov Matake in [I-D.sakimura-oauth-wmrm] which tried to
define a response mode with similarities to this specification. In
contrast, this specification is not focused on iframes and does not
include the use of the OAuth Implicit Grant.
We would like to thank Vladislav Mladenov, ...
for their valuable feedback on this document.
Appendix B. Document History
[[ To be removed from the final specification ]]
-00 * initial draft
Authors' Addresses
Karsten Meyer zu Selhausen
Hackmanit
Email: karsten.meyerzuselhausen@hackmanit.de
Louis Jannett
Ruhr University Bochum
Email: louis.jannett@rub.de
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 11]
Internet-Draft oauth-web-message-response-mode November 2023
Christian Mainka
Hackmanit
Email: christian.mainka@hackmanit.de
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page 12]
