Android Microsoft Authentication Library configuration file

Article
11/13/2024

The Android Microsoft Authentication Library (MSAL) ships with a default configuration JSON file that you customize to define the behavior of your public client app for things such as the default authority, which authorities you'll use, and so on.

This article will help you understand the various settings in the configuration file and how to specify the configuration file to use in your MSAL-based app.

Configuration settings

General settings

Property	Data Type	Required	Notes
`client_id`	String	Yes	Your app's Client ID from the Application registration page
`redirect_uri`	String	Yes	Your app's Redirect URI from the Application registration page
`broker_redirect_uri_registered`	Boolean	No	Possible values: `true`, `false`
`authorities`	List<Authority>	No	The list of authorities your app needs
`authorization_user_agent`	AuthorizationAgent (enum)	No	Possible values: `WEBVIEW`, `BROWSER`
`http`	HttpConfiguration	No	Configure `HttpUrlConnection` `connect_timeout` and `read_timeout`
`logging`	LoggingConfiguration	No	Specifies the level of logging detail. Optional configurations include: `pii_enabled`, which takes a boolean value, and `log_level`, which takes `ERROR`, `WARNING`, `INFO`, or `VERBOSE`.

client_id

The client ID or app ID that was created when you registered your application.

redirect_uri

The redirect URI you registered when you registered your application. If the redirect URI is to a broker app, refer to Redirect URI for public client apps to ensure you're using the correct redirect URI format for your broker app.

broker_redirect_uri_registered

If you want to use brokered authentication, the broker_redirect_uri_registered property must be set to true. In a brokered authentication scenario, if the application isn't in the correct format to talk to the broker as described in Redirect URI for public client apps, the application validates your redirect URI and throws an exception when it starts.

authorities

The list of authorities that are known and trusted by you. In addition to the authorities listed here, MSAL also queries Microsoft to get a list of clouds and authorities known to Microsoft. In this list of authorities, specify the type of the authority and any additional optional parameters such as "audience", which should align with the audience of your app based on your app's registration. The following is an example list of authorities:

// Example AzureAD My Organization
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMyOrg",
        "tenant_id": "contoso.com" // Provide your specific tenant ID here
    }
},
// Example AzureAD Multiple Organizations
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMultipleOrgs"
    }
}

Map Microsoft Entra authority & audience to Microsoft identity platform endpoints

Type	Audience	Tenant ID	Authority_Url	Resulting Endpoint	Notes
Microsoft Entra ID	AzureADMyOrg	contoso.com		`https://login.partner.microsoftonline.cn/contoso.com`	Only accounts present in contoso.com can acquire a token. Any verified domain, or the tenant GUID, may be used as the tenant ID.
Microsoft Entra ID	AzureADMultipleOrgs			`https://login.partner.microsoftonline.cn/organizations`	Only Microsoft Entra accounts can be used with this endpoint. Microsoft accounts can be members of organizations. To acquire a token using a Microsoft account for a resource in an organization, specify the organizational tenant from which you want the token.
B2C			See Resulting Endpoint	`https://login.partner.microsoftonline.cn/tfp/contoso.partner.onmschina.cn/B2C_1_SISOPolicy/`	Only accounts present in the contoso.partner.onmschina.cn tenant can acquire a token. In this example, the B2C policy is part of the Authority URL path.

Note

Authority validation cannot be enabled and disabled in MSAL. Authorities are either known to you as the developer as specified via configuration or known to Microsoft via metadata. If MSAL receives a request for a token to an unknown authority, an MsalClientException of type UnknownAuthority results. Brokered authentication does not work for Azure AD B2C.

Authority properties

Property	Data type	Required	Notes
`type`	String	Yes	Mirrors the audience or account type your app targets. Possible values: `AAD`, `B2C`
`audience`	Object	No	Only applies when type=`AAD`. Specifies the identity your app targets. Use the value from your app registration
`authority_url`	String	Yes	Required only when type=`B2C`. Optional for type=`AAD`. Specifies the authority URL or policy your app should use
`default`	boolean	Yes	A single `"default":true` is required when one or more authorities is specified.

Audience Properties

Property	Data Type	Required	Notes
`type`	String	Yes	Specifies the audience your app wants to target. Possible values: `AzureADMultipleOrgs`, `AzureADMyOrg`
`tenant_id`	String	Yes	Required only when `"type":"AzureADMyOrg"`. Optional for other `type` values. This can be a tenant domain such as `contoso.com`, or a tenant ID such as `aaaabbbb-0000-cccc-1111-dddd2222eeee`

authorization_user_agent

Indicates whether to use an embedded webview, or the default browser on the device, when signing in an account or authorizing access to a resource.

Possible values:

WEBVIEW: Use the embedded web view.
BROWSER: Uses the default browser on the device.

multiple_clouds_supported

