Redirect Bridge

This guide provides framework-specific instructions for setting up the redirect bridge page introduced in MSAL Browser v5. For background on why the redirect bridge is needed, see the v4 to v5 migration guide.

Important: The redirect bridge page must NOT be served with Cross-Origin-Opener-Policy headers. The bridge page is an intermediary that receives the authentication response after the IdP completes the OAuth flow. If COOP headers are set on the bridge page, the browser performs a browsing context group swap that severs the communication channel back to the main application — reintroducing the exact problem the bridge is designed to solve.

Logout and the Redirect Bridge

logoutPopup() — redirect bridge is required

When using logoutPopup(), the postLogoutRedirectUri must point to a page that implements the redirect bridge (calls broadcastResponseToMainFrame()). After ESTS completes the sign-out, it redirects the popup to the postLogoutRedirectUri. The redirect bridge on that page broadcasts the response back to the main window and closes the popup. Without the bridge, the popup will remain open after logout because COOP headers prevent the main window from closing it directly.

The simplest configuration is to set postLogoutRedirectUri to the same value as redirectUri:

const msalConfig = {
    auth: {
        clientId: "{your-client-id}",
        redirectUri: "/redirect",
        postLogoutRedirectUri: "/redirect", // Must host the redirect bridge
    },
};

logoutRedirect() — redirect bridge is optional

For logoutRedirect(), hosting the redirect bridge on the postLogoutRedirectUri page is optional. The redirect flow navigates the entire browser window, so there is no popup to close. If the redirect bridge is present on the postLogoutRedirectUri page, it will navigate the user back to the origin page. If not, ESTS will redirect the user directly to the postLogoutRedirectUri page and the user stays there.

Cross-Origin Iframe Limitation

The redirect bridge relies on the BroadcastChannel API to send the authentication response from the popup back to the main application window. Starting with Chromium 115+ (Chrome, Edge, and other Chromium-based browsers), third-party storage partitioning is enforced, which means BroadcastChannel is partitioned by top-level site, not just by origin. Other browsers are expected to adopt similar partitioning in the future.

This causes popup-based flows to fail when your application runs inside a cross-origin iframe:

Context	Top-level site	BroadcastChannel partition
Your app in the iframe	hostplatform.com	hostplatform.com
Popup opened by the iframe	yourapp.com (popup is its own top-level context)	yourapp.com

Although both the iframe and the popup share the same origin (yourapp.com), the popup is in a different storage partition. The redirect bridge sends the response on a BroadcastChannel in the popup's partition, but the iframe is listening on a channel in the host platform's partition — the message never arrives, and the authentication flow times out.

Recommended alternatives for cross-origin iframe scenarios

Option 1: Nested App Authentication (recommended)

If the host platform supports it, use Nested App Authentication (NAA). With NAA, the iframe delegates authentication entirely to the host application via createNestablePublicClientApplication. The host authenticates the user at the top level (where there are no partitioning issues) and provides tokens to the nested app through the NAA bridge. This avoids popup and silent flows from within the iframe altogether.

import { createNestablePublicClientApplication } from "@azure/msal-browser";

const pca = await createNestablePublicClientApplication({
    auth: {
        clientId: "your-client-id",
        authority: "https://login.microsoftonline.com/your-tenant-id",
    },
});

NAA is supported out of the box by Microsoft host platforms such as Teams, Outlook, and Microsoft 365. For custom host platforms, the host must implement the NAA bridge protocol. If the NAA bridge is not available, createNestablePublicClientApplication automatically falls back to a standard PublicClientApplication.

Option 2: Redirect flow within the iframe (fallback)

If NAA is not available, use loginRedirect() / acquireTokenRedirect() instead of popup APIs. The redirect flow happens entirely within the iframe's browsing context and does not use BroadcastChannel, so the redirect bridge partition mismatch does not apply. You will need to set system.allowRedirectInIframe: true:

const msalConfig = {
    auth: {
        clientId: "your-client-id",
        authority: "https://login.microsoftonline.com/your-tenant-id",
        redirectUri: "/redirect",
    },
    system: {
        allowRedirectInIframe: true,
    },
};

For more information on running MSAL in iframes, see Using MSAL in iframed apps.

Page Title

Always set a meaningful <title> on your redirect bridge page. Without an explicit title, the browser displays the raw redirect URL — which contains authorization codes or tokens — as the tab title and browser history entry.

A good title should:

• Indicate that authentication is in progress (e.g., "Signing in" or "Signing in - MyApp")
• Be static HTML (not set dynamically after JavaScript loads) so it appears immediately

<head>
    <title>Signing in</title>
</head>

This improves:

• User experience — Users see a meaningful tab title instead of a long URL with query parameters
• Browser history — History entries show a descriptive name rather than the raw redirect URL
• Accessibility — Screen readers announce the page title when focus moves to the window or tab

Angular

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

import { Component, OnInit } from "@angular/core";
import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";

@Component({
    selector: "app-redirect",
    standalone: true,
    template: "<p>Processing authentication...</p>",
})
export class RedirectComponent implements OnInit {
    ngOnInit(): void {
        broadcastResponseToMainFrame().catch((error: Error) => {
            console.error("Error broadcasting response to main frame:", error);
        });
    }
}

1. Add the /redirect route in your routing configuration. The redirect route must be outside the MsalGuard, and the redirect page should not make API calls that would trigger MsalInterceptor (or otherwise invoke MSAL APIs):

