Skip to content

Latest commit

 

History

History
127 lines (97 loc) · 14.9 KB

configuration.md

File metadata and controls

127 lines (97 loc) · 14.9 KB

Configuration Options

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.

In this document:

Usage

The configuration object 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 authentication flow, tenant and application model.

Configuration object with all supported parameters is as below:

// Call back APIs which automatically write and read into a .json file - example implementation
const beforeCacheAccess = async (cacheContext) => {
    cacheContext.tokenCache.deserialize(await fs.readFile(cachePath, "utf-8"));
};

const afterCacheAccess = async (cacheContext) => {
    if(cacheContext.cacheHasChanged){
        await fs.writeFile(cachePath, cacheContext.tokenCache.serialize());
    }
};

// Cache Plugin
const cachePlugin = {
    beforeCacheAccess,
    afterCacheAccess
};;

const msalConfig = {
    auth: {
        clientId: "enter_client_id_here",
        authority: "https://login.microsoftonline.com/common",
        knownAuthorities: [],
        cloudDiscoveryMetadata: "",
        azureCloudOptions: {
            azureCloudInstance: "enter_AzureCloudInstance_here" // AzureCloudInstance enum is exported as a "type",
            tenant: "enter_tenant_info" // defaults to "common"
        }
    },
    cache: {
        cachePlugin // your implementation of cache plugin
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: msal.LogLevel.Verbose,
        },
        proxyUrl: "",
        customAgentOptions: {},
    }
}

const msalInstance = new PublicClientApplication(msalConfig);

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 URIs that are known to be valid. Used in B2C scenarios. 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 ""
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 []
protocolMode Enum representing the protocol mode to use. If "AAD", will function on the AAD v2 endpoints; if "OIDC", will function on OIDC-compliant endpoints. string "AAD"
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
skipAuthorityMetadataCache A flag to choose whether to use the local metadata cache during authority initialization. Metadata cache would be used if no authority metadata is provided in configuration and before a network call for metadata has been made (see Authority) boolean false

Cache Config Options

Option Description Format Default Value
cachePlugin Cache plugin with call backs to reading and writing into the cache persistence (see also: caching) ICachePlugin null

Broker Config Options

Option Description Format Default Value
nativeBrokerPlugin Broker plugin for acquiring tokens via a native token broker (see also: brokering) INativeBrokerPlugin null

System Config Options

Option Description Format Default Value
loggerOptions Config object for logger. See below. See below.
NetworkClient Custom HTTP implementation INetworkModule HttpClient.ts
proxyUrl The URL of the proxy the app is running behind string Empty string ""
customAgentOptions Set of configurable options to set on a http(s) agent Object - NodeJS documentation on alloweable options Empty Object {}
disableInternalRetries A flag that disables MSALJS's built-in retry policies, allowing the app developer to specify their own retry policy. Currently, only Managed Identity flows have a retry policy. boolean 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

Telemetry Config Options

Option Description Format Default Value
application Telemetry options for applications using MSAL.js See below See below

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 ""

Next Steps

Proceed to understand the public APIs provided by msal-node for acquiring tokens here