Skip to main content

How to Add the MSAL Redirect Bridge Page to a Next.js App

· 10 min read
Jagdish Kumawat
Founder @ Dewiride

MSAL Browser 5, the library behind Microsoft Entra ID sign-in in the browser, no longer finishes a sign-in on whatever page Microsoft sends the response to. It wants a small page of its own, the redirect bridge, that hands the response back to your app. This guide adds that page to a Next.js App Router app, with every setting MSAL's documentation asks for.

Why the Bridge Exists​

When someone signs in, Microsoft sends the response to your app's redirect URI. With MSAL 4, the page at that address processed the response itself. MSAL 5 adds support for Cross-Origin-Opener-Policy (COOP), a browser security header that cuts the connection between windows of different origins. MSAL's migration guide explains the problem it solves: with COOP headers on the sign-in service's responses, traditional popup and silent iframe authentication flows will fail because the authentication window cannot communicate back to the main application window. It also notes that Microsoft Entra ID … has COOP enabled by default.

The redirect bridge is MSAL 5's answer: a page on your own site that receives the response and passes it back with broadcastResponseToMainFrame(). For a redirect sign-in, the whole page went to Microsoft, and the bridge sends it back to where it started. For popups and silent sign-ins, it hands the response to the waiting page and closes the window. MSAL's documentation is clear that the bridge isn't optional: when your redirectUri points to it and it's missing, those redirect flows will also fail.

The example is a Next.js 16 app that signs people in with MSAL React 5 and runs on http://localhost:3000; its bridge lives at /redirect (How to Sign Users In to a Next.js App with MSAL React).

Prerequisites​

  • The redirect URI registered: your app's registration in Microsoft Entra ID lists http://localhost:3000/redirect as a single-page application redirect URI. MSAL's documentation warns that it must match exactly — including path, protocol, and port.

Step 1: Create the Bridge Page​

In the App Router, a page is a page.tsx in a folder named after its path. Create app/redirect/page.tsx:

app/redirect/page.tsx
"use client";

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

// Microsoft sends the sign-in response here. This page passes it back to the
// page that started the sign-in. It must stay outside MsalProvider.
export default function Redirect() {
useEffect(() => {
broadcastResponseToMainFrame().catch((error: unknown) => {
console.error("Couldn't pass the sign-in response on.", error);
});
}, []);

return <p>Signing in…</p>;
}

macOS-style code window titled app/redirect/page.tsx showing a client component that imports broadcastResponseToMainFrame from @azure/msal-browser/redirect-bridge, calls it once in a useEffect with a catch that logs Couldn't pass the sign-in response on., and renders Signing in…

LineWhy
"use client"The response is in the browser's address bar, so the page must run in the browser. MSAL's App Router instructions say the page must be a Client Component
@azure/msal-browser/redirect-bridgeThe bridge's own entry point in MSAL Browser
useEffect(…, [])Runs once, after the page appears in the browser
.catch(…)If there's nothing to pass on, the call fails; the page logs why instead of failing silently
<p>Signing in…</p>What people see for the moment the page is on screen

Step 2: Keep It Outside MsalProvider​

The bridge page must not be inside MsalProvider, MSAL React's component that runs MSAL for your pages. MSAL's Next.js instructions say to exclude the redirect route from MsalProvider: if your root layout wraps everything in the provider, give /redirect a layout that doesn't.

The simplest way is not to put the provider in the root layout at all, and to wrap only the pages that need sign-in. In the example, the home page wraps its content in the provider and the root layout stays plain, so /redirect is outside it automatically.

Step 3: Give It a Fixed Title​

The response arrives in the page's address, and that address includes the sign-in code. MSAL's documentation explains the risk: 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. It asks for a static title, present before any JavaScript runs.

In the App Router, a layout's metadata is part of the HTML Next.js sends: the built page starts with <title>Signing in</title>. Give the folder its own app/redirect/layout.tsx:

app/redirect/layout.tsx
import type { Metadata } from "next";

// A fixed title, so the browser tab and history never show the address,
// which carries the sign-in response.
export const metadata: Metadata = {
title: "Signing in",
};

export default function RedirectLayout({ children }: LayoutProps<"/redirect">) {
return children;
}

LayoutProps<"/redirect"> is the type Next.js generates for this route's layout. The layout adds nothing but the title, and it's also where a provider-free layout would go if your root layout had one.

Step 4: Stop Anyone from Caching It​

MSAL's documentation is just as clear about caching: Because the bridge page carries sensitive authentication material in the URL, it must not be cached by any intermediary. Serve the redirect bridge page with Cache-Control: no-store.

