Configuration Options

July 1, 2026 · View on GitHub

Before you start here, make sure you understand how to initialize an app object.

The MSAL library has a set of configuration options that can be used to customize the behavior of your authentication flows. These options can be set either in the constructor of the PublicClientApplication object or as part of the request APIs. Here we describe the configuration object that can be passed into the PublicClientApplication constructor.

Using the config object

The configuration object has the following structure, and can be passed into the PublicClientApplication constructor. The only required config parameter is the client ID of the application. Everything else is optional, but may be required depending on your tenant and application model.

const msalConfig = {
    auth: {
        clientId: "enter_client_id_here",
        authority: "https://login.microsoftonline.com/common",
        knownAuthorities: [],
        cloudDiscoveryMetadata: "",
        redirectUri: "enter_redirect_uri_here",
        postLogoutRedirectUri: "enter_postlogout_uri_here",
        navigateToLoginRequestUrl: true,
        clientCapabilities: ["CP1"],
    },
    cache: {
        cacheLocation: "sessionStorage",
    },
    system: {
        loggerOptions: {
            loggerCallback: (
                level: LogLevel,
                message: string,
                containsPii: boolean
            ): void => {
                if (containsPii) {
                    return;
                }
                switch (level) {
                    case LogLevel.Error:
                        console.error(message);
                        return;
                    case LogLevel.Info:
                        console.info(message);
                        return;
                    case LogLevel.Verbose:
                        console.debug(message);
                        return;
                    case LogLevel.Warning:
                        console.warn(message);
                        return;
                }
            },
            piiLoggingEnabled: false,
        },
        windowHashTimeout: 60000,
        iframeHashTimeout: 6000,
        loadFrameTimeout: 0,
        protocolMode: "AAD",
        serverTelemetryEnabled: false,
    },
    telemetry: {
        application: {
            appName: "My Application",
            appVersion: "1.0.0",
        },
    },
};

const msalInstance = new PublicClientApplication(msalConfig);

Configuration Options

Auth Config Options

Option	Description	Format	Default Value
`clientId`	App ID of your application. Can be found in your portal registration.	UUID/GUID	None. This parameter is required in order for MSAL to perform any actions.
`authority`	URI of the tenant to authenticate and authorize with. Usually takes the form of `https://{uri}/{tenantid}` (see Authority)	String in URI format with tenant - `https://{uri}/{tenantid}`	`https://login.microsoftonline.com/common`
`knownAuthorities`	An array of known authority URIs. Used in B2C and CIAM scenarios. For CIAM with Entra External ID, include the GUID-based issuer host if it differs from the authority host (see Authority - CIAM).	Array of strings in URI format	Empty array `[]`
`cloudDiscoveryMetadata`	A string containing the cloud discovery response. Used in AAD scenarios. See Performance for more info	string	Empty string `""`
`authorityMetadata`	A string containing the .well-known/openid-configuration endpoint response. See Performance for more info	string	Empty string `""`
`redirectUri`	URI where the authorization code response is sent back to. Whatever location is specified here must have the MSAL library available to handle the response.	String in absolute or relative URI format	Login request page (`window.location.href` of page which made auth request)
`postLogoutRedirectUri`	URI that is redirected to after a logout() call is made.	String in absolute or relative URI format. Pass `null` to disable post logout redirect.	Login request page (`window.location.href` of page which made auth request)
`popupRelayUri`	URI of a first-party, top-level "popup-relay" page used to acquire tokens (and log out) interactively from inside a cross-origin iframe, where third-party storage partitioning and COOP would otherwise break the popup flow. When set, `acquireTokenPopup`/`logoutPopup` open this page top-level and relay the flow through it. Must be same-origin as the app. See Popup relay for cross-origin iframes.	String in absolute or relative (same-origin) URI format.	Empty string `""` (disabled)
`navigateToLoginRequestUrl`	If `true`, will navigate back to the original request location before processing the authorization code response. If the `redirectUri` is the same as the original request location, this flag should be set to false.	boolean	`true`
`clientCapabilities`	Array of capabilities to be added to all network requests as part of the `xms_cc` claims request (see: Client capability in MSAL)	Array of strings	`[]`
`azureCloudOptions`	A defined set of azure cloud options for developers to default to their specific cloud authorities, for specific clouds supported please refer to the AzureCloudInstance	AzureCloudOptions	AzureCloudInstance.None
`onRedirectNavigate`	A callback that will be passed the url that MSAL will navigate to in redirect flows. Returning false in the callback will stop navigation.	`(url: string) => boolean	void`
`instanceAware`	A flag of whether the STS will send back additional parameters to specify where the tokens should be retrieved from.	boolean	`false`
`isMcp`	If true, a `resource` parameter is required on all token requests. Used for MCP flows. See MCP documentation for more details.	boolean	`false`

