@azure/msal-browser 5.16.0 → 5.17.0

package/src/config/Configuration.ts

@@ -67,6 +67,23 @@ export type BrowserAuthOptions = {
      */
     postLogoutRedirectUri?: string | null;
 
+    /**
+     * URI of a first-party, top-level "popup-relay" page used to acquire tokens
+     * interactively from inside a cross-origin iframe that an untrusted host has
+     * embedded (where third-party storage partitioning and COOP break the normal
+     * popup flow). When set, `acquireTokenPopup` opens this page top-level
+     * instead of navigating the popup straight to the IdP, and the page must call
+     * `runPopupRelay()`. Resolved relative to the app origin, so it must be
+     * same-origin as the embedded frame.
+     *
+     * This is a browser SPA-only mechanism (`PublicClientApplication` in
+     * `@azure/msal-browser`): it brokers the standard interactive popup
+     * auth-code flow through a same-origin page. It does not apply to native
+     * app, platform broker (WAM), Nested App Auth, or confidential-client /
+     * server-side scenarios.
+     */
+    popupRelayUri?: string;
+
     /**
      * Array of capabilities which will be added to the claims.access_token.xms_cc request property on every network request.
      */
@@ -271,6 +288,7 @@ export function buildConfiguration(
                 ? window.location.href.split("?")[0].split("#")[0]
                 : "",
         postLogoutRedirectUri: "",
+        popupRelayUri: "",
         clientCapabilities: [],
         OIDCOptions: {
             responseMode: Constants.ResponseMode.FRAGMENT,

package/src/error/BrowserAuthErrorCodes.ts

@@ -24,6 +24,7 @@ export const redirectBridgeEmptyResponse = "redirect_bridge_empty_response";
 export const redirectInIframe = "redirect_in_iframe";
 export const blockIframeReload = "block_iframe_reload";
 export const blockNestedPopups = "block_nested_popups";
+export const popupRelayUnsupportedFlow = "popup_relay_unsupported_flow";
 export const iframeClosedPrematurely = "iframe_closed_prematurely";
 export const silentLogoutUnsupported = "silent_logout_unsupported";
 export const noAccountError = "no_account_error";

package/src/interaction_client/PopupClient.ts

@@ -19,6 +19,7 @@ import {
     PkceCodes,
     CommonAuthorizationUrlRequest,
     ProtocolUtils,
+    Authority,
 } from "@azure/msal-common/browser";
 import {
     initializeAuthorizationRequest,
@@ -34,6 +35,8 @@ import {
 import { EndSessionPopupRequest } from "../request/EndSessionPopupRequest.js";
 import { NavigationOptions } from "../navigation/NavigationOptions.js";
 import * as BrowserUtils from "../utils/BrowserUtils.js";
+import * as PopupRelay from "../popup_relay/relayClient.js";
+import { base64Decode } from "../encode/Base64Decode.js";
 import { PopupRequest } from "../request/PopupRequest.js";
 import {
     createBrowserAuthError,
@@ -375,9 +378,26 @@ export class PopupClient extends StandardInteractionClient {
                     this.performanceClient
                 );
 
+                /*
+                 * When a popup-relay page is configured, open it top-level
+                 * (same first-party origin) instead of navigating the popup
+                 * straight to the IdP, and carry the /authorize URL in its hash.
+                 * The relay page opens the IdP child popup and relays the
+                 * response back via postMessage (see waitForPopupResponse).
+                 */
+                const popupRelayUri = this.config.auth.popupRelayUri;
+                const popupNavigateUrl = popupRelayUri
+                    ? PopupRelay.buildPopupRelayUrl(
+                          popupRelayUri,
+                          this.getRelayStateId(request.state, correlationId),
+                          { method: "GET", url: navigateUrl },
+                          correlationId
+                      )
+                    : navigateUrl;
+
                 // Show the UI once the url has been created. Get the window handle for the popup.
                 const popupWindow: Window = this.initiateAuthRequest(
-                    navigateUrl,
+                    popupNavigateUrl,
                     popupParams
                 );
                 this.eventHandler.emitEvent(
@@ -497,18 +517,13 @@ export class PopupClient extends StandardInteractionClient {
             earJwk: earJwk,
             codeChallenge: pkce.challenge,
         };
-        const popupWindow =
-            popupParams.popup || this.openPopup("about:blank", popupParams);
-
-        const form = await Authorize.getEARForm(
-            popupWindow.document,
-            this.config,
-            discoveredAuthority,
+        const popupWindow = await this.openPostFormPopup(
             popupRequest,
-            this.logger,
-            this.performanceClient
+            discoveredAuthority,
+            popupParams,
+            correlationId,
+            true
         );
-        form.submit();
 
         // Monitor the popup for the hash. Return the string value and close the popup when the hash is received. Default timeout is 60 seconds.
         const responseString = await invokeAsync(
@@ -621,20 +636,14 @@ export class PopupClient extends StandardInteractionClient {
             this.logger
         );
 
-        const popupWindow =
-            popupParams.popup || this.openPopup("about:blank", popupParams);
-
-        const form = await Authorize.getCodeForm(
-            popupWindow.document,
-            this.config,
-            discoveredAuthority,
+        const popupWindow = await this.openPostFormPopup(
             request,
-            this.logger,
-            this.performanceClient
+            discoveredAuthority,
+            popupParams,
+            correlationId,
+            false
         );
 
-        form.submit();
-
         // Monitor the popup for the hash. Return the string value and close the popup when the hash is received. Default timeout is 60 seconds.
         const responseString = await invokeAsync(
             this.waitForPopupResponse.bind(this),
@@ -794,8 +803,30 @@ export class PopupClient extends StandardInteractionClient {
                 validRequest
             );
 
+            /*
+             * When a popup-relay page is configured, open it top-level (same
+             * first-party origin) and carry the end-session URL in its hash,
+             * exactly like the login flow. The relay page opens the IdP child
+             * popup and the post-logout redirect page (running the redirect
+             * bridge) relays completion back via postMessage — so logout works
+             * from an embedded, cross-origin iframe where a direct popup to the
+             * IdP cannot. See runPopupRelay / waitForPopupResponse.
+             */
+            const popupRelayUri = this.config.auth.popupRelayUri;
+            const popupNavigateUrl = popupRelayUri
+                ? PopupRelay.buildPopupRelayUrl(
+                      popupRelayUri,
+                      this.getRelayStateId(
+                          validRequest.state || "",
+                          this.correlationId
+                      ),
+                      { method: "GET", url: logoutUri },
+                      this.correlationId
+                  )
+                : logoutUri;
+
             // Open the popup window to requestUrl.
-            const popupWindow = this.openPopup(logoutUri, popupParams);
+            const popupWindow = this.openPopup(popupNavigateUrl, popupParams);
             this.eventHandler.emitEvent(
                 EventType.POPUP_OPENED,
                 validRequest.correlationId,
@@ -1074,11 +1105,94 @@ export class PopupClient extends StandardInteractionClient {
         return `${BrowserConstants.POPUP_NAME_PREFIX}.${this.config.auth.clientId}.${homeAccountId}.${this.correlationId}`;
     }
 
+    /**
+     * Decodes the per-request library-state id from the encoded request state.
+     */
+    private getRelayStateId(state: string, correlationId: string): string {
+        return ProtocolUtils.parseRequestState(
+            base64Decode,
+            state,
+            correlationId
+        ).libraryState.id;
+    }
+
+    /**
+     * Opens the interactive popup for a POST-form /authorize request. Shared by
+     * the auth-code POST and EAR flows, which are identical apart from the form
+     * builder (`isEAR` selects the EAR vs auth-code builders). When a
+     * popup-relay page is configured the form is carried to the relay page
+     * (which opens the IdP child popup); otherwise the form is submitted
+     * directly into the popup.
+     */
+    private async openPostFormPopup(
+        request: CommonAuthorizationUrlRequest,
+        discoveredAuthority: Authority,
+        popupParams: PopupParams,
+        correlationId: string,
+        isEAR: boolean
+    ): Promise<Window> {
+        const popupRelayUri = this.config.auth.popupRelayUri;
+        if (popupRelayUri) {
+            const getFormData = isEAR
+                ? Authorize.getEARFormData
+                : Authorize.getCodeFormData;
+            const formData = await getFormData(
+                this.config,
+                discoveredAuthority,
+                request,
+                this.logger,
+                this.performanceClient
+            );
+            const relayUrl = PopupRelay.buildPopupRelayUrl(
+                popupRelayUri,
+                this.getRelayStateId(request.state, correlationId),
+                {
+                    method: "POST",
+                    action: formData.action,
+                    fields: formData.fields,
+                },
+                correlationId
+            );
+            return this.initiateAuthRequest(relayUrl, popupParams);
+        }
+
+        const popupWindow =
+            popupParams.popup || this.openPopup("about:blank", popupParams);
+        const getForm = isEAR ? Authorize.getEARForm : Authorize.getCodeForm;
+        const form = await getForm(
+            popupWindow.document,
+            this.config,
+            discoveredAuthority,
+            request,
+            this.logger,
+            this.performanceClient
+        );
+        form.submit();
+        return popupWindow;
+    }
+
     protected async waitForPopupResponse(
         request: CommonAuthorizationUrlRequest | CommonEndSessionRequest,
         popupWindow: Window,
         popupWindowParent: Window
     ): Promise<string> {
+        /*
+         * When a popup-relay page is configured the response is relayed back to
+         * this frame by the relay page via postMessage, and the relay popup's
+         * lifecycle (including the user dismissing it before signing in) must be
+         * tracked here. This takes precedence over the default bridge response
+         * hook, whose BroadcastChannel cannot reach a partitioned cross-site
+         * frame and which does not track the relay popup.
+         */
+        if (this.config.auth.popupRelayUri) {
+            return PopupRelay.waitForPopupRelayResponse(
+                this.config.system.popupBridgeTimeout,
+                this.logger,
+                request,
+                popupWindow,
+                this.performanceClient
+            );
+        }
         if (this.waitForPopupResponseHook) {
             return this.waitForPopupResponseHook(
                 request,

package/src/packageMetadata.ts

@@ -1,3 +1,3 @@
 /* eslint-disable header/header */
 export const name = "@azure/msal-browser";
-export const version = "5.16.0";
+export const version = "5.17.0";

package/src/popup_relay/constants.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * postMessage envelope type used to relay an auth response from a popup-relay
+ * page (see `runPopupRelay`) back to the embedded frame that opened it. See
+ * {@link BrowserAuthOptions.popupRelayUri}.
+ *
+ * Kept dependency-free so both the relay-page entry (`./index.js`) and the
+ * client-side helpers (`./relayClient.js`) can import it without either bundle
+ * pulling in the other's dependencies.
+ *
+ * @internal
+ */
+export const POPUP_RELAY_RESPONSE_TYPE = "msal:popup-relay-response:v1";

package/src/popup_relay/index.ts

@@ -0,0 +1,221 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { POPUP_RELAY_RESPONSE_TYPE } from "./constants.js";
+import {
+    BrowserAuthErrorCodes,
+    createBrowserAuthError,
+} from "../error/BrowserAuthError.js";
+import { createForm } from "../protocol/Authorize.js";
+import { PopupWindowAttributes } from "../request/PopupWindowAttributes.js";
+
+/** Options for {@link runPopupRelay}. */
+export type PopupRelayOptions = {
+    /**
+     * Sizing/positioning for the IdP child popup the relay page opens. Same
+     * shape as `PopupRequest.popupWindowAttributes` (`popupSize` with width and
+     * height, `popupPosition` with top and left). Defaults to a 520x640 window.
+     */
+    popupWindowAttributes?: PopupWindowAttributes;
+    /**
+     * How long (ms) to wait for the IdP child popup to deliver a response
+     * before giving up. Defaults to 300000 (5 minutes).
+     */
+    timeoutMs?: number;
+};
+
+type PopupRelayRequest = { id: string } & (
+    | { method: "GET"; url: string }
+    | { method: "POST"; action: string; fields: Record<string, string> }
+);
+
+const DEFAULT_POPUP_RELAY_TIMEOUT_MS = 300000;
+const DEFAULT_POPUP_RELAY_WIDTH = 520;
+const DEFAULT_POPUP_RELAY_HEIGHT = 640;
+
+/**
+ * Builds the `window.open` features string for the IdP child popup from a
+ * {@link PopupWindowAttributes}, mirroring the shape used by
+ * `PopupRequest.popupWindowAttributes`.
+ */
+function buildChildPopupFeatures(attributes?: PopupWindowAttributes): string {
+    const width = attributes?.popupSize?.width || DEFAULT_POPUP_RELAY_WIDTH;
+    const height = attributes?.popupSize?.height || DEFAULT_POPUP_RELAY_HEIGHT;
+    const features = [`width=${width}`, `height=${height}`];
+    if (attributes?.popupPosition?.top !== undefined) {
+        features.push(`top=${attributes.popupPosition.top}`);
+    }
+    if (attributes?.popupPosition?.left !== undefined) {
+        features.push(`left=${attributes.popupPosition.left}`);
+    }
+    features.push("scrollbars=yes");
+    return features.join(",");
+}
+
+/**
+ * Entry point for the top-level "popup-relay" page referenced by
+ * `auth.popupRelayUri`. Call this from the relay page (which MSAL opens as a
+ * top-level popup from inside an embedded, cross-origin iframe). It:
+ *
+ *   1. Reads the IdP navigation MSAL passed in this page's hash (a GET URL, or a
+ *      POST form for the form_post / EAR response modes), then scrubs the hash.
+ *   2. Opens the IdP child popup and performs that navigation (the relay page
+ *      stays put, so its `window.opener` link back to the embedded frame
+ *      survives COOP).
+ *   3. Waits for the child's redirect URI page (which must run the redirect
+ *      bridge, `broadcastResponseToMainFrame`) to broadcast the raw auth
+ *      response over a same-origin `BroadcastChannel`.
+ *   4. Relays that raw response back to the embedded frame via
+ *      `opener.postMessage`, posting only to its own (same) origin, then closes.
+ *
+ * The embedded frame keeps the PKCE verifier (and EAR private key) and exchanges
+ * the relayed response itself — no token, verifier, or private key ever crosses
+ * a window boundary.
+ *
+ * Note: the child popup is opened when this function runs, so call it from a
+ * user gesture (e.g. a "Continue" button click) to avoid popup blockers.
+ *
+ * @param options - {@link PopupRelayOptions}
+ */
+export function runPopupRelay(options?: PopupRelayOptions): void {
+    const opener = window.opener as Window | null;
+    const targetOrigin = window.location.origin;
+
+    const hashParams = new URLSearchParams(
+        window.location.hash.replace(/^#/, "")
+    );
+    const rawReq = hashParams.get("req") || "";
+
+    // Scrub the relayed request out of the relay page's own URL immediately.
+    if (typeof window.history.replaceState === "function") {
+        window.history.replaceState(
+            null,
+            "",
+            window.location.origin + window.location.pathname
+        );
+    }
+
+    if (!opener) {
+        throw createBrowserAuthError(
+            BrowserAuthErrorCodes.popupRelayUnsupportedFlow,
+            "",
+            "popup_relay_no_opener"
+        );
+    }
+
+    let request: PopupRelayRequest;
+    try {
+        request = JSON.parse(rawReq) as PopupRelayRequest;
+    } catch (e) {
+        throw createBrowserAuthError(
+            BrowserAuthErrorCodes.popupRelayUnsupportedFlow,
+            "",
+            "popup_relay_bad_request"
+        );
+    }
+    if (!request || !request.id) {
+        throw createBrowserAuthError(
+            BrowserAuthErrorCodes.popupRelayUnsupportedFlow,
+            "",
+            "popup_relay_bad_request"
+        );
+    }
+
+    const id = request.id;
+    const channel = new BroadcastChannel(id);
+    let settled = false;
+    /*
+     * Timer handles are kept on a const holder so relay() (declared before the
+     * timers are created) can clear them — `let` handles trip prefer-const, and
+     * `const` handles can't be referenced before assignment (TDZ).
+     */
+    const timers: {
+        closedPoll?: number;
+        timeoutId?: number;
+    } = {};
+
+    const relay = (message: { payload?: string; error?: string }): void => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        try {
+            channel.close();
+        } catch (e) {
+            /* ignore */
+        }
+        clearInterval(timers.closedPoll);
+        clearTimeout(timers.timeoutId);
+        opener.postMessage(
+            { type: POPUP_RELAY_RESPONSE_TYPE, id, ...message },
+            targetOrigin
+        );
+        setTimeout(() => {
+            try {
+                window.close();
+            } catch (e) {
+                /* ignore */
+            }
+        }, 0);
+    };
+
+    // The redirect bridge broadcasts the raw auth response payload here.
+    channel.onmessage = (event: MessageEvent): void => {
+        const payload = event.data && event.data.payload;
+        if (payload) {
+            relay({ payload });
+        }
+    };
+
+    const features = buildChildPopupFeatures(options?.popupWindowAttributes);
+    const childPopup =
+        request.method === "POST"
+            ? window.open("about:blank", "msalPopupRelayChild", features)
+            : window.open(request.url, "msalPopupRelayChild", features);
+
+    if (!childPopup) {
+        relay({ error: BrowserAuthErrorCodes.popupWindowError });
+        return;
+    }
+
+    if (request.method === "POST") {
+        createForm(
+            childPopup.document,
+            request.action,
+            request.fields
+        ).submit();
+    }
+
+    timers.closedPoll = window.setInterval(() => {
+        if (childPopup.closed && !settled) {
+            /*
+             * The popup is gone, so the overall timeout no longer applies —
+             * drop it and report cancellation. A successful sign-in settles
+             * first: the redirect bridge broadcasts the response before it
+             * closes the popup, so onmessage runs on the
+             * next event-loop turn, well before this 500ms poll observes the
+             * close — the `!settled` guard then skips cancellation.
+             */
+            clearTimeout(timers.timeoutId);
+            relay({ error: BrowserAuthErrorCodes.userCancelled });
+        }
+    }, 500);
+
+    timers.timeoutId = window.setTimeout(() => {
+        if (!settled) {
+            /*
+             * Stop the close poll before we close the popup ourselves, so it
+             * can't observe the close and report user_cancelled instead.
+             */
+            clearInterval(timers.closedPoll);
+            try {
+                childPopup.close();
+            } catch (e) {
+                /* ignore */
+            }
+            relay({ error: BrowserAuthErrorCodes.timedOut });
+        }
+    }, options?.timeoutMs || DEFAULT_POPUP_RELAY_TIMEOUT_MS);
+}

package/src/popup_relay/relayClient.ts

@@ -0,0 +1,178 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    IPerformanceClient,
+    Logger,
+    ProtocolUtils,
+} from "@azure/msal-common/browser";
+import { base64Decode } from "../encode/Base64Decode.js";
+import {
+    BrowserAuthErrorCodes,
+    createBrowserAuthError,
+} from "../error/BrowserAuthError.js";
+import { redirectBridgeEmptyResponse } from "../error/BrowserAuthErrorCodes.js";
+import type { WaitForBridgeRequest } from "../utils/BrowserUtils.js";
+import { POPUP_RELAY_RESPONSE_TYPE } from "./constants.js";
+
+/**
+ * The navigation the popup-relay page should perform in its IdP child popup:
+ * either a GET navigation to a URL, or a POST form submission (used by the
+ * form_post and EAR response modes).
+ *
+ * @internal
+ */
+export type PopupRelayAction =
+    | { method: "GET"; url: string }
+    | { method: "POST"; action: string; fields: Record<string, string> };
+
+/**
+ * Builds the URL of the popup-relay page to open. The action the relay page
+ * must perform (GET navigation or POST form) is carried in the page's hash
+ * (client-side only, never sent to a server), keyed by the per-request
+ * library-state `id` so the relay page can listen on the right BroadcastChannel
+ * and echo the id back. The relay URI is resolved against the app origin, so it
+ * must be same-origin as the embedded frame. See `runPopupRelay`.
+ *
+ * @internal
+ */
+export function buildPopupRelayUrl(
+    popupRelayUri: string,
+    id: string,
+    action: PopupRelayAction,
+    correlationId: string
+): string {
+    const req = { id, ...action };
+    const target = new URL(popupRelayUri, window.location.origin);
+    /*
+     * The relay page must be same-origin as the embedded frame: the response is
+     * relayed back via postMessage and only accepted from this origin, and a
+     * cross-origin page would also receive the relayed /authorize request. Fail
+     * fast with a clear error instead of silently relaying to (and timing out
+     * against) the wrong origin.
+     */
+    if (target.origin !== window.location.origin) {
+        throw createBrowserAuthError(
+            BrowserAuthErrorCodes.popupRelayUnsupportedFlow,
+            correlationId,
+            "popup_relay_cross_origin"
+        );
+    }
+    const hashParams = new URLSearchParams();
+    hashParams.set("req", JSON.stringify(req));
+    target.hash = hashParams.toString();
+    return target.toString();
+}
+
+/**
+ * Waits for the popup-relay page to relay the raw auth response back to the
+ * embedded frame via postMessage. Used in place of `waitForBridgeResponse`
+ * when `auth.popupRelayUri` is configured, because third-party storage
+ * partitioning blocks the BroadcastChannel the redirect bridge uses from
+ * reaching the embedded frame.
+ *
+ * The response is accepted only from the popup window we opened, on our own
+ * origin (the relay page is same-origin as the embedded frame), and only when
+ * it carries the matching per-request library-state id.
+ *
+ * @internal
+ */
+export async function waitForPopupRelayResponse(
+    timeoutMs: number,
+    logger: Logger,
+    request: WaitForBridgeRequest,
+    popupWindow: Window,
+    performanceClient: IPerformanceClient
+): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+        const correlationId = request.correlationId;
+        logger.verbose(
+            "PopupRelay.waitForPopupRelayResponse - started",
+            correlationId
+        );
+        performanceClient.addFields(
+            { redirectBridgeTimeoutMs: timeoutMs },
+            correlationId
+        );
+
+        const { libraryState } = ProtocolUtils.parseRequestState(
+            base64Decode,
+            request.state || "",
+            correlationId
+        );
+        const expectedId = libraryState.id;
+        const expectedOrigin = window.location.origin;
+        let settled = false;
+
+        const cleanup = (): void => {
+            window.removeEventListener("message", onMessage);
+            clearTimeout(timeoutId);
+            clearInterval(closedPoll);
+        };
+
+        const onMessage = (event: MessageEvent): void => {
+            if (
+                event.origin !== expectedOrigin ||
+                event.source !== popupWindow
+            ) {
+                return;
+            }
+            const data = event.data;
+            if (
+                !data ||
+                data.type !== POPUP_RELAY_RESPONSE_TYPE ||
+                data.id !== expectedId
+            ) {
+                return;
+            }
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            if (data.error) {
+                reject(createBrowserAuthError(data.error, correlationId));
+            } else if (data.payload) {
+                resolve(data.payload);
+            } else {
+                reject(
+                    createBrowserAuthError(
+                        redirectBridgeEmptyResponse,
+                        correlationId
+                    )
+                );
+            }
+        };
+        window.addEventListener("message", onMessage);
+
+        const timeoutId = window.setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            reject(
+                createBrowserAuthError(
+                    BrowserAuthErrorCodes.timedOut,
+                    correlationId,
+                    "popup_relay_timeout"
+                )
+            );
+        }, timeoutMs);
+
+        const closedPoll = window.setInterval(() => {
+            if (popupWindow.closed && !settled) {
+                settled = true;
+                cleanup();
+                reject(
+                    createBrowserAuthError(
+                        BrowserAuthErrorCodes.userCancelled,
+                        correlationId
+                    )
+                );
+            }
+        }, 500);
+    });
+}