For clients that support multiple national clouds, specify true. The Microsoft identity platform will then automatically redirect to the correct national cloud during authorization and token redemption. You can determine the national cloud of the signed-in account by examining the authority associated with the AuthenticationResult. Note that the AuthenticationResult doesn't provide the national cloud-specific endpoint address of the resource for which you request a token.

broker_redirect_uri_registered

A boolean that indicates whether you're using a Microsoft Identity broker compatible in-broker redirect URI. Set to false if you don't want to use the broker within your app.

http

Configure global settings for HTTP timeouts, such as:

Property	Data type	Required	Notes
`connect_timeout`	int	No	Time in milliseconds
`read_timeout`	int	No	Time in milliseconds

logging

The following global settings are for logging:

Property	Data Type	Required	Notes
`pii_enabled`	boolean	No	Whether to emit personal data
`log_level`	string	No	Which log messages to output. Supported log levels include `ERROR`,`WARNING`,`INFO`, and `VERBOSE`.
`logcat_enabled`	boolean	No	Whether to output to log cat in addition to the logging interface

account_mode

Specifies how many accounts can be used within your app at a time. The possible values are:

MULTIPLE (Default)
SINGLE

Constructing a PublicClientApplication using an account mode that doesn't match this setting will result in an exception.

For more information about the differences between single and multiple accounts, see Single and multiple account apps.

browser_safelist

An allow-list of browsers that are compatible with MSAL. These browsers correctly handle redirects to custom intents. You can add to this list. The default is provided in the default configuration shown below. ``

The default MSAL configuration file

The default MSAL configuration that ships with MSAL is shown below. You can see the latest version on GitHub.

This configuration is supplemented by values that you provide. The values you provide override the defaults.

{
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADMyOrg"
      },
      "default": true
    }
  ],
  "authorization_user_agent": "DEFAULT",
  "multiple_clouds_supported": false,
  "broker_redirect_uri_registered": false,
  "http": {
    "connect_timeout": 10000,
    "read_timeout": 30000
  },
  "logging": {
    "pii_enabled": false,
    "log_level": "WARNING",
    "logcat_enabled": false
  },
  "shared_device_mode_supported": false,
  "account_mode": "MULTIPLE",
  "browser_safelist": [
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "45"
    },
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "cD2eF3gH4iJ5kL6mN7-oP8qR9sT=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "eF3gH4iJ5kL6mN7oP8-qR9sT0uV=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "gH4iJ5kL6mN7oP8qR9-sT0uV1wX=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "57"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "iJ5kL6mN7oP8qR9sT0-uV1wX2yZ=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "4.0"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "kL6mN7oP8qR9sT0uV1-wX2yZ3aB=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.cloudmosa.puffinFree",
      "browser_signature_hashes": [
        "mN7oP8qR9sT0uV1wX2-yZ3aB4dE="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.duckduckgo.mobile.android",
      "browser_signature_hashes": [
        "S5Av4...jAi4Q=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.explore.web.browser",
      "browser_signature_hashes": [
        "BzDzB...YHCag=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.ksmobile.cb",
      "browser_signature_hashes": [
        "lFDYx...7nouw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.microsoft.emmx",
      "browser_signature_hashes": [
        "Ivy-R...A6fVQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.browser",
      "browser_signature_hashes": [
        "FIJ3I...jWJWw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.mini.native",
      "browser_signature_hashes": [
        "TOTyH...mmUYQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "mobi.mgeek.TunnyBrowser",
      "browser_signature_hashes": [
        "RMVoXgjjgyjjmbj4578fcbkyyQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "org.mozilla.focus",
      "browser_signature_hashes": [
        "L72dT...q0oYA=="
      ],
      "browser_use_customTab" : false
    }
  ]
}

Example basic configuration

The following example illustrates a basic configuration that specifies the client ID, redirect URI, whether a broker redirect is registered, and a list of authorities.

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "redirect_uri" : "msauth://com.microsoft.identity.client.sample.local/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "broker_redirect_uri_registered": true,
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADMyOrg"
      }
      "default": true
    }
  ]
}

How to use a configuration file

Create a configuration file. We recommend that you create your custom configuration file in res/raw/auth_config.json. But you can put it anywhere that you wish.

Tell MSAL where to look for your configuration when you construct the PublicClientApplication. For example:

//On Worker Thread
IMultipleAccountPublicClientApplication sampleApp = null; 
sampleApp = new PublicClientApplication.createMultipleAccountPublicClientApplication(getApplicationContext(), R.raw.auth_config);

Android Microsoft Authentication Library configuration file

Configuration settings

General settings

client_id

redirect_uri

broker_redirect_uri_registered

authorities

Map Microsoft Entra authority & audience to Microsoft identity platform endpoints

Authority properties

Audience Properties

authorization_user_agent

multiple_clouds_supported

broker_redirect_uri_registered

http

logging

account_mode

browser_safelist

The default MSAL configuration file

Example basic configuration

How to use a configuration file

Additional resources