OAuth 2.0 Web Message Response Mode for Popup- and Iframe-based Authorization FlowsHackmanitkarsten.meyerzuselhausen@hackmanit.deRuhr University Bochumlouis.jannett@rub.deHackmanitchristian.mainka@hackmanit.de
Security
Web Authorization Protocolsecurityoauth2This 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.IntroductionOAuth 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.Conventions and TerminologyThe 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 ModeThis 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 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 and the security best practices
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")
Popup-Based Authorization Flow Using the Web Message Response ModeIn 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.Overview of popup-based authorization flow using the web message response mode. +------------------------------+
| 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 |
| | | |
+------------------------------+ +-----------------------+
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.
Additional authorization request parameters and techniques,
such as PAR and RAR ,
are unaffected by this specification and might be used with the web message response mode.
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">
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, 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 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")
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 the security best practices .
Iframe-Based Authorization Flow Using the Web Message Response ModeIn 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.Secure Iframe IntegrationAn authorization endpoint and consent-page embedded in an iframe MUST be protected against Clickjacking attacks .If the user's browser supports the Observer v2 API , 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 . The authorization server MUST prevent framing the authorization endpoint and consent-page except from origins deemed trustworthy.User-Session in IframesModern 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 .Authorization Server MetadataAuthorization servers
MUST announce their support for the web message response mode defined in
by adding web_message to the response_modes_supported list
in their authorization server metadata as specified in .Security ConsiderationsReceiver Origin ValidationAuthorization servers MUST follow
and the security best practices
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 ProtectionIn 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 the security best practices
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 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 ValidationEven after the initiator origin of the postMessage is validated, the client
MUST check that the postMessage has the expected format .
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.Cross-Site Leak Protections on the Authorization ServerThe 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 OriginIn 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 ConsiderationsThis draft makes no requests to IANA.Normative ReferencesOAuth 2.0 Multiple Response Type Encoding PracticesGoogleGoogleFacebookMicrosoftHTML Living Standard: Cross-document messagingInformative ReferencesSecure popup interactions with restrict-propertiesStorage Access APIOAuth 2.0 Form Post Response ModeMicrosoftPing IdentityIntersection ObserverHTML Living Standard: Cross-origin opener policiesAcknowledgementsWe 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 ]]-00
* initial draft