Android Microsoft 身份验证库配置文件Android Microsoft Authentication Library configuration file

Android Microsoft 身份验证库 (MSAL) 随附了一个默认的配置 JSON 文件,对此文件进行自定义可以定义公共客户端应用在默认颁发机构、要使用的颁发机构等方面的行为。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.

本文将帮助你了解该配置文件中的各项设置,以及如何指定要在基于 MSAL 的应用中使用的配置文件。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 StringString Yes 应用程序注册页中的应用客户端 IDYour app's Client ID from the Application registration page
redirect_uri StringString Yes 应用程序注册页中的应用重定向 URIYour app's Redirect URI from the Application registration page
authorities List<Authority>List<Authority> No 应用所需的颁发机构列表The list of authorities your app needs
authorization_user_agent AuthorizationAgent(枚举)AuthorizationAgent (enum) No 可能的值:DEFAULTBROWSERWEBVIEWPossible values: DEFAULT, BROWSER, WEBVIEW
http HttpConfigurationHttpConfiguration No 配置 HttpUrlConnection connect_timeoutread_timeoutConfigure HttpUrlConnection connect_timeout and read_timeout
logging LoggingConfigurationLoggingConfiguration No 指定日志记录的详细级别。Specifies the level of logging detail. 可选配置包括:采用布尔值的 pii_enabled,以及采用 ERRORWARNINGINFOVERBOSElog_levelOptional configurations include: pii_enabled, which takes a boolean value, and log_level, which takes ERROR, WARNING, INFO, or VERBOSE.

client_idclient_id

注册应用程序时创建的客户端 ID 或应用 ID。The client ID or app ID that was created when you registered your application.

redirect_uriredirect_uri

注册应用程序时注册的重定向 URI。The redirect URI you registered when you registered your application. 如果重定向 URI 属于某个中介应用,请参阅公共客户端应用的重定向 URI,确保对中介应用使用正确的重定向 URI 格式。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.

authoritiesauthorities

你已知且信任的颁发机构列表。The list of authorities that are known and trusted by you. 除了此处所列的颁发机构以外,MSAL 还会查询 Microsoft,以获取 Microsoft 已知的云和颁发机构列表。In addition to the authorities listed here, MSAL also queries Microsoft to get a list of clouds and authorities known to Microsoft. 在此颁发机构列表中,指定颁发机构的类型,并根据应用的注册指定与应用受众相符的任何其他可选参数(例如 "audience")。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"
    }
}

将 AAD 颁发机构和受众映射到 Microsoft 标识平台终结点Map AAD authority & audience to Microsoft identity platform endpoints

类型Type 目标受众Audience 租户 IDTenant ID Authority_UrlAuthority_Url 生成的终结点Resulting Endpoint 注释Notes
AADAAD AzureADMyOrgAzureADMyOrg contoso.comcontoso.com https://login.partner.microsoftonline.cn/contoso.com 只有 contoso.com 中的帐户才能获取令牌。Only accounts present in contoso.com can acquire a token. 任何已验证的域或租户 GUID 都可用作租户 ID。Any verified domain, or the tenant GUID, may be used as the tenant ID.
AADAAD AzureADMultipleOrgsAzureADMultipleOrgs https://login.partner.microsoftonline.cn/organizations 在此终结点上只能使用 Azure Active Directory 帐户。Only Azure Active Directory accounts can be used with this endpoint. Microsoft 帐户可以是组织的成员。Microsoft accounts can be members of organizations. 若要使用 Microsoft 帐户获取组织中资源的令牌,请指定要从中获取令牌的组织租户。To acquire a token using a Microsoft account for a resource in an organization, specify the organizational tenant from which you want the token.
B2CB2C 参阅“生成的终结点”See Resulting Endpoint https://login.partner.microsoftonline.cn/tfp/contoso.partner.onmschina.cn/B2C_1_SISOPolicy/ 只有 contoso.partner.onmschina.cn 租户中的帐户才能获取令牌。Only accounts present in the contoso.partner.onmschina.cn tenant can acquire a token. 在此示例中,B2C 策略是颁发机构 URL 路径的一部分。In this example, the B2C policy is part of the Authority URL path.

