Internet-Draft oauth-web-message-response-mode November 2023
Meyer zu Selhausen, et al. Expires 26 May 2024 [Page]
Web Authorization Protocol
Intended Status:
Standards Track
K. Meyer zu Selhausen
L. Jannett
Ruhr University Bochum
C. Mainka

OAuth 2.0 Web Message Response Mode for Popup- and Iframe-based Authorization Flows


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

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.

Table of Contents

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 [].

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].

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:

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")

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

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 and [I-D.ietf-oauth-security-topics] (Section

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 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 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.

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 [] 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

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, , <>.
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <>.
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <>.
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <>.
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <>.
de Medeiros, B., Scurtescu, M., Tarjan, P., and M. Jones, "OAuth 2.0 Multiple Response Type Encoding Practices", , <>.
"HTML Living Standard: Cross-document messaging", <>.

10. Informative References

Yamaguchi, T., Sakimura, N., and N. Matake, "OAuth 2.0 Web Message Response Mode", Work in Progress, Internet-Draft, draft-sakimura-oauth-wmrm-01, , <>.
Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", RFC 9126, DOI 10.17487/RFC9126, , <>.
Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, , <>.
"Secure popup interactions with restrict-properties", , <>.
"Storage Access API", , <>.
Jones, M. and B. Campbell, "OAuth 2.0 Form Post Response Mode", , <>.
"Intersection Observer", , <>.
"HTML Living Standard: 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
Louis Jannett
Ruhr University Bochum
Christian Mainka