import { RedirectComponent } from "./redirect/redirect.component";

const routes: Routes = [
    { path: "redirect", component: RedirectComponent },
    // ... your other routes
];

1. Ensure the build includes the component. No angular.json assets change is needed when using an Angular route component — the Angular CLI bundles the component automatically. If you prefer a static redirect.html instead of a routed component, add it to the assets array:

// angular.json
{
    "projects": {
        "your-app": {
            "architect": {
                "build": {
                    "options": {
                        "assets": [
                            { "glob": "**/*", "input": "public" },
                            "src/redirect.html" // ← Add redirect bridge page
                        ]
                    }
                }
            }
        }
    }
}

Sample: See angular-standalone-sample and angular-modules-sample.

Vite

Vite requires a multi-page configuration so that redirect.html is included as a separate entry point in the build output.

1. Create redirect.html in your project root (next to index.html):

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Signing in</title>
</head>
<body>
    <p>Processing authentication...</p>
    <script type="module">
        import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";

        broadcastResponseToMainFrame().catch((error) => {
            console.error("Error broadcasting response:", error);
        });
    </script>
</body>
</html>

1. Update vite.config.ts to add the redirect page as a second entry:

import { defineConfig } from "vite";
import { resolve } from "path";

export default defineConfig({
    build: {
        rollupOptions: {
            input: {
                main: resolve(__dirname, "index.html"),
                redirect: resolve(__dirname, "redirect.html"), // ← Redirect bridge entry
            },
        },
    },
});

During development (vite dev), the redirect page is automatically served at /redirect.html. In production builds, Rollup will emit both index.html and redirect.html in the output directory.

Sample: See the react-router-sample, typescript-sample, and b2c-sample.

Webpack

Webpack requires a dedicated entry point and an HtmlWebpackPlugin instance for the redirect page.

1. Create src/redirect.html:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Signing in</title>
</head>
<body>
    <p>Processing authentication...</p>
    <!-- The redirect script bundle will be injected by HtmlWebpackPlugin (see redirect.js entry). -->
</body>
</html>

1. Create src/redirect.js (entry point for Webpack):

import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";

broadcastResponseToMainFrame().catch((error) => {
    console.error("Error broadcasting response:", error);
});

1. Update webpack.config.js:

const HtmlWebpackPlugin = require("html-webpack-plugin");

module.exports = {
    entry: {
        main: "./src/index.js",
        redirect: "./src/redirect.js", // ← Redirect bridge entry
    },
    plugins: [
        new HtmlWebpackPlugin({
            filename: "index.html",
            template: "./src/index.html",
            chunks: ["main"],
        }),
        new HtmlWebpackPlugin({
            filename: "redirect.html",
            template: "./src/redirect.html",
            chunks: ["redirect"], // ← Only include the redirect chunk
        }),
    ],
};

Next.js

Next.js pages automatically become routes, so the redirect bridge is a page component. The setup differs between the Pages Router and the App Router.

Pages Router (pages/)

1. Create pages/redirect.js:

import { useEffect } from "react";
import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";

export default function Redirect() {
    useEffect(() => {
        broadcastResponseToMainFrame().catch((error) => {
            console.error("Error broadcasting response to main frame:", error);
        });
    }, []);

    return <p>Processing authentication...</p>;
}

1. Exclude the redirect page from MsalProvider in _app.js:

// pages/_app.js
import { useRouter } from "next/router";
import { MsalProvider } from "@azure/msal-react";

function MyApp({ Component, pageProps }) {
    const router = useRouter();

    // The redirect page must NOT be wrapped in MsalProvider
    if (router.pathname === "/redirect") {
        return <Component {...pageProps} />;
    }

    return (
        <MsalProvider instance={msalInstance}>
            <Component {...pageProps} />
        </MsalProvider>
    );
}

App Router (app/)

1. Create app/redirect/page.js — this must be a Client Component ("use client"):

"use client";

import { useEffect } from "react";
import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";

export default function Redirect() {
    useEffect(() => {
        broadcastResponseToMainFrame().catch((error) => {
            console.error("Error broadcasting response to main frame:", error);
        });
    }, []);

    return <p>Processing authentication...</p>;
}

1. Exclude the redirect route from MsalProvider in your root layout. If your app/layout.js wraps children in MsalProvider, create a separate layout for the redirect route that skips it:

// app/redirect/layout.js — no MsalProvider wrapper
export default function RedirectLayout({ children }) {
    return <>{children}</>;
}

This prevents MSAL from processing the auth response hash before broadcastResponseToMainFrame() runs.

---

No next.config.js changes are needed for either router — Next.js serves pages automatically.

Sample: See the nextjs-sample for a Pages Router example.

Express.js / Node.js Backend

When using Express.js (or any Node.js backend serving static files), configure the server to serve the redirect page without COOP headers:

const express = require("express");
const path = require("path");
const app = express();

// Serve the redirect bridge page WITHOUT COOP headers
app.get("/redirect", (req, res) => {
    res.sendFile(path.join(__dirname, "public", "redirect.html"));
});

// Set COOP headers for all other routes
app.use((req, res, next) => {
    res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
    next();
});

app.use(express.static(path.join(__dirname, "public")));

Sample: See the HybridSample.

Additional Resources

• v4 to v5 migration guide — COOP section
• Redirect URI considerations
• Handling popup interaction_in_progress errors
• MDN: Cross-Origin-Opener-Policy