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

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

karsten.meyerzuselhausen@hackmanit.de

Ruhr University Bochum

louis.jannett@rub.de

Hackmanit

christian.mainka@hackmanit.de

Security Web Authorization Protocol security oauth2 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.

Introduction OAuth 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 . 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 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. These flows that span the authorization process across two windows are especially useful for browser-based applications, where the main application window should remain uninterrupted to preserve the user experience. Executing authorization flows in invisible iframes can also enable seamless session resumption and renewal without disrupting the user.

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 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 . It further uses the term "response mode" defined by the OAuth 2.0 Multiple Response Type Encoding Practices . 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.

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 .

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 dynamically discover the client's primary window reference as described in .
MUST use the user-agent's postMessage API to return the authorization response to the client's primary window.
MUST encode the response paramters as key-value string pairs in a JSON dictionary.
MUST follow and 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: const primaryWindowRef = window.opener // for popup-based flow const primaryWindowRef = window.parent // for iframe-based flow const params = { "code": "XXXXXXXX", "state":"XXXXXXXX", "iss": "https://as.example" } primaryWindowRef.postMessage(params, "https://client.example/cb") The client MAY signal its preferred primary window reference by using the response_mode parameter. For popup-based authorization flows, it MAY set the value to web_message.opener, and for iframe-based authorization flows, it MAY set the value to web_message.parent. When either web_message.opener or web_message.parent is specified, the authorization server MUST use the corresponding window reference window.opener or window.parent and MUST NOT attempt to dynamically determine the primary window reference as specified in .

Dynamic Discovery of Primary Window Reference If the authorization request specifies web_message as the response_mode, the authorization server running in the secondary window MUST dynamically determine the client's primary window reference. This is done by checking whether the window.opener or window.parent references point to a valid primary window. If both references are available, the window.opener reference MUST take precedence to ensure that popup-based authorization flows are prioritized over iframe-based flows. The following example illustrates how an authorization server may perform this discovery process: let primaryWindowRef = undefined if (window.opener !== null) // this is a popup-based flow primaryWindowRef = window.opener else if (window.parent !== self) // this is an iframe-based flow primaryWindowRef = window.parent else // abort flow: could not discover primary window reference

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 and described in the following.

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)

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 or web_message.opener. Additional authorization request parameters and techniques, such as PAR and RAR , are unaffected by this specification and MAY be used with the web message response mode.