popupRelayUri lets acquireTokenPopup (and logoutPopup) work when your app runs inside an untrusted, cross-origin iframe — a context where third-party storage partitioning and COOP normally break the popup flow. When set, MSAL opens the relay page top-level (on your own origin) instead of navigating the popup straight to the identity provider, and that page relays the response back to the embedded frame. No tokens, PKCE verifier, or EAR key cross the window boundary.

Setup:

Host a same-origin page at popupRelayUri that calls runPopupRelay() from the @azure/msal-browser/popup-relay sub-export. It opens the IdP child popup, so call it from a user gesture (e.g. a "Continue" button click) so popup blockers don't block it.
Point your redirectUri (and, for logout, postLogoutRedirectUri) at a page that calls broadcastResponseToMainFrame() from the @azure/msal-browser/redirect-bridge sub-export.

Caveats:

The relay is a browser SPA-only mechanism (PublicClientApplication in @azure/msal-browser). It brokers the standard interactive popup auth-code flow through a same-origin page and is not intended for native app, platform broker (WAM), Nested App Auth, or confidential-client / server-side scenarios.
popupRelayUri must resolve to the same origin as the app; a cross-origin value throws popup_relay_unsupported_flow with sub-error popup_relay_cross_origin (see errors).
The relay page opens the IdP popup, so it must be triggered by a user gesture.
The auth-code (GET), form_post, and EAR response modes are all supported.

Cache Config Options

Option	Description	Format	Default Value
`cacheLocation`	Location of token cache in browser.	String value that must be one of the following: `"sessionStorage"`, `"localStorage"`, `"memoryStorage"`	`sessionStorage`

See Caching in MSAL for more.

System Config Options

Option	Description	Format	Default Value
`loggerOptions`	Config object for logger.	See below.	See below.
`navigatePopups`	Sets whether popups are opened and navigated to later. By default, this flag is set to true. When set to true, blank popups are opened and navigates to login domain. When set to false, popups are opened directly to the login domain. This can be set to false for scenarios where `about:blank` is not supported, e.g. desktop apps or progressive web apps.	boolean	`true`
`allowRedirectInIframe`	By default, MSAL will not allow redirect operations to be initiated when the application is inside an iframe. Set this flag to `true` to remove this check.	boolean	`false`
`cryptoOptions`	Config object for crypto operations in the browser.	See below	See below
`popupBridgeTimeout`	Timeout in milliseconds to wait for the popup to send its response via BroadcastChannel. If the user closes the popup without completing authentication, `loginPopup` or `acquireTokenPopup` will reject with a `timed_out` error after this timeout. See Popup closure detection.	integer (milliseconds)	`60000`
`iframeBridgeTimeout`	Timeout in milliseconds to wait for a hidden iframe to send its response via BroadcastChannel during silent token acquisition (`ssoSilent`, `acquireTokenSilent`). If the iframe does not respond within this time, the call will reject with a `timed_out` error.	integer (milliseconds)	`10000`
`protocolMode`	Enum representing the protocol mode to use. If `"AAD"`, will function on the OIDC-compliant AAD v2 endpoints; if `"OIDC"`, will function on other OIDC-compliant endpoints.	string	`"AAD"`
`serverTelemetryEnabled`	Enables MSER server telemetry headers and browser cache writes for failed requests. When `false`, MSAL does not send MSER headers and does not persist server telemetry data to browser storage. This option is deprecated and will be removed in a future release.	boolean	`false`

Logger Config Options

Option	Description	Format	Default Value
`loggerCallback`	Callback function which handles the logging of MSAL statements.	Function - `loggerCallback: (level: LogLevel, message: string, containsPii: boolean): void`	See above.
`piiLoggingEnabled`	If true, personally identifiable information (PII) is included in logs.	boolean	`false`

Crypto Config Options

Option	Description	Format	Default Value
`useMsrCrypto`	Whether to use MSR Crypto if available in the browser (and other crypto interfaces are not available).	boolean	`false`
`entropy`	Cryptographically strong random values used to seed MSR Crypto (e.g. `crypto.randomBytes(48)` from Node). 48 bits of entropy is recommended. Required if `useMsrCrypto` is enabled.	`Uint8Array`	`undefined`

Telemetry Config Options

Option	Description	Format	Default Value
`application`	Telemetry options for applications using MSAL.js	See below	See below
`client`	Telemetry performance client instance	IPerformanceClient	StubPerformanceClient

Application Telemetry

Option	Description	Format	Default Value
`appName`	Unique string name of an application	string	Empty string ""
`appVersion`	Version of the application using MSAL	string	Empty string ""