备注

在 MSAL 中无法启用和禁用授权机构验证。Authority validation cannot be enabled and disabled in MSAL. 颁发机构是开发人员已知的、通过配置指定的颁发机构,或者是 Microsoft 已知的、通过元数据指定的颁发机构。Authorities are either known to you as the developer as specified via configuration or known to Microsoft via metadata. 如果 MSAL 收到了向未知颁发机构获取令牌的请求,将导致 UnknownAuthority 类型的 MsalClientExceptionIf MSAL receives a request for a token to an unknown authority, an MsalClientException of type UnknownAuthority results.

颁发机构属性Authority properties

属性Property 数据类型Data type 必须Required 注释Notes
type StringString Yes 镜像应用面向的受众或帐户类型。Mirrors the audience or account type your app targets. 可能的值:AADB2CPossible values: AAD, B2C
audience ObjectObject No 仅当 type=AAD 时才适用。Only applies when type=AAD. 指定应用面向的标识。Specifies the identity your app targets. 使用应用注册中的值Use the value from your app registration
authority_url StringString Yes 仅当 type =B2C 时才是必需的。Required only when type=B2C. 指定应用应该使用的颁发机构 URL 或策略Specifies the authority URL or policy your app should use
default booleanboolean Yes 指定了一个或多个颁发机构时,需要指定单个 "default":trueA single "default":true is required when one or more authorities is specified.

受众属性Audience Properties

属性Property 数据类型Data Type 必须Required 注释Notes
type StringString Yes 指定应用要面向的受众。Specifies the audience your app wants to target. 可能的值:AzureADMultipleOrgsAzureADMyOrgPossible values: AzureADMultipleOrgs, AzureADMyOrg
tenant_id StringString Yes 仅当指定 "type":"AzureADMyOrg" 时才是必需的。Required only when "type":"AzureADMyOrg". 如果指定其他 type 值,则是可选的。Optional for other type values. 这可以是类似于 contoso.com 的租户域,或类似于 72f988bf-86f1-41af-91ab-2d7cd011db46 的租户 IDThis can be a tenant domain such as contoso.com, or a tenant ID such as 72f988bf-86f1-41af-91ab-2d7cd011db46)

authorization_user_agentauthorization_user_agent

指示在登录到某个帐户或授权访问资源时,是要使用嵌入式 Web 视图,还是使用设备上的默认浏览器。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:

  • DEFAULT:首选系统浏览器。DEFAULT: Prefers the system browser. 如果设备上未提供浏览器,则使用嵌入式 Web 视图。Uses the embedded web view if a browser isn't available on the device.
  • WEBVIEW:使用嵌入式 Web 视图。WEBVIEW: Use the embedded web view.
  • BROWSER:使用设备上的默认浏览器。BROWSER: Uses the default browser on the device.

multiple_clouds_supportedmultiple_clouds_supported

对于支持多个国家云的客户端,请指定 trueFor clients that support multiple national clouds, specify true. 然后,在授权和令牌兑换期间,Microsoft 标识平台会自动重定向到正确的国家云。The Microsoft identity platform will then automatically redirect to the correct national cloud during authorization and token redemption. 可以通过检查与 AuthenticationResult 关联的颁发机构来确定登录帐户的国家云。You can determine the national cloud of the signed-in account by examining the authority associated with the AuthenticationResult. 请注意,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_registeredbroker_redirect_uri_registered

一个布尔值,指示是否正在使用 Microsoft 标识中介兼容的中介内重定向 URI。A boolean that indicates whether you're using a Microsoft Identity broker compatible in-broker redirect URI. 如果不想要在应用中使用中介,请设置为 falseSet to false if you don't want to use the broker within your app.

httphttp

配置全局 HTTP 超时设置,例如:Configure global settings for HTTP timeouts, such as:

属性Property 数据类型Data type 必须Required 注释Notes
connect_timeout intint No 时间(毫秒)Time in milliseconds
read_timeout intint No 时间(毫秒)Time in milliseconds

logginglogging

以下全局设置用于日志记录:The following global settings are for logging:

