若要进行身份验证并获取令牌,请在代码中初始化新的公共或机密客户端应用程序。 在 Microsoft 身份验证库 (MSAL) 中初始化客户端应用时,可以设置多个配置选项。 这些选项划分为两组:
- 注册选项,包括:
- 日志记录选项,包括日志级别、个人数据的控制以及使用库的组件名称
颁发机构
颁发机构是一个 URL,表示 MSAL 可从中请求令牌的目录。
常见的颁发机构包括:
常见的颁发机构 URL | 何时使用 |
---|---|
https://login.microsoftonline.com/<tenant>/ |
仅允许特定组织的用户登录。 URL 中的 <tenant> 是 Microsoft Entra 租户 (GUID) 或其租户域的租户 ID。 |
https://login.microsoftonline.com/common/ |
通过工作和学校帐户或个人 Microsoft 帐户登录用户。 |
https://login.microsoftonline.com/organizations/ |
通过工作和学校帐户登录用户。 |
https://login.microsoftonline.com/consumers/ |
仅通过个人 Microsoft 帐户 (MSA) 登录用户。 |
在代码中指定的机构需要与在 Azure 门户中为应用注册中的应用指定的支持帐户类型一致 。
颁发机构可以是:
- Microsoft Entra 云颁发机构。
- Azure AD B2C 颁发机构。 请参阅 B2C 细节。
- Active Directory 联合身份验证服务 (AD FS) 颁发机构。 请参阅 AD FS support(AD FS 支持)。
Microsoft Entra 云颁发机构有两个部分:
- 标识提供者实例
- 应用的登录受众
可将实例和受众连接到一起,以颁发机构 URL 的形式提供。 下图显示了颁发机构 URL 的构成方式:
云实例
实例用于指定应用是要从 Azure 公有云还是国家/地区云将用户登录。 在代码中使用 MSAL,可以通过使用枚举或将 URL 作为 Instance
成员传递给国家/地区云实例来设置 Azure 云实例。
MSAL.NET 如果同时指定 Instance
和 AzureCloudInstance
时,会引发显式异常。
如果未指定实例,应用将面向 Azure 公有云实例(URL https://login.onmicrosoftonline.com
的实例)。
应用程序受众
登录受众取决于应用的业务需求:
- 如果您是业务线(LOB)开发人员,您可能会开发一个仅供您所在组织内部使用的单租户应用程序。 在这种情况下,请按租户 ID(Microsoft Entra 实例的 ID)或者与 Microsoft Entra 实例关联的域名指定组织。
- ISV 可能想要使用任一组织或某些组织(多租户应用)中的用户工作帐户和学校帐户将用户登录。 但你也可能想让用户使用其个人 Microsoft 帐户登录。
如何在代码/配置中指定受众
在代码中使用 MSAL 时,可以使用以下值之一指定受众:
- Microsoft Entra 颁发机构受众枚举
- 租户 ID,可以是:
- 单租户应用程序的 GUID(Microsoft Entra 实例的 ID)
- 与 Microsoft Entra 实例关联的域名(也适用于单租户应用程序)
- 以下租户 ID 占位符之一代表 Microsoft Entra 颁发机构受众枚举:
- 多租户应用程序的
organizations
- 仅通过其个人帐户登录用户的
consumers
- 通过工作和学校帐户或其个人 Microsoft 帐户登录用户的
common
- 多租户应用程序的
如果你同时指定 Microsoft Entra 颁发机构受众和租户 ID,MSAL 将引发有含义的异常。
建议指定一个用户群体,因为部署在这些租户中的许多应用程序将包括来宾用户。 如果应用程序适用于外部用户,请避免 common
和 organization
终结点。 如果没有指定受众,应用将以 Microsoft Entra ID 和个人 Microsoft 帐户为受众,并且会表现得像指定了 common
一样。
有效的受众
应用程序的有效受众是在应用中设置的受众与在应用注册中指定的受众之间的最小值(如果存在交集)。 事实上, 应用注册 体验允许你为应用指定受众(支持的帐户类型)。 有关详细信息,请参阅 快速入门:将应用程序注册到Microsoft标识平台。
目前,让应用仅使用个人 Microsoft 帐户登录用户的唯一方法是配置这两个设置:
- 将应用注册受众设置为
Work and school accounts and personal accounts
。 - 将你的代码/配置中的受众设置为
AadAuthorityAudience.PersonalMicrosoftAccount
(或TenantID
= "consumers")。
客户端 ID
客户端 ID 是注册应用时由 Microsoft Entra ID 分配给应用的唯一应用程序(客户端)ID。 可以在 Entra ID>应用程序的“概述”页上找到应用程序(客户端)ID。
重定向 URI
重定向 URI 是标识提供者将安全令牌发送回的 URI。
公共客户端应用的重定向 URI
如果你是使用 MSAL 的公共客户端应用开发人员:
你想要在桌面应用程序中使用
.WithDefaultRedirectUri()
(MSAL.NET 4.1+)。 该方法.WithDefaultRedirectUri()
将公共客户端应用程序的重定向 URI 属性设置为公共客户端应用程序的默认推荐重定向 URI。平台 重定向 URI 桌面应用 (.NET Framework) https://login.microsoftonline.com/common/oauth2/nativeclient
UWP WebAuthenticationBroker.GetCurrentApplicationCallbackUri()
的值。 这可以通过浏览器启用单一登录 (SSO),方法是:将值设置为需注册的 WebAuthenticationBroker.GetCurrentApplicationCallbackUri() 的结果.NET 通过 https://localhost
,用户能够使用系统浏览器进行交互式身份验证,因为 .NET 目前还没有适用于嵌入式 Web 视图的 UI。
可以使用 RedirectUri
属性替代重定向 URI(例如,如果使用代理)。 下面是该方案的重定向 URI 的一些示例:
RedirectUriOnAndroid
="msauth-00001111-aaaa-2222-bbbb-3333cccc4444://com.microsoft.identity.client.sample";
RedirectUriOnIos
=$"msauth.{Bundle.ID}://auth";
有关更多 Android 详细信息,请参阅 Android 中的中转身份验证。
使用 MSAL Android 生成应用时,可以在初始应用注册步骤中配置
redirect_uri
,也可以在之后添加它。- 重定向 URI 的格式为:
msauth://<yourpackagename>/<base64urlencodedsignature>
- 示例:
redirect_uri
=msauth://com.azuresamples.myapp/6/aB1cD2eF3gH4iJ5kL6-mN7oP8qR=
- 重定向 URI 的格式为:
若要查找有关 MSAL Android 应用配置的更多详细信息,请参阅 MSAL Android 配置。
在 应用注册中配置重定向 URI:
机密客户端应用的重定向 URI
对于 Web 应用,重定向 URI(或回复 URL)是 Microsoft Entra ID 用来向应用程序发回令牌的 URI。 如果机密应用是 Web 应用/Web API 中之一,则 URI 可以是其 URL。 重定向 URI 需在应用注册中注册。 部署一个已经在本地测试过的应用程序时,注册尤为重要。 然后,需要在应用程序注册门户中添加已部署应用的回复 URL。
对于守护程序应用,不需要指定重定向 URI。
应用程序凭据
对于机密客户端应用程序,有效管理凭据至关重要。 凭据可以是联合凭据(建议)、证书或客户端密码。
联合标识凭据
联合标识凭据是一种凭据类型,此类凭据支持工作负载(例如 GitHub Actions、Kubernetes 上运行的工作负载,或在 Azure 外部的计算平台中运行的工作负载)访问受 Microsoft Entra 保护的资源,而无需使用工作负载标识联合身份验证管理机密。
证书
此选项指定机密客户端应用的证书。 证书有时称为公钥,是建议的凭据类型,因为我们认为证书比客户端机密更安全。
客户端密码
此选项指定机密客户端应用的客户端机密。 在使用 PowerShell Microsoft Entra ID、PowerShell AzureRM 或 Azure CLI 注册应用期间,此客户端机密(应用密码)由应用程序注册门户提供或提供给 Microsoft Entra ID。
日志记录
为在调试和身份验证失败故障排除场景提供帮助,MSAL 提供了内置的日志记录支持。 以下文章介绍了每个库中的日志记录: