Implement redirect bridge to support COOP

change/@azure-msal-browser-3b6b0844-0608-4d31-bba7-7c7177ad52f1.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Implement redirect bridge to support COOP #8118",
+  "packageName": "@azure/msal-browser",
+  "email": "kshabelko@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-common-cde5a6b6-5532-4445-945e-4ca192b96714.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Implement redirect bridge to support COOP #8118",
+  "packageName": "@azure/msal-common",
+  "email": "kshabelko@microsoft.com",
+  "dependentChangeType": "patch"
+}

docs/errors.md

@@ -263,7 +263,7 @@ This error occurs when MSAL.js surpasses the allotted storage limit when attempt
 -   Authority mismatch error. Authority provided in login request or PublicClientApplication config does not match the environment of the provided account. Please use a matching account or make an interactive request to login to this authority.
 
 ### `invalid_request_method_for_EAR`
-- The EAR protocol cannot be used with HTTP method `GET`. The `httpMethod` parameter in all requests using `protocolMode: ProtocolMode.EAR` must be either unset or `"POST"`/`HttpMethod.POST`. 
+- The EAR protocol cannot be used with HTTP method `GET`. The `httpMethod` parameter in all requests using `protocolMode: ProtocolMode.EAR` must be either unset or `"POST"`/`HttpMethod.POST`.
 
 ## Interaction required errors
 
