Android Microsoft 身份验证库配置文件
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 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 | 是 | 镜像应用面向的受众或帐户类型。 可能的值:AAD 、B2C |
audience |
Object | 否 | 仅当 type=AAD 时才适用。 指定应用面向的标识。 使用应用注册中的值 |
authority_url |
String | 是 | 仅当 type =B2C 时才是必需的。 对于 type=AAD 是可选项。 指定应用应该使用的颁发机构 URL 或策略 |
default |
boolean | 是 | 指定了一个或多个颁发机构时,需要指定单个 "default":true 。 |
受众属性
属性 | 数据类型 | 必须 | 注释 |
---|---|---|---|
type |
String | 是 | 指定应用要面向的受众。 可能的值:AzureADMultipleOrgs 、AzureADMyOrg |
tenant_id |
String | 是 | 仅当指定 "type":"AzureADMyOrg" 时才是必需的。 如果指定其他 type 值,则是可选的。 这可以是租户域(如 contoso.com ),也可以是租户 ID(如 00001111-aaaa-2222-bbbb-3333cccc4444 ) |
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 | 否 | 要输出的日志消息。 支持的日志级别包括 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": "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
}
]
}
如何使用配置文件
创建配置文件。 建议在
res/raw/auth_config.json
中创建自定义配置文件。 但可以将此文件放在所需的任意位置。构造
PublicClientApplication
时,请告诉 MSAL 要在何处查找配置。 例如://On Worker Thread IMultipleAccountPublicClientApplication sampleApp = null; sampleApp = new PublicClientApplication.createMultipleAccountPublicClientApplication(getApplicationContext(), R.raw.auth_config);