属性Property 数据类型Data Type 必须Required 注释Notes
pii_enabled booleanboolean No 是否发出个人数据Whether to emit personal data
log_level stringstring No 要输出的日志消息。Which log messages to output. 支持的日志级别包括 ERRORWARNINGINFOVERBOSESupported log levels include ERROR,WARNING,INFO, and VERBOSE.
logcat_enabled booleanboolean No 除了输出到日志记录界面以外,是否还要输出到 logcatWhether to output to log cat in addition to the logging interface

account_modeaccount_mode

指定在应用中一次可以使用多少个帐户。Specifies how many accounts can be used within your app at a time. 可能的值包括:The possible values are:

  • MULTIPLE(默认值)MULTIPLE (Default)
  • SINGLE

使用与此设置不匹配的帐户模式构造 PublicClientApplication 会导致异常。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_safelistbrowser_safelist

与 MSAL 兼容的浏览器的允许列表。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. ``

默认的 MSAL 配置文件The default MSAL configuration file

下面显示了 MSAL 随附的默认 MSAL 配置。The default MSAL configuration that ships with MSAL is shown below. 可以在 GitHub 上查看最新版本。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": [
        "7fmduHKTdHHrlMvldlEqAIlSfii1tl35bxj1OXN5Ve8c4lU6URVu4xtSHc3BVZxS6WWJnxMDhIfQN0N0K2NDJg=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "45"
    },
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "7fmduHKTdHHrlMvldlEqAIlSfii1tl35bxj1OXN5Ve8c4lU6URVu4xtSHc3BVZxS6WWJnxMDhIfQN0N0K2NDJg=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "2gCe6pR_AO_Q2Vu8Iep-4AsiKNnUHQxu0FaDHO_qa178GByKybdT_BuE8_dYk99G5Uvx_gdONXAOO2EaXidpVQ=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "2gCe6pR_AO_Q2Vu8Iep-4AsiKNnUHQxu0FaDHO_qa178GByKybdT_BuE8_dYk99G5Uvx_gdONXAOO2EaXidpVQ=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "57"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "ABi2fbt8vkzj7SJ8aD5jc4xJFTDFntdkMrYXL3itsvqY1QIw-dZozdop5rgKNxjbrQAd5nntAGpgh9w84O1Xgg=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "4.0"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "ABi2fbt8vkzj7SJ8aD5jc4xJFTDFntdkMrYXL3itsvqY1QIw-dZozdop5rgKNxjbrQAd5nntAGpgh9w84O1Xgg=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.cloudmosa.puffinFree",
      "browser_signature_hashes": [
        "1WqG8SoK2WvE4NTYgr2550TRhjhxT-7DWxu6C_o6GrOLK6xzG67Hq7GCGDjkAFRCOChlo2XUUglLRAYu3Mn8Ag=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.duckduckgo.mobile.android",
      "browser_signature_hashes": [
        "S5Av4cfEycCvIvKPpKGjyCuAE5gZ8y60-knFfGkAEIZWPr9lU5kA7iOAlSZxaJei08s0ruDvuEzFYlmH-jAi4Q=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.explore.web.browser",
      "browser_signature_hashes": [
        "BzDzBVSAwah8f_A0MYJCPOkt0eb7WcIEw6Udn7VLcizjoU3wxAzVisCm6bW7uTs4WpMfBEJYf0nDgzTYvYHCag=="
      ],
      "browser_use_customTab" : false
    },

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

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

    {
      "browser_package_name": "com.opera.browser",
      "browser_signature_hashes": [
        "FIJ3IIeqB7V0qHpRNEpYNkhEGA_eJaf7ntca-Oa_6Feev3UkgnpguTNV31JdAmpEFPGNPo0RHqdlU0k-3jWJWw=="
      ],
      "browser_use_customTab" : false
    },

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

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

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

基本配置示例Example basic configuration

以下示例演示了一个基本配置,该配置指定了客户端 ID、重定向 URI、是否注册了中介重定向,以及颁发机构列表。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" : "4b0db8c2-9f26-4417-8bde-3f0e3656f8e0",
  "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. 建议在 res/raw/auth_config.json 中创建自定义配置文件。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. 构造 PublicClientApplication 时,请告诉 MSAL 要在何处查找配置。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);