Micro-Frontend Authentication with a BFF
On this page
The authentication trap
Picture each team adding sign-in its own way. The cart uses one OAuth library, the account area another. Each keeps an access token in the browser. Now there are five token stores for an attacker to read, five refresh flows that race each other, and five slightly different "you've been signed out" experiences.
Authentication is a cross-cutting concern, and it belongs below the micro-frontends, not inside them.
One BFF, one session
The cleanest pattern pairs the shell with a Backend for Frontend on the same origin, as the BFF course in this series builds in detail:
- The BFF runs the OpenID Connect sign-in and keeps the tokens on the server.
- The browser holds one
HttpOnlysession cookie,__Host-Http-sid, which no JavaScript can read. - Every micro-frontend calls the BFF with relative URLs like
/api/cart, and the browser sends the cookie automatically.
So no micro-frontend ever handles a token. "Who is signed in" becomes a plain question to the BFF: GET /bff/user.
What the shell does
The shell owns the session *experience*, not the tokens:
// shell: find out who's signed in once, and share it as a prop
const res = await fetch('/bff/user', { headers: { 'x-csrf': '1' } });
const user = res.ok ? (await res.json()).user : null;
const props = (basePath: string): MountProps => ({
basePath, currency: 'USD', navigate,
user, // { sub, name } or null: display data, not a credential
signIn: () => location.assign(`/auth/login?returnTo=${encodeURIComponent(location.pathname)}`),
});user is for display and decisions about what to show, like "Hello, Ada" or hiding the "Orders" link when signed out. It's not proof of anything. The BFF and the services behind it still check every request.
One fetch helper for every team
All micro-frontends call the BFF the same way. Put the helper in the contract package so nobody reinvents it:
// @shop/contract
export async function bff(path: string, init: RequestInit = {}) {
const res = await fetch(path, {
...init,
headers: {
'x-csrf': '1', // the BFF's CSRF check
...(init.body ? { 'content-type': 'application/json' } : {}),
...init.headers,
},
});
if (res.status === 401) {
window.dispatchEvent(new CustomEvent('shop:session-expired'));
throw new Error('Signed out');
}
return res;
}A 401 from any team's call raises one event, shop:session-expired, and the shell decides what to do: show "Your session ended, sign in again" once, then send the user to /auth/login with a returnTo. Five teams don't each build their own expired-session dialog.
The x-csrf header satisfies the BFF's CSRF defense: a fixed custom header that cross-site requests can't send without a CORS preflight the BFF refuses.
Who owns which BFF routes
With one BFF behind several teams, ownership needs care, or the BFF becomes a shared monolith. A practical split:
- Shared, owned by the platform team:
/auth/*,/bff/user, session handling, the CSRF check, and the proxy plumbing. - Per team, owned by each team: their own route prefix, like
/bff/cart/*and/api/cart/*, in their own module of the BFF, with their own tests and review.
Some organizations go further and give each team its own small BFF behind a router on the same origin, sharing only the session store. That's more independent and more infrastructure. Start with one BFF and clear module ownership, and split when a team's release pace really demands it.
Data each micro-frontend fetches itself
Each micro-frontend fetches its own data from its own routes, at mount time. The shell doesn't load data on teams' behalf, because then every data change would need a shell change.
The one exception is data every micro-frontend needs, like the current user. Load it once in the shell and pass it down, rather than having five teams call /bff/user on every page.
If two micro-frontends need the *same* data, like a product's price on both the product page and the cart, both read it from the service that owns it. Don't pass it between micro-frontends in events, where it can go stale.
Signing out
Sign-out must end the BFF session, the identity provider's session and every micro-frontend's view of the user:
- The shell calls
POST /auth/logoutwith thex-csrfheader. - The BFF destroys the session, clears the cookie and returns the provider's end-session URL.
- The shell sends the browser there with a full page navigation, which also discards every micro-frontend's in-memory state.
A full navigation is simpler and safer than asking each micro-frontend to forget its data. To sign out other open tabs too, post a message on a BroadcastChannel('shop-session'), and have each tab's shell reload when it hears it.
document.cookie for auth, or store user data in localStorage "for convenience". The session lives in the BFF, and the shell's user prop is the only client-side copy.Check yourself
It multiplies token storage in the browser, so there are more places for an injected script to steal from. It creates several refresh flows that race each other, and inconsistent sign-out experiences. One BFF session, shared by every micro-frontend through an HttpOnly cookie, avoids all of that and keeps tokens off the browser entirely.
No. The prop is display data that lives in the browser, where any script can change it. Decisions about what data a user may see must happen on the server, in the BFF and the services behind it, on every request. The cart can use user to show a name or hide a link, nothing more.
The shared bff() helper raises shop:session-expired, and the shell shows one consistent message and sends the user to sign in with a returnTo, so each team doesn't build its own handling.
A full navigation discards every micro-frontend's memory and caches in one step, so no team has to write cleanup code and nothing can be forgotten. It also lets the identity provider end its own session through its end-session URL.
Load the current user once in the shell and pass it down as a prop. It's needed by everyone, rarely changes during a page view, and five duplicate calls add load and latency for nothing.