Android Microsoft Authentication Library configuration file

  • Article

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 00001111-aaaa-2222-bbbb-3333cccc4444

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

  1. 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.

  2. 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);