Example of using the window.open API to open the authorization request in a secondary window: window.open( "https://as.example/auth?...&response_mode=web_message", "secondaryWindowRef", "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: <a href="https://as.example/auth?...&response_mode=web_message" target="secondaryWindowRef" >

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.
If the authorization request includes the response_mode parameter value web_message or web_message.opener, the authorization server MUST follow the web message response mode as described in and use the user-agent's postMessage API to return the authorization response parameters from the secondary window 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: const params = { "code": "XXXXXXXX", "state": "XXXXXXXX", "iss": "https://as.example" } window.opener.postMessage(params, "https://client.example/cb")

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

Iframe-Based Authorization Flow Using the Web Message Response Mode In addition to secondary windows being popups, iframes can be used as well. Iframes enable a seamless authorization flow where the end-user only sees a single browser tab, without ever leaving the actual client. The client MAY explicitly request the iframe-based authorization flow by setting the response_mode parameter to web_message.parent. The authorization flow proceeds in a manner technically similar to the popup-based flow described in , with the following modifications:

In step 2, the client MUST embed the authorization request in an iframe instead of opening a popup window.
In step 4, the secondary window MUST reference its parent window rather than its opener window.

If user consent has already been granted, iframe-based authorization flows can enable seamless session resumption or renewal by embedding invisible iframes with the prompt parameter set to none . In this case, the client receives the authorization response directly, allowing the user session to resume without further interaction. If the prompt parameter is set to none but no prior user authentication or consent exists, the authorization server MUST return an error as specified in . In this case, the client can fall back to a popup-based flow or to an iframe-based flow that displays a Clickjacking-protected user interface, as discussed in .

Clickjacking Mitigations in Iframes The authorization server MUST implement Clickjacking countermeasures according to and protect its authorization endpoint and consent-page from being embedded in an iframe by origins not deemed trustworthy. If the user's browser supports the Intersection Observer v2 API , the authorization server MAY use it to allow the client to embed the authorization endpoint and consent-page. For example, the authorization server's script running in the embedded consent-page could pre-emptively load itself in a popup window if it detects the Intersection Observer v2 API's isVisible attribute being set to false, thus avoiding any occlusion of its content.

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 . This mechanism is unnecessary in first-party scenarios where the authorization server and client share the same origin. In such cases, cookies are treated as first-party and remain included in requests made from iframes.

Authorization Server Metadata Authorization servers MUST announce their support for the web message response mode defined in by adding web_message, web_message.opener, web_message.parent, or any combinations of these values to the response_modes_supported list in their authorization server metadata as specified in . Authorization servers MAY declare exclusive support for a specific authorization flow by including either web_message.opener or web_message.parent in the response_modes_supported list. If the response_modes_supported list contains the generic value web_message, the authorization server MUST support both the popup-based and the iframe-based authorization flows.

Security Considerations

Receiver Origin Validation Authorization servers MUST follow and when validating the postMessage receiver origin. Otherwise, the authorization response may leak to an attacker, as described in and .

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, introduces the state parameter to counter so-called Cross-Site Request Forgery (CSRF) attacks 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 and 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 . This verification prevents some variants of CSRF attacks, where the attacker wants to log in a victim to the attacker's 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 MUST be used.

Data Validation Even after the initiator origin of the postMessage is validated, the client MUST check that the postMessage has the expected format . In particular, 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.

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

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.

IANA Considerations This draft makes no requests to IANA.

Normative References OAuth 2.0 Multiple Response Type Encoding Practices Google Google Facebook Microsoft HTML Living Standard: Cross-document messaging Informative References Secure popup interactions with restrict-properties Storage Access API OAuth 2.0 Form Post Response Mode Microsoft Ping Identity OpenID Connect Core 1.0 incorporating errata set 1 NRI Ping Identity Microsoft Google Salesforce Intersection Observer HTML Living Standard: Cross-origin opener policies

Acknowledgements We would like to acknowledge the prior work of Toru Yamaguchi, Nat Sakimura, and Nov Matake in 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.

Document History [[ To be removed from the final specification ]] -01 * Add use cases of popup and iframe flows * Enhance and clarify descriptions and mitigations for iframe flow * Clarify iframe use for first-party context and invisible iframes for reauthentication flows with prompt none * Add dynamic discovery of primary window reference and new values for response_mode: web_message.opener and web_message.parent * Add notes about how this draft differs from Sakimura et al. * Add several example implementations of the web message response mode and popup- or iframe-based flows * Minor improvements of style and language * Update references to newer versions -00 * Initial draft

Example Implementations [[ To be removed from the final specification ]] Although neither the web_message response mode nor the popup- and iframe-based authorization flows have been officially standardized, they are already widely supported in practice. A study from late 2022 found that 153 of the Tranco Top 1k websites opened the authorization server in a secondary window, compared to only 134 websites that navigated the primary window to the authorization server. More recently, a scan of all domains in the CrUX dataset (July 2025) revealed 22 authorization servers that publish the still-undefined web_message value in the response_modes_supported list of their OpenID Provider Metadata at /.well-known/openid-configuration. In addition, several authorization servers support popup- or iframe-based flows without explicitly announcing them in their metadata:

Apple supports the popup-based flow with response_mode=web_message through its custom JS SDK. The flow is activated if the client enables the SDK's popup mode via a meta tag. Apple's REST API documentation does not mention web_message as a valid response_mode, although the SDK uses it when configured.
Google supports both the popup-based (default) and iframe-based flows within its Google Identity Services SDKs. However, these flows are not available in its interoperable OAuth and OpenID Connect endpoints.
Facebook supports the popup-based flow through its JS SDK. It always includes the xd_arbiter endpoint as a parameter to the authorization endpoint, e.g., channel_url=https://staticxx.facebook.com/x/connect/xd_arbiter.
Auth0 officially documents support for the web_message response mode in its API documentation. It references the expired draft from 2015 and uses it for silent authentication with HTML5 web messaging.
Nintendo uses the web_message response mode internally, following the expired draft . It also relies on the additional web_message_uri and web_message_target parameters.

Beyond these providers, other authorization servers also employ web_message or proprietary variants of popup- and iframe-based flows. Apple, Google, and Facebook even make multi-window flows the default within their SDKs, highlighting their practical importance. Yet, the absence of an interoperable, standards-based mechanism for clients to use these flows underscores the need for formal standardization.

Differences to [[ To be removed from the final specification ]] This draft builds on the earlier work of Toru Yamaguchi, Nat Sakimura, and Nov Matake in , which introduced a web message response mode. While sharing several conceptual similarities, this draft differs in the following ways:

Flow illustrations: illustrates only the deprecated implicit flow (response_type=token). This draft is flow-agnostic and uses the authorization code flow (response_type=code) in its examples.
Primary window reference: does not specify how the authorization server should obtain a reference to the client's primary window. This draft allows the authorization server to either dynamically discover the reference or rely on client-provided hints via the web_message.opener and web_message.parent response modes.
Relay mode: defines a relay mode in which the authorization response is forwarded through the client to a third window (the "message target window"). This draft does not support tertiary windows and instead limits the exchange to the client's primary window and the authorization server's secondary window. This draft omits relay mode due to lack of practical demand.
Browser compatibility: uses JavaScript constructs that no longer work in modern browsers (e.g., window.opener != window and cross-origin DOM access via evt.source.document.getElementById). These break relay mode entirely, as the secondary window cannot obtain a reference to the message target window.
Parameters: introduces the web_message_uri (target URI) and web_message_target (DOM id) parameters, both tied to relay mode. This draft omits these parameters and instead relies solely on the established redirect_uri.
Message format: defines postMessage data as an object with fields type (string) and response (object). This draft simplifies the structure to a single object containing all authorization response parameters, since only one postMessage is used.
Iframe restrictions: restricts iframe-based flows to already-authenticated sessions with prior consent ("authenticated windows"). This draft permits iframe-based flows in unauthenticated states as well, relying on Clickjacking mitigations (e.g., the Intersection Observer v2 API).
Security considerations: This draft provides extended guidance on secure use of postMessage, Clickjacking mitigations, and implications of browsers phasing out third-party cookies.