Android Microsoft 身份验证库配置文件

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

本文将帮助你了解该配置文件中的各项设置,以及如何指定要在基于 MSAL 的应用中使用的配置文件。

配置设置

常规设置

属性 数据类型 必须 注释
client_id String 应用程序注册页中的应用客户端 ID
redirect_uri String 应用程序注册页中的应用重定向 URI
broker_redirect_uri_registered 布尔 可能的值:truefalse
authorities List<Authority> 应用所需的颁发机构列表
authorization_user_agent AuthorizationAgent(枚举) 可能的值:WEBVIEWBROWSER
http HttpConfiguration 配置 HttpUrlConnection connect_timeoutread_timeout
logging LoggingConfiguration 指定日志记录的详细级别。 可选配置包括:采用布尔值的 pii_enabled,以及采用 ERRORWARNINGINFOVERBOSElog_level

client_id

注册应用程序时创建的客户端 ID 或应用 ID。

redirect_uri

注册应用程序时注册的重定向 URI。 如果重定向 URI 属于某个中介应用,请参阅公共客户端应用的重定向 URI,确保对中介应用使用正确的重定向 URI 格式。

broker_redirect_uri_registered

若要使用中介身份验证,则必须将 broker_redirect_uri_registered 属性设置为 true。 在中介身份验证方案中,如果应用程序的格式不正确,无法按照公共客户端应用的重定向 URI 中所述与代理进行对话,则该应用程序会验证重定向 URI 并在它启动时引发异常。

authorities

你已知且信任的颁发机构列表。 除了此处所列的颁发机构以外,MSAL 还会查询 Microsoft,以获取 Microsoft 已知的云和颁发机构列表。 在此颁发机构列表中,指定颁发机构的类型,并根据应用的注册指定与应用受众相符的任何其他可选参数(例如 "audience")。 下面是颁发机构列表的示例:

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

将 Microsoft Entra 颁发机构和受众映射到 Microsoft 标识平台终结点

类型 目标受众 租户 ID Authority_Url 生成的终结点 说明
Microsoft Entra ID AzureADMyOrg contoso.com https://login.partner.microsoftonline.cn/contoso.com 只有 contoso.com 中的帐户才能获取令牌。 任何已验证的域或租户 GUID 都可用作租户 ID。
Microsoft Entra ID AzureADMultipleOrgs https://login.partner.microsoftonline.cn/organizations 仅 Microsoft Entra 帐户可以用于此终结点。 Microsoft 帐户可以是组织的成员。 若要使用 Microsoft 帐户获取组织中资源的令牌,请指定要从中获取令牌的组织租户。
B2C 参阅“生成的终结点” https://login.partner.microsoftonline.cn/tfp/contoso.partner.onmschina.cn/B2C_1_SISOPolicy/ 只有 contoso.partner.onmschina.cn 租户中的帐户才能获取令牌。 在此示例中,B2C 策略是颁发机构 URL 路径的一部分。

注意

在 MSAL 中无法启用和禁用授权机构验证。 颁发机构是开发人员已知的、通过配置指定的颁发机构,或者是 Microsoft 已知的、通过元数据指定的颁发机构。 如果 MSAL 收到了向未知颁发机构获取令牌的请求,将导致 UnknownAuthority 类型的 MsalClientException。 对于 Azure AD B2C,中介身份验证不起作用。

颁发机构属性

属性 数据类型 必须 注释
type String 镜像应用面向的受众或帐户类型。 可能的值:AADB2C
audience Object 仅当 type=AAD 时才适用。 指定应用面向的标识。 使用应用注册中的值
authority_url String 仅当 type =B2C 时才是必需的。 对于 type=AAD 是可选项。 指定应用应该使用的颁发机构 URL 或策略
default boolean 指定了一个或多个颁发机构时,需要指定单个 "default":true

受众属性

属性 数据类型 必须 注释
type String 指定应用要面向的受众。 可能的值:AzureADMultipleOrgsAzureADMyOrg
tenant_id String 仅当指定 "type":"AzureADMyOrg" 时才是必需的。 如果指定其他 type 值,则是可选的。 这可以是租户域(如 contoso.com),也可以是租户 ID(如 aaaabbbb-0000-cccc-1111-dddd2222eeee

authorization_user_agent

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

可能的值:

  • WEBVIEW:使用嵌入式 Web 视图。
  • BROWSER:使用设备上的默认浏览器。

multiple_clouds_supported

对于支持多个国家云的客户端,请指定 true。 然后,在授权和令牌兑换期间,Microsoft 标识平台会自动重定向到正确的国家云。 可以通过检查与 AuthenticationResult 关联的颁发机构来确定登录帐户的国家云。 请注意,AuthenticationResult 不提供要请求其令牌的资源的国家云特定的终结点地址。

broker_redirect_uri_registered

一个布尔值,指示是否正在使用 Microsoft 标识中介兼容的中介内重定向 URI。 如果不想要在应用中使用中介,请设置为 false

http

配置全局 HTTP 超时设置,例如:

属性 数据类型 必须 注释
connect_timeout int 时间(毫秒)
read_timeout int 时间(毫秒)

logging

以下全局设置用于日志记录:

属性 数据类型 必须 注释
pii_enabled boolean 是否发出个人数据
log_level string 要输出的日志消息。 支持的日志级别包括 ERRORWARNINGINFOVERBOSE
logcat_enabled boolean 除了输出到日志记录界面以外,是否还要输出到 logcat

account_mode

指定在应用中一次可以使用多少个帐户。 可能的值包括:

  • MULTIPLE(默认值)
  • SINGLE

使用与此设置不匹配的帐户模式构造 PublicClientApplication 会导致异常。

有关单个帐户与多个帐户之间的差异的详细信息,请参阅单帐户和多帐户应用

browser_safelist

与 MSAL 兼容的浏览器的允许列表。 这些浏览器可根据自定义意图正确处理重定向。 可在此列表中添加内容。 默认值在默认配置中提供,如下所示。 ``

默认的 MSAL 配置文件

下面显示了 MSAL 随附的默认 MSAL 配置。 可以在 GitHub 上查看最新版本。

此配置由提供的值补充。 提供的值将替代默认值。

{
  "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
    }
  ]
}

基本配置示例

以下示例演示了一个基本配置,该配置指定了客户端 ID、重定向 URI、是否注册了中介重定向,以及颁发机构列表。

{
  "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
    }
  ]
}

如何使用配置文件

  1. 创建配置文件。 建议在 res/raw/auth_config.json 中创建自定义配置文件。 但可以将此文件放在所需的任意位置。

  2. 构造 PublicClientApplication 时,请告诉 MSAL 要在何处查找配置。 例如:

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