Next.js doesn't do that on its own. In production it serves a static page like this one with Cache-Control: s-maxage=31536000, which lets a CDN keep it for a year (Fixed: Next.js Caches the MSAL Redirect Page with "Cache-Control: s-maxage=31536000"). Add a header rule for the page in next.config.ts:

next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
// The sign-in response arrives at /redirect in the page's address, so no
// browser, proxy or CDN may keep a copy of that page.
async headers() {
return [
{
source: "/redirect",
headers: [{ key: "Cache-Control", value: "no-store" }],
},
];
},
};

export default nextConfig;

How headers() works, and why the development server hides the problem, is in How to Set a Cache-Control Header for One Page in Next.js.

The documentation adds two more rules that need no code in a Next.js app: the page must not be served with COOP headers, and it must come from your own site, never from a CDN on another origin, because it handles the raw sign-in response.

Step 5: Point MSAL at It​

Use the page's path for both MSAL redirect settings:

app/auth-provider.tsx (the MSAL settings)
new PublicClientApplication({
auth: {
clientId: process.env.NEXT_PUBLIC_ENTRA_CLIENT_ID ?? "",
authority: `https://login.microsoftonline.com/${process.env.NEXT_PUBLIC_ENTRA_TENANT_ID}`,
redirectUri: "/redirect",
postLogoutRedirectUri: "/redirect",
},
})

redirectUri is where sign-in responses go. postLogoutRedirectUri is where Microsoft sends people after signing out; MSAL's documentation calls pointing both at the bridge the simplest configuration.

Step 6: Check It​

A sign-in. With npm run dev, a sign-in comes back through the bridge; the app's terminal shows the page, then the home page it sends the browser back to:

Output (the app's terminal)
GET /redirect 200 in 57ms (next.js: 11ms, application-code: 46ms)
GET / 200 in 27ms (next.js: 0.8ms, application-code: 26ms)

The production build. npm run build lists the bridge as a static page:

Output
Route (app)
┌ ○ /
├ ○ /_not-found
└ ○ /redirect


○ (Static) prerendered as static content

The header. With npm start running the build, curl -I asks for the page's headers only:

Terminal
curl -I http://localhost:3000/redirect
Response (excerpt)
HTTP/1.1 200 OK
Cache-Control: no-store
x-nextjs-cache: HIT
x-nextjs-prerender: 1
X-Powered-By: Next.js
Content-Type: text/html; charset=utf-8

In PowerShell, write curl.exe instead of curl. The home page, which has no rule, still gets Cache-Control: s-maxage=31536000: the rule changes this one page only.

Common Mistakes​

MistakeWhat happensDo this instead
Wrapping /redirect in MsalProviderMSAL's documentation says the bridge must stay outside itWrap only the pages that need sign-in
Leaving out "use client"The page renders on the server, and the call never runs in the browserMake the page a client component
No Cache-Control: no-storeIn production, Next.js marks the page as cacheable for a yearAdd the headers() rule
Setting the title from JavaScriptThe raw address shows in the tab and history until the script runsUse a layout's metadata, which is in the HTML
A redirect URI that doesn't match the registrationMicrosoft refuses to send the responseRegister http://localhost:3000/redirect exactly

Troubleshooting​

SymptomLikely causeFix
The page stays on Signing in…, and the console shows Couldn't pass the sign-in response on. BrowserAuthError: empty_responseThe page was opened without a sign-in response in its address, such as by typing /redirectExpected: start the sign-in from your app's button
The error appears twice in the console in developmentReact's development mode runs effects twice to catch mistakesExpected in npm run dev only
curl -I shows s-maxage=31536000 for /redirectThe headers() rule is missing, or the build is older than the ruleAdd the rule, then npm run build again
Popups or silent sign-ins time outThe bridge page is missing or broken: MSAL's documentation says those flows depend on itCheck that the page exists at the redirectUri and calls broadcastResponseToMainFrame()

FAQ​

Does the page have to be at /redirect?​

No. Any path works, as long as redirectUri points to it and the registration lists it exactly. /redirect is the path MSAL's examples use.

Can the bridge be the home page?​

MSAL's documentation describes the bridge as its own page, outside MsalProvider. Your home page is usually inside the provider, so keep them apart.

Does sign-out need the bridge?​

For logoutRedirect(), the documentation calls it optional: when the postLogoutRedirectUri page has the bridge, it will navigate the user back to the origin page. For logoutPopup(), it's required.

Conclusion​

MSAL Browser 5 hands every sign-in response to a redirect bridge page. In a Next.js App Router app, that's app/redirect/page.tsx: a client component calling broadcastResponseToMainFrame(), outside MsalProvider, with a static Signing in title from its layout and Cache-Control: no-store from a headers() rule. Point redirectUri and postLogoutRedirectUri at it, register the exact address, and check the header in a production build.

Additional Resources​