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](https://github.com/AzureAD/microsoft-authentication-library-for-js/pull/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](https://github.com/AzureAD/microsoft-authentication-library-for-js/pull/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_cancelled`
+
+-   The current interaction was cancelled 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_cancelled
+// 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,61 @@ 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`
 
--   Token acquisition in popup failed due to timeout.
+- Communication with the redirect page (popup or iframe) timed out while waiting for authentication response.
 
-### `monitor_window_timeout`
+**Error Messages**:
 
--   Token acquisition in iframe failed due to timeout.
+- Token acquisition in popup failed due to timeout.
+- Token acquisition in iframe failed due to timeout.
 
-**Error Messages**:
+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.
 
--   Token acquisition in iframe failed due to timeout.
+**What is the redirect bridge?**
 
-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:
+The redirect bridge is a mechanism that enables authentication flows in COOP (Cross-Origin-Opener-Policy) enabled applications. When COOP headers are present, popup and iframe windows cannot directly communicate with the main application window. The redirect bridge solves this by using the BroadcastChannel API to transmit authentication responses from the redirect page back to the main window. For more details on COOP support and the redirect bridge, see the [COOP Migration Guide](../lib/msal-browser/docs/v4-migration.md#cross-origin-opener-policy-coop-support).
 
-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`.
+**Common Causes:**
 
-**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.
+This timeout typically occurs for the following reasons:
 
-#### Issues caused by the redirectUri page
+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
 
-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.
+**Resolution Steps:**
 
-✔️ 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.
+✔️ **Ensure the redirect bridge script is loaded:**
 
-You can do this on a per request basis, for example:
+Your `redirectUri` page must include the redirect bridge script to enable communication back to the main window:
 
-```javascript
-msalInstance.acquireTokenSilent({
-    scopes: ["User.Read"],
-    redirectUri: "http://localhost:3000/blank.html",
-});
+```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>
 ```
 
-Remember that you will need to register this new `redirectUri` on your App Registration.
+**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 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.
+
+Remember that you will need to register `redirectUri` on your App Registration.
 
 **Notes regarding Angular and React:**
 
@@ -641,24 +693,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 response, 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.