@azure/msal-browser

@azure/msal-browser is Microsoft’s official client library for adding sign-in and token acquisition to browser-based single-page applications. It implements the OAuth 2.0 Authorization Code Flow with PKCE against Microsoft Entra ID (Azure AD), Microsoft personal accounts, and Azure AD B2C identity providers, handling redirect and popup login flows, silent token renewal via hidden iframes, and secure token caching in the browser without a backend server.

Built as one package in the msal.js monorepo alongside @azure/msal-common, @azure/msal-node, and framework wrappers for Angular and React, msal-browser exposes a single PublicClientApplication entry point backed by pluggable interaction clients for popup, redirect, silent-iframe, and silent-refresh flows, plus dedicated support for nested app authentication (Office Add-ins, Teams tabs) and native broker scenarios on Windows.

What You Get

• A PublicClientApplication class exposing loginPopup, loginRedirect, acquireTokenSilent, and ssoSilent methods for the full authentication lifecycle
• Automatic silent token renewal via hidden iframes with fallback to interactive popup or redirect when silent renewal fails
• Pluggable browser token cache with support for localStorage, sessionStorage, memory, and cookie storage backends
• Built-in account management for multi-account scenarios, including getAllAccounts and account filtering by tenant or home account
• Nested app authentication support for Office Add-ins and Teams tabs via the @azure/msal-browser controllers for non-standard operating contexts
• A dedicated custom-auth entry point for native, redirect-free sign-up/sign-in UI flows against Entra External ID

Common Use Cases

• Signing users into a React, Angular, or vanilla JS single-page app against a company’s Microsoft Entra tenant
• Acquiring access tokens to call Microsoft Graph or a protected backend API from client-side code
• Supporting Azure AD B2C consumer sign-up/sign-in flows for public-facing web apps
• Adding single sign-on so a signed-in user is silently recognized across multiple first-party apps
• Embedding authenticated Microsoft identity flows inside an Office Add-in or Microsoft Teams tab

Under The Hood

Architecture

The library separates concerns into app (the public PublicClientApplication facade), controllers (StandardController for normal browser contexts, NestedAppAuthController for Office/Teams host scenarios, UnknownOperatingContextController as a fallback), and interaction_client (BaseInteractionClient specialized into PopupClient, RedirectClient, SilentIframeClient, SilentRefreshClient, SilentCacheClient, and HybridSpaAuthorizationCodeClient). This controller-per-operating-context design lets the same public API route to entirely different token-acquisition strategies depending on whether the app is running in a normal browser tab or hosted inside another application, while cache/BrowserCacheManager and its storage adapters (LocalStorage, SessionStorage, CookieStorage, MemoryStorage, DatabaseStorage) isolate persistence from protocol logic. Changing the core @azure/msal-common request/response contracts that this package depends on would ripple through every interaction client.

Tech Stack

Written entirely in TypeScript and built with Rollup into dual ESM/CJS output plus generated .d.ts/.d.cts type declarations, using conditional exports map entries for the main bundle and separate custom-auth, redirect-bridge, and popup-relay sub-entry points. The only runtime dependency is the sibling @azure/msal-common package from the same monorepo; tests run on Jest with jest-environment-jsdom and fake-indexeddb for browser-API simulation, and packaging is coordinated across the monorepo via npm workspaces and the beachball semantic-versioning tool.

Code Quality

The package ships roughly 100 Jest spec files covering interaction clients, cache managers, crypto helpers, and controllers, with coverage tracked through Codecov and enforced in Azure Pipelines CI (.pipelines) rather than GitHub Actions. ESLint (via a shared eslint-config-msal workspace package) and Prettier enforce consistent style, TypeScript’s strict settings catch type errors at build time, and error handling is centralized into typed BrowserAuthError, BrowserConfigurationAuthError, and NestedAppAuthError classes with dedicated error-code enums rather than ad hoc thrown strings.

API Design The public surface is a single PublicClientApplication class with consistently named methods (loginPopup/loginRedirect/acquireTokenSilent/ssoSilent/logout), which keeps the getting-started path to a handful of calls, though the full configuration surface (authority, cache, system, telemetry options) is large and documented across a dozen separate markdown guides in docs/ rather than in a single reference. Extensive migration guides for each major version (v1 through v4) reduce upgrade friction for a library with a wide, long-lived install base.