应用程序配置选项

若要进行身份验证并获取令牌,请在代码中初始化新的公共或机密客户端应用程序。 在 Microsoft 身份验证库 (MSAL) 中初始化客户端应用时,可以设置多个配置选项。 这些选项划分为两组:

颁发机构

颁发机构是一个 URL,表示 MSAL 可从中请求令牌的目录。

常见的颁发机构包括:

常见的颁发机构 URL 何时使用
https://login.partner.microsoftonline.cn/<tenant>/ 仅允许特定组织的用户登录。 URL 中的 <tenant> 是 Microsoft Entra 租户 (GUID) 或其租户域的租户 ID。
https://login.partner.microsoftonline.cn/common/ 通过工作和学校帐户登录用户。
https://login.partner.microsoftonline.cn/organizations/ 通过工作和学校帐户登录用户。

在代码中指定的机构需要与在 Azure 门户中为“应用注册”中的应用指定的支持帐户类型一致 。

颁发机构可以是:

  • Microsoft Entra 云颁发机构。
  • Azure AD B2C 颁发机构。 请参阅 B2C 细节
  • Active Directory 联合身份验证服务 (AD FS) 颁发机构。 请参阅 AD FS support(AD FS 支持)。

Microsoft Entra 云颁发机构有两个部分:

  • 标识提供者实例
  • 应用的登录受众

可将实例和受众连接到一起,以颁发机构 URL 的形式提供。 下图显示了颁发机构 URL 的构成方式:

如何构成颁发机构 URL

云实例

实例用于指定应用是要从 Azure 公有云还是国家/地区云将用户登录。 在代码中使用 MSAL,可以通过使用枚举或将 URL 作为 Instance 成员传递给国家/地区云实例来设置 Azure 云实例。

如果同时指定 InstanceAzureCloudInstance,MSAL.NET 将引发显式异常。

如果未指定实例,应用将面向 Azure 公有云实例。

应用程序受众

登录受众取决于应用的业务需求:

  • 业务线应用程序 (LOB) 开发人员也许会生成一个只在其组织中使用的单租户应用程序。 在这种情况下,请按租户 ID(Microsoft Entra 实例的 ID)或者与 Microsoft Entra 实例关联的域名指定组织。
  • ISV 可能想要使用任一组织或某些组织(多租户应用)中的用户工作帐户和学校帐户将用户登录。

如何在代码/配置中指定受众

在代码中使用 MSAL 时,可以使用以下值之一指定受众:

  • Microsoft Entra 颁发机构受众枚举
  • 租户 ID,可以是:
    • 单租户应用程序的 GUID(Microsoft Entra 实例的 ID)
    • 与 Microsoft Entra 实例关联的域名(也适用于单租户应用程序)
  • 以下租户 ID 占位符之一代表 Microsoft Entra 颁发机构受众枚举:
    • 多租户应用程序的 organizations
    • 用于通过工作和学校帐户将用户登录的 common 如果同时指定 Microsoft Entra 颁发机构受众和租户 ID,MSAL 将引发重要异常。

建议指定受众,即租户数量,并且部署在其中的应用将具有来宾用户。 如果应用将具有外部用户,则最好避免使用 commonorganization 的终结点。 如果你没有指定受众,你的应用将以 Microsoft Entra 作为受众,并且会表现得像指定了 common 一样。

有效的受众

应用程序的有效受众是在应用中设置的受众与在应用注册中指定的受众之间的最小值(如果存在交集)。 实际上,可以在应用注册体验中指定应用的受众(支持的帐户类型)。 有关详细信息,请参阅快速入门:将应用程序注册到 Microsoft 标识平台

客户端 ID

客户端 ID 是注册应用时由 Microsoft Entra ID 分配给应用的唯一应用程序(客户端)ID。 可在“标识”>“应用程序”>“企业应用程序”的“概述”页上找到应用程序(客户端)ID。

重定向 URI

重定向 URI 是标识提供者将安全令牌发回到的 URI。

公共客户端应用的重定向 URI

如果你是使用 MSAL 的公共客户端应用开发人员:

  • 将需要在桌面或通用 Windows 平台 (UWP) 应用程序 (MSAL.NET 4.1+) 中使用 .WithDefaultRedirectUri().WithDefaultRedirectUri() 方法会将公共客户端应用程序的重定向 URI 属性设置为建议用于公共客户端应用程序的默认重定向 URI。

    平台 重定向 URI
    桌面应用 (.NET Framework) https://login.partner.microsoftonline.cn/common/oauth2/nativeclient
    UWP WebAuthenticationBroker.GetCurrentApplicationCallbackUri() 的值。 这可以通过浏览器启用单一登录 (SSO),方法是:将值设置为需注册的 WebAuthenticationBroker.GetCurrentApplicationCallbackUri() 的结果
    .NET 通过 https://localhost,用户能够使用系统浏览器进行交互式身份验证,因为 .NET 目前还没有适用于嵌入式 Web 视图的 UI。

可以使用 RedirectUri 属性替代重定向 URI(例如,如果使用代理)。 下面是该方案的重定向 URI 的一些示例:

  • RedirectUriOnAndroid = "msauth-5a434691-ccb2-4fd1-b97b-b64bcfbc03fc://com.microsoft.identity.client.sample";

  • RedirectUriOnIos = $"msauth.{Bundle.ID}://auth";

  • 使用 MSAL Android 生成应用时,可以在初始应用注册步骤中配置 redirect_uri,也可以在之后添加它。

    • 重定向 URI 的格式为:msauth://<yourpackagename>/<base64urlencodedsignature>
    • 示例: redirect_uri = msauth://com.azuresamples.myapp/6/aB1cD2eF3gH4iJ5kL6-mN7oP8qR=
  • 若要查找有关 MSAL Android 应用配置的更多详细信息,请参阅 MSAL Android 配置

  • 请在应用注册中配置重定向 URI:

    显示“应用注册”页上的“重定向 URI”窗格和选项的屏幕截图。

机密客户端应用的重定向 URI

对于 Web 应用,重定向 URI(或回复 URL)是 Microsoft Entra ID 用来向应用程序发回令牌的 URI。 如果机密应用是 Web 应用/Web API 中之一,则 URI 可以是其 URL。 重定向 URI 需在应用注册中注册。 部署一个已经在本地测试过的应用程序时,注册尤为重要。 然后,需要在应用程序注册门户中添加已部署应用的回复 URL。

对于守护程序应用,不需要指定重定向 URI。

客户端机密

此选项指定机密客户端应用的客户端机密。 在使用 PowerShell Microsoft Entra ID、PowerShell AzureRM 或 Azure CLI 注册应用期间,此客户端机密(应用密码)由应用程序注册门户提供或提供给 Microsoft Entra ID。

日志记录

为在调试和身份验证失败故障排除场景提供帮助,MSAL 提供了内置的日志记录支持。 以下文章介绍了每个库中的日志记录:

后续步骤

了解如何使用 MSAL.NET 初始化客户端应用程序使用 MSAL.js 初始化客户端应用程序