Skip to content

Commit 33b9647

Browse files
konstantin-msftkonstantin-msft
authored
Add COOP redirect bridge setup documentation for various frameworks (#8398)
- Add error message format change impact on error handling - Add COOP redirect bridge setup documentation for various frameworks
1 parent b3d4888 commit 33b9647

5 files changed

Lines changed: 501 additions & 61 deletions

File tree

‎docs/errors.md‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -847,7 +847,7 @@ The redirect bridge is a mechanism that enables authentication flows in COOP (Cr
847847

848848
This timeout typically occurs for the following reasons:
849849

850-
1. The page you use as your `redirectUri` is not loading the `msal-redirect-bridge.js` script
850+
1. The page you use as your `redirectUri` is not loading the redirect bridge script (either via the ESM import from `@azure/msal-browser/redirect-bridge` or the UMD bundle `msal-redirect-bridge(.min).js`)
851851
1. The redirect page is removing or manipulating the URL hash before the bridge script can process it
852852
1. The redirect page is automatically navigating to a different page before the bridge can communicate the response
853853
1. Your identity provider is being slow to redirect back to your `redirectUri` (network latency)
@@ -857,7 +857,28 @@ This timeout typically occurs for the following reasons:
857857

858858
✔️ **Ensure the redirect bridge script is loaded:**
859859

860-
Your `redirectUri` page must include the redirect bridge script to enable communication back to the main window:
860+
Your `redirectUri` page must include the redirect bridge script to enable communication back to the main window.
861+
862+
**Option A — ESM (recommended for apps using a bundler such as Vite or Webpack):**
863+
864+
```html
865+
<!DOCTYPE html>
866+
<html>
867+
<head>
868+
<title>Redirect</title>
869+
</head>
870+
<body>
871+
<script type="module">
872+
import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";
873+
broadcastResponseToMainFrame().catch(console.error);
874+
</script>
875+
</body>
876+
</html>
877+
```
878+
879+
**Option B — UMD (for static pages served without a bundler):**
880+
881+
Copy `msal-redirect-bridge.min.js` from `node_modules/@azure/msal-browser/lib/redirect-bridge/` to your public directory, then reference it directly:
861882

862883
```html
863884
<!DOCTYPE html>
@@ -866,14 +887,16 @@ Your `redirectUri` page must include the redirect bridge script to enable commun
866887
<title>Redirect</title>
867888
</head>
868889
<body>
869-
<script src="path/to/msal-redirect-bridge.js"></script>
890+
<script src="/msal-redirect-bridge.min.js"></script>
870891
<script>
871-
msalRedirectBridge.sendRedirectPayloadToMainFrame();
892+
msalRedirectBridge.broadcastResponseToMainFrame().catch(console.error);
872893
</script>
873894
</body>
874895
</html>
875896
```
876897

898+
For framework-specific setup instructions (Angular, React, Next.js, Vite, Webpack), see the [redirect bridge guide](../lib/msal-browser/docs/redirect-bridge.md).
899+
877900
**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.
878901

879902
**Issues caused by the redirectUri page:**
@@ -882,7 +905,7 @@ When you make a silent call, in some cases, an iframe will be opened and will na
882905

883906
✔️ To solve this problem you should ensure that the page you use as your `redirectUri` is not doing any of these things.
884907

885-
Remember that you will need to register `redirectUri` on your App Registration. We recommend using the HTML code shown above as the content for your registered redirect page.
908+
Remember that you will need to register `redirectUri` on your App Registration. We recommend using one of the HTML snippets above as the content for your registered redirect page.
886909

887910
**Notes regarding Angular and React:**
888911

‎lib/msal-browser/docs/login-user.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ Your `redirectUri` must point to a dedicated page that loads the redirect bridge
183183
3. **Not include routing logic** - Avoid router libraries that might interfere with hash handling
184184
4. **Be registered in your App Registration** - The URI must match exactly what's registered in Azure portal
185185

186-
**Example redirect page:**
186+
**Example redirect page (when using a bundler such as Vite or Webpack):**
187187

188188
```html
189189
<!DOCTYPE html>
@@ -193,14 +193,18 @@ Your `redirectUri` must point to a dedicated page that loads the redirect bridge
193193
</head>
194194
<body>
195195
<p>Processing authentication...</p>
196-
<script src="path/to/msal-redirect-bridge.js"></script>
197-
<script>
198-
msalRedirectBridge.sendRedirectPayloadToMainFrame();
196+
<script type="module">
197+
import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";
198+
199+
broadcastResponseToMainFrame();
199200
</script>
200201
</body>
201202
</html>
202203
```
203204

205+
> [!NOTE]
206+
> The `@azure/msal-browser/redirect-bridge` specifier must be resolved by a bundler (Vite, Webpack, etc.) — it is not a URL that browsers can fetch directly. For framework-specific instructions, see the [Redirect Bridge setup guide](./redirect-bridge.md).
207+
204208
### Configuration
205209

206210
You can set the `redirectUri` globally in your MSAL configuration or on a per-request basis:
@@ -236,10 +240,10 @@ For more information and complete sample implementations, see:
236240

237241
For popup flows, you can use the `overrideInteractionInProgress` flag to cancel a pending interaction and start a new one. This is useful for recovery scenarios where the user cancelled a popup or an interaction failed.
238242

239-
> [!NOTE]
243+
> [!NOTE]
240244
> This feature is **only available for popup flows** and is **not supported for redirect flows**. With the COOP (Cross-Origin-Opener-Policy) header, the traditional `window.opener` connection is severed, allowing popup windows to communicate with the main frame only via BroadcastChannel.
241245
242-
> [!CAUTION]
246+
> [!CAUTION]
243247
> Setting this to `true` will forcefully cancel any pending popup authentication request but **will not** close any open popups.
244248
245249
**When set to `true`:**

0 commit comments

Comments
 (0)