Skip to content

Commit f16b843

Browse files
Enhance redirect bridge documentation (#8433)
Enhance redirect bridge documentation with warnings and cautions about setup and security risks
1 parent 48cd5e0 commit f16b843

2 files changed

Lines changed: 44 additions & 0 deletions

File tree

lib/msal-browser/docs/redirect-bridge.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,34 @@ This guide provides framework-specific instructions for setting up the redirect
1111
> The URI must match **exactly** — including path, protocol, and port.
1212
> Failure to update the app registration will result in `redirect_uri_mismatch` errors.
1313
14+
> [!WARNING]
15+
> If the redirect bridge is **not** set up, all authentication flows that rely
16+
> on a popup or hidden iframe will stop working. `ssoSilent`,
17+
> `acquireTokenPopup`, and `loginPopup` depend on the redirect bridge to
18+
> receive the authentication response from the identity provider.
19+
> `acquireTokenSilent` is also affected when the refresh token is expired and
20+
> MSAL falls back to acquiring a new token in a hidden iframe (the same
21+
> mechanism used by `ssoSilent`). Without the redirect bridge, the popup or
22+
> iframe cannot communicate the response back to the main application window.
23+
>
24+
> Redirect flows (`loginRedirect` / `acquireTokenRedirect`) **can** work
25+
> without the redirect bridge **only if** your `redirectUri` points to a page
26+
> that directly processes the authentication response (for example, using
27+
> `handleRedirectPromise` as in MSAL v4). However, when following the v5
28+
> guidance in this document—where `redirectUri` is set to the redirect bridge
29+
> page that calls `broadcastResponseToMainFrame()`—those redirect flows will
30+
> also fail if the bridge page is missing or not implemented correctly.
31+
32+
> [!CAUTION]
33+
> **Do NOT load the redirect bridge page from a CDN** (e.g., jsdelivr, unpkg,
34+
> cdnjs). The redirect bridge receives the raw authentication response —
35+
> including authorization codes and tokens — directly from the identity
36+
> provider. Loading this page from a third-party CDN creates a **supply-chain
37+
> and token-theft risk**: a compromised CDN asset could intercept the
38+
> authentication response before it reaches your application. Always bundle the
39+
> redirect bridge with your application or serve it from your own
40+
> infrastructure.
41+
1442
## Angular
1543

1644
1. **Create the redirect bridge component** (`src/app/redirect/redirect.component.ts`):

lib/msal-browser/docs/v4-migration.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,22 @@ The setup varies by build system — see the **[Redirect Bridge — Framework-Sp
359359

360360
**See also:** [Redirect URI considerations](./login-user.md#redirecturi-considerations) | [Popup interaction_in_progress errors](./login-user.md#handling-popup-interaction_in_progress-errors) | [MDN: COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy)
361361

362+
> [!WARNING]
363+
> If the redirect bridge is **not** configured correctly (for example, your
364+
> `redirectUri` does not point to a page that runs `broadcastResponseToMainFrame()`),
365+
> popup and iframe-based authentication flows (`ssoSilent`, `acquireTokenPopup`,
366+
> `loginPopup`, and `acquireTokenSilent` when it falls back to a hidden iframe)
367+
> will fail. Redirect-based flows (`acquireTokenRedirect` / `loginRedirect`) will
368+
> still complete, but will not benefit from the redirect bridge isolation and
369+
> optimizations until the bridge is correctly configured.
370+
371+
> [!CAUTION]
372+
> **Do NOT load the redirect bridge page from a CDN** (e.g., jsdelivr, unpkg,
373+
> cdnjs). The bridge receives the raw authentication response and loading it
374+
> from a third-party CDN creates a supply-chain and token-theft risk. Always
375+
> bundle the redirect bridge with your application or serve it from your own
376+
> infrastructure. See the [Redirect Bridge guide](./redirect-bridge.md) for details.
377+
362378
##### 2. Update your MSAL configuration
363379

364380
Point `redirectUri` to a new redirect bridge page:

0 commit comments

Comments
 (0)