Android Microsoft 身份验证库配置文件

项目
04/10/2024

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

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

配置设置

常规设置

属性	数据类型	必须	注释
`client_id`	String	是	应用程序注册页中的应用客户端 ID
`redirect_uri`	String	是	应用程序注册页中的应用重定向 URI
`broker_redirect_uri_registered`	布尔	否	可能的值：`true`、`false`
`authorities`	List<Authority>	否	应用所需的颁发机构列表
`authorization_user_agent`	AuthorizationAgent（枚举）	否	可能的值：`WEBVIEW`、`BROWSER`
`http`	HttpConfiguration	否	配置 `HttpUrlConnection` `connect_timeout` 和 `read_timeout`
`logging`	LoggingConfiguration	否	指定日志记录的详细级别。可选配置包括：采用布尔值的 `pii_enabled`，以及采用 `ERROR`、`WARNING`、`INFO` 或 `VERBOSE` 的 `log_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 and Personal Microsoft Account
{
    "type": "AAD",
    "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
    },
    "default": true // Indicates that this is the default to use if not provided as part of the acquireToken call
},
// 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"
    }
},
//Example PersonalMicrosoftAccount
{
    "type": "AAD",
    "audience": {
        "type": "PersonalMicrosoftAccount"
    }
}

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

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

注意

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

颁发机构属性

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

受众属性

属性	数据类型	必须	注释
`type`	String	是	指定应用要面向的受众。可能的值：`AzureADandPersonalMicrosoftAccount`、`PersonalMicrosoftAccount`、`AzureADMultipleOrgs`、`AzureADMyOrg`
`tenant_id`	字符串	是	仅当指定 `"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。

如果使用的是将受众设置为 "MicrosoftPersonalAccount" 的 Microsoft Entra 颁发机构，则不会使用代理。

http

配置全局 HTTP 超时设置，例如：

属性	数据类型	必须	注释
`connect_timeout`	int	否	时间（毫秒）
`read_timeout`	int	否	时间（毫秒）

logging

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

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

account_mode

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

MULTIPLE（默认值）
SINGLE

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

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

browser_safelist

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

默认的 MSAL 配置文件

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

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

{
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      },
      "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": "AzureADandPersonalMicrosoftAccount"
      }
      "default": true
    }
  ]
}

如何使用配置文件

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

构造 PublicClientApplication 时，请告诉 MSAL 要在何处查找配置。例如：

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

通过

Android Microsoft 身份验证库配置文件

配置设置

常规设置

client_id

redirect_uri

broker_redirect_uri_registered

authorities

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

颁发机构属性

受众属性

authorization_user_agent

multiple_clouds_supported

broker_redirect_uri_registered

http

logging

account_mode

browser_safelist

默认的 MSAL 配置文件

基本配置示例

如何使用配置文件

反馈

其他资源