@@ -558,6 +558,40 @@ If you are unable to figure out why this error is being thrown please [open an i
 -   Refresh the page. Does the error go away?
 -   Open your application in a new tab. Does the error go away?
 
+### `interaction_in_progress_overridden`
+
+-   The current interaction was overridden by a new interaction request with `overrideInteractionInProgress` set to `true`.
+
+This error is thrown when an existing popup interaction is cancelled because a new popup request was initiated with the `overrideInteractionInProgress` flag set to `true`. This is not necessarily an error condition - it indicates that the previous interaction was intentionally cancelled to allow a new one to proceed.
+
+**When This Occurs:**
+
+This error is thrown for the **previous/cancelled** interaction when:
+1. A popup interaction is in progress (e.g., `acquireTokenPopup`)
+2. A new popup request is made with `overrideInteractionInProgress: true`
+3. The library cancels the pending interaction and starts the new one
+
+**Example:**
+
+```javascript
+// First popup request starts
+const request1 = { scopes: ["User.Read"] };
+const promise1 = msalInstance.acquireTokenPopup(request1);
+
+// User closes the popup or something goes wrong
+// App decides to retry with override flag
+const request2 = {
+    scopes: ["User.Read"],
+    overrideInteractionInProgress: true  // Override the previous interaction
+};
+const promise2 = msalInstance.acquireTokenPopup(request2);
+
+// promise1 will reject with interaction_in_progress_overridden
+// promise2 will proceed normally
+```
+
+**Note:** This error should only be seen when you explicitly use the `overrideInteractionInProgress` flag. Under normal circumstances, concurrent interaction attempts will throw `interaction_in_progress` instead.
+
 ### `popup_window_error`
 
 -   Error opening popup window. This can happen if you are using IE or if popups are blocked in the browser.
@@ -570,43 +604,53 @@ If you are unable to figure out why this error is being thrown please [open an i
 
 -   User cancelled the flow.
 
-### `monitor_popup_timeout`
+### `redirect_bridge_timeout`
+
+- Communication with the redirect page (popup or iframe) timed out while waiting for authentication response.
 
--   Token acquisition in popup failed due to timeout.
+**Error Messages**:
 
-### `monitor_window_timeout`
+- Token acquisition in popup failed due to timeout.
+- Token acquisition in iframe failed due to timeout.
 
--   Token acquisition in iframe failed due to timeout.
+This error can be thrown when calling `ssoSilent`, `acquireTokenSilent`, `acquireTokenPopup` or `loginPopup` when the redirect bridge script fails to send the authentication response back to the main window within the configured timeout period. This typically occurs for the following reasons:
 
-**Error Messages**:
+1. The page you use as your `redirectUri` is not loading the `msal-redirect-bridge.js` script
+1. The redirect page is removing or manipulating the hash before the bridge script can process it
+1. The redirect page is automatically navigating to a different page before the bridge can communicate the response
+1. Your identity provider is being slow to redirect back to your `redirectUri` (network latency)
+1. You are being throttled by your identity provider due to too many requests in a short period
 
--   Token acquisition in iframe failed due to timeout.
+**Resolution Steps:**
 
-This error can be thrown when calling `ssoSilent`, `acquireTokenSilent`, `acquireTokenPopup` or `loginPopup` and there are several reasons this could happen. These are a few of the most common:
+✔️ **Ensure the redirect bridge script is loaded:**
 
-1. The page you use as your `redirectUri` is removing or manipulating the hash
-1. The page you use as your `redirectUri` is automatically navigating to a different page
-1. You are being throttled by your identity provider. The identity provider may throttle clients that make too many similar requests in a short period of time. Never implement an endless retry mechanism or retry more than once. Attempts to retry non-network errors typically yield the same result. See [throttling guide](#Throttling) for more details.
-1. Your identity provider did not redirect back to your `redirectUri`.
+Your `redirectUri` page must include the redirect bridge script to enable communication back to the main window:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Redirect</title>
+</head>
+<body>
+    <script src="path/to/msal-redirect-bridge.js"></script>
+    <script>
+        msalRedirectBridge.sendRedirectPayloadToMainFrame();
+    </script>
+</body>
+</html>
+```
 
 **Important**: If your application uses a router library (e.g. React Router, Angular Router), please make sure it does not strip the hash or auto-redirect while MSAL token acquisition is in progress. If possible, it is best if your `redirectUri` page does not invoke the router at all.
 
 #### Issues caused by the redirectUri page
 
-When you make a silent call, in some cases, an iframe will be opened and will navigate to your identity provider's authorization page. After the identity provider has authorized the user it will redirect the iframe back to the `redirectUri` with the authorization code or error information in the hash fragment. The MSAL instance running in the frame or window that originally made the request will extract this response hash and process it. If your `redirectUri` is removing or manipulating this hash or navigating to a different page before MSAL has extracted it you will receive this timeout error.
+When you make a silent call, in some cases, an iframe will be opened and will navigate to your identity provider's authorization page. After the identity provider has authorized the user it will redirect the iframe back to the `redirectUri` with the authorization code or error information in the hash fragment. The MSAL redirect bridge running in the iframe will broadcast response to MSAL instance running in the frame or window that originally made the request. If your `redirectUri` is removing or manipulating this hash or navigating to a different page before MSAL redirect bridge has extracted it you will receive this timeout error.
 
-✔️ To solve this problem you should ensure that the page you use as your `redirectUri` is not doing any of these things, at the very least, when loaded in a popup or iframe. We recommend using a blank page as your `redirectUri` for silent and popup flows to ensure none of these things can occur.
+✔️ To solve this problem you should ensure that the page you use as your `redirectUri` is not doing any of these things, at the very least, when loaded in a popup or iframe.
 
-You can do this on a per request basis, for example:
-
-```javascript
-msalInstance.acquireTokenSilent({
-    scopes: ["User.Read"],
-    redirectUri: "http://localhost:3000/blank.html",
-});
-```
-
-Remember that you will need to register this new `redirectUri` on your App Registration.
+Remember that you will need to register `redirectUri` on your App Registration.
 
 **Notes regarding Angular and React:**
 
@@ -641,24 +685,27 @@ Some B2C flows are expected to throw this error due to their need for user inter
 
 Another potential reason the identity provider may not redirect back to your application in time may be that there is some extra network latency.
 
-✔️ The default timeout is about 10 seconds and should be sufficient in most cases, however, if your identity provider is taking longer than that to redirect you can increase this timeout in the MSAL config with either the `iframeHashTimeout`, `windowHashTimeout` or `loadFrameTimeout` configuration parameters.
+✔️ The default timeout is about 10 seconds and should be sufficient in most cases, however, if your identity provider is taking longer than that to redirect you can increase this timeout in the MSAL config with either the `iframeBridgeTimeout` or `popupBridgeTimeout` configuration parameters.
 
 ```javascript
 const msalConfig = {
     auth: {
         clientId: "your-client-id",
     },
     system: {
-        windowHashTimeout: 9000, // Applies just to popup calls - In milliseconds
-        iframeHashTimeout: 9000, // Applies just to silent calls - In milliseconds
-        loadFrameTimeout: 9000, // Applies to both silent and popup calls - In milliseconds
+        popupBridgeTimeout: 50000, // Applies just to popup calls - In milliseconds
+        iframeBridgeTimeout: 9000, // Applies just to silent calls - In milliseconds
     },
 };
 ```
 
 > [!IMPORTANT]
 > Please consult the [Troubleshooting Single-Sign On](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/FAQ.md#troubleshooting-single-sign-on) section of the MSAL Browser FAQ if you are having trouble with the `ssoSilent` API.
 
+### `redirect_bridge_empty_response`
+
+-   The redirect bridge returned an empty, indicating the redirect bridge script may have been modified or replaced.
+
 ### `redirect_in_iframe`
 
 -   Redirects are not supported for iframed or brokered applications. Please ensure you are using MSAL.js in a top frame of the window if using the redirect APIs, or use the popup APIs.

lib/msal-browser/apiReview/msal-browser.api.md

@@ -23,6 +23,7 @@ import { CommonEndSessionRequest } from '@azure/msal-common/browser';
 import { CommonSilentFlowRequest } from '@azure/msal-common/browser';
 import { Constants } from '@azure/msal-common/browser';
 import { ExternalTokenResponse } from '@azure/msal-common/browser';
+import { ICrypto } from '@azure/msal-common/browser';
 import { IdTokenClaims } from '@azure/msal-common/browser';
 import { ILoggerCallback } from '@azure/msal-common/browser';
 import { INetworkModule } from '@azure/msal-common/browser';
@@ -225,11 +226,12 @@ declare namespace BrowserAuthErrorCodes {
         unableToParseState,
         stateInteractionTypeMismatch,
         interactionInProgress,
+        interactionInProgressOverridden,
         popupWindowError,
         emptyWindowError,
         userCancelled,
-        monitorPopupTimeout,
-        monitorWindowTimeout,
+        redirectBridgeTimeout,
+        redirectBridgeEmptyResponse,
         redirectInIframe,
         blockIframeReload,
         blockNestedPopups,
@@ -384,15 +386,13 @@ export type BrowserSystemOptions = SystemOptions & {
     loggerOptions?: LoggerOptions;
     networkClient?: INetworkModule;
     navigationClient?: INavigationClient;
-    windowHashTimeout?: number;
-    iframeHashTimeout?: number;
-    loadFrameTimeout?: number;
+    popupBridgeTimeout?: number;
+    iframeBridgeTimeout?: number;
     redirectNavigationTimeout?: number;
     navigatePopups?: boolean;
     allowRedirectInIframe?: boolean;
     allowPlatformBroker?: boolean;
     nativeBrokerHandshakeTimeout?: number;
-    pollIntervalMilliseconds?: number;
     protocolMode?: ProtocolMode;
 };
 
@@ -410,6 +410,8 @@ declare namespace BrowserUtils {
         replaceHash,
         isInIframe,
         isInPopup,
+        cancelPendingBridgeResponse,
+        waitForBridgeResponse,
         getCurrentUri,
         getHomepage,
         blockReloadInHiddenIframes,
@@ -452,6 +454,11 @@ export type CacheOptions = {
     cacheRetentionDays?: number;
 };
 
+// Warning: (ae-missing-release-tag) "cancelPendingBridgeResponse" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public
+function cancelPendingBridgeResponse(logger: Logger, correlationId: string): void;
+
 // Warning: (ae-missing-release-tag) "ClearCacheRequest" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public
@@ -755,6 +762,11 @@ export { InProgressPerformanceEvent }
 // @public (undocumented)
 const interactionInProgress = "interaction_in_progress";
 
+// Warning: (ae-missing-release-tag) "interactionInProgressOverridden" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+const interactionInProgressOverridden = "interaction_in_progress_overridden";
+
 export { InteractionRequiredAuthError }
 
 export { InteractionRequiredAuthErrorCodes }
@@ -996,16 +1008,6 @@ export class MemoryStorage<T> implements IWindowStorage<T> {
     setUserData(key: string, value: T): Promise<void>;
 }
 
-// Warning: (ae-missing-release-tag) "monitorPopupTimeout" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
-const monitorPopupTimeout = "monitor_popup_timeout";
-
-// Warning: (ae-missing-release-tag) "monitorWindowTimeout" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
-const monitorWindowTimeout = "monitor_window_timeout";
-
 // Warning: (ae-missing-release-tag) "nativeConnectionNotEstablished" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -1112,6 +1114,7 @@ export type PopupRequest = Partial<Omit<CommonAuthorizationUrlRequest, "response
     scopes: Array<string>;
     popupWindowAttributes?: PopupWindowAttributes;
     popupWindowParent?: Window;
+    overrideInteractionInProgress?: boolean;
 };
 
 // Warning: (ae-missing-release-tag) "PopupSize" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -1247,6 +1250,16 @@ export class PublicClientApplication implements IPublicClientApplication {
     ssoSilent(request: SsoSilentRequest): Promise<AuthenticationResult>;
 }
 
+// Warning: (ae-missing-release-tag) "redirectBridgeEmptyResponse" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+const redirectBridgeEmptyResponse = "redirect_bridge_empty_response";
+
+// Warning: (ae-missing-release-tag) "redirectBridgeTimeout" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+const redirectBridgeTimeout = "redirect_bridge_timeout";
+
 // Warning: (ae-missing-release-tag) "redirectInIframe" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -1440,6 +1453,11 @@ const userCancelled = "user_cancelled";
 // @public (undocumented)
 export const version = "5.0.0-alpha.0";
 
+// Warning: (ae-missing-release-tag) "waitForBridgeResponse" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+function waitForBridgeResponse(timeoutMs: number, logger: Logger, browserCrypto: ICrypto, request: CommonAuthorizationUrlRequest | CommonEndSessionRequest): Promise<string>;
+
 // Warning: (ae-missing-release-tag) "WrapperSKU" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 // Warning: (ae-missing-release-tag) "WrapperSKU" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -1457,7 +1475,7 @@ export type WrapperSKU = (typeof WrapperSKU)[keyof typeof WrapperSKU];
 // src/cache/LocalStorage.ts:366:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/cache/LocalStorage.ts:429:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/cache/LocalStorage.ts:460:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/config/Configuration.ts:211:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
+// src/config/Configuration.ts:199:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
 // src/event/EventHandler.ts:114:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/event/EventHandler.ts:141:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/index.ts:8:12 - (tsdoc-characters-after-block-tag) The token "@azure" looks like a TSDoc tag but contains an invalid character "/"; if it is not a tag, use a backslash to escape the "@"

lib/msal-browser/package.json

@@ -37,6 +37,16 @@
                 "default": "./lib/custom-auth-path/msal-custom-auth.cjs"
             }
         },
+        "./redirect-bridge": {
+            "import": {
+                "types": "./dist/redirect-bridge/redirect_bridge/index.d.ts",
+                "default": "./dist/redirect-bridge/redirect_bridge/index.mjs"
+            },
+            "require": {
+                "types": "./lib/redirect-bridge/types/redirect_bridge/index.d.ts",
+                "default": "./lib/redirect-bridge/msal-redirect-bridge.js"
+            }
+        },
         ".": {
             "import": {
                 "types": "./dist/index.d.ts",