使用 MSAL.NET 初始化客户端应用程序

本文介绍如何使用适用于 .NET 的 Microsoft 身份验证库 (MSAL.NET) 初始化公共客户端和机密客户端应用程序。 若要详细了解客户端应用程序类型,请参阅公共客户端和机密客户端应用程序

使用 MSAL.NET 3.x 实例化应用程序的建议方式是使用应用程序生成器 PublicClientApplicationBuilderConfidentialClientApplicationBuilder。 这些生成器提供强大的机制用于通过代码、配置文件甚至两者的混合来配置应用程序。

API 参考文档 | NuGet 上的包 | 库源代码 | 代码示例

先决条件

在初始化应用程序之前,首先需要将其注册,使应用能够与 Microsoft 标识平台集成。 注册后,可能需要以下信息(可在 Azure 门户中找到):

  • 客户端 ID(表示 GUID 的字符串)
  • 标识提供者 URL(为实例命名)和应用程序的登录受众。 这两个参数统称为颁发机构。
  • 如果你仅在为组织编写业务线应用程序(也称为单租户应用程序),则为租户 ID。
  • 应用程序机密(客户端机密字符串);对于机密客户端应用,需要获取证书(类型为 X509Certificate2)。
  • 对于 Web 应用或者公共客户端应用(特别是当你的应用需要使用中转站时),还将需要设置 redirectUri,标识提供者将在其中使用安全令牌联系你的应用程序。

初始化应用程序的方式

可通过多种不同的方式来实例化客户端应用程序。

通过代码初始化公共客户端应用程序

以下代码实例化一个公共客户端应用程序,使用工作和学校帐户在 Azure 云中将用户登录。

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

通过代码初始化机密客户端应用程序

以下代码以相同的方式实例化一个机密应用程序(位于 https://myapp.chinacloudsites.cn 上的 Web 应用),该应用程序可以使用工作和学校帐户处理 Azure 云中用户的令牌。 标识提供者通过共享客户端机密标识该应用程序:

string redirectUri = "https://myapp.chinacloudsites.cn";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

你可能已知道,在生产环境中,最好是与 Azure AD 共享证书,而不要使用客户端机密。 根据此要求,代码如下所示:

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certificate)
    .WithRedirectUri(redirectUri )
    .Build();

通过配置选项初始化公共客户端应用程序

以下代码通过一个配置对象实例化公共客户端应用程序,该对象可以通过编程方式进行填充,也可以从配置文件读取:

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
    .Build();

通过配置选项初始化机密客户端应用程序

可对机密客户端应用程序应用上述相同的模式。 还可以使用 .WithXXX 修饰符(此处为证书)添加其他参数。

ConfidentialClientApplicationOptions options = GetOptions(); // your own method
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(options)
    .WithCertificate(certificate)
    .Build();

生成器修饰符

在使用应用程序生成器的代码片段中,可将许多 .With 方法应用为修饰符(例如 .WithCertificate.WithRedirectUri)。

公共和机密客户端应用程序通用的修饰符

可在公共客户端或机密客户端应用程序生成器中设置的修饰符包括:

修饰符 说明
.WithAuthority() 7 个重写 将应用程序默认颁发机构设置为 Azure AD 颁发机构,有时还可以选择 Azure 云、受众、租户(租户 ID 或域名),或直接提供颁发机构 URI。
.WithAdfsAuthority(string) 将应用程序默认颁发机构设置为 ADFS 颁发机构。
.WithB2CAuthority(string) 将应用程序默认颁发机构设置为 Azure AD B2C 颁发机构。
.WithClientId(string) 重写客户端 ID。
.WithComponent(string) 使用 MSAL.NET 设置库的名称(出于遥测原因)。
.WithDebugLoggingCallback() 调用后,应用程序将调用 Debug.Write,目的只是启用调试跟踪。 有关详细信息,请参阅日志记录
.WithExtraQueryParameters(IDictionary<string,string> eqp) 设置要在所有身份验证请求中发送的应用程序级附加查询参数。 可在每个令牌获取方法级别重写此值(具有相同的 .WithExtraQueryParameters pattern)。
.WithHttpClientFactory(IMsalHttpClientFactory httpClientFactory) 启用高级方案(例如对 HTTP 代理进行配置),或者强制 MSAL 使用特定的 HttpClient(例如,在 ASP.NET Core Web 应用/API 中)。
.WithLogging() 调用后,应用程序将结合调试跟踪调用某个回调。 有关详细信息,请参阅日志记录
.WithRedirectUri(string redirectUri) 重写默认的重定向 URI。 此操作对于公共客户端应用程序中涉及代理的方案非常有用。
.WithTelemetry(TelemetryCallback telemetryCallback) 设置用于发送遥测数据的委托。
.WithTenantId(string tenantId) 重写租户 ID 或租户说明。

特定于 Xamarin.iOS 应用程序的修饰符

可在 Xamarin.iOS 上的公共客户端应用程序生成器中设置的修饰符包括:

修饰符 说明
.WithIosKeychainSecurityGroup() 仅限 Xamarin.iOS:设置 iOS 密钥链安全组(为实现缓存持久性)。

特定于机密客户端应用程序的修饰符

可在机密客户端应用程序生成器中设置的修饰符包括:

修饰符 说明
.WithCertificate(X509Certificate2 certificate) 设置用于在 Azure AD 中识别应用程序的证书。
.WithClientSecret(string clientSecret) 设置用于在 Azure AD 中识别应用程序的客户端机密(应用密码)。

这些修饰符是互斥的。 如果同时提供两者,MSAL 会引发有含义的异常。

修饰符用法示例

假设你的应用程序是一个仅供你的组织使用的业务线应用程序。 那么,可编写以下代码:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzureChina, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

ADFS 也有一个重写(目前不支持 ADFS 2019):

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

最后,如果你是 Azure AD B2C 开发人员,可按如下所示指定租户:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.cn/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

后续步骤

初始化客户端应用程序后,下一项任务是添加对用户登录和/或已授权 API 访问的支持。

我们的应用程序方案文档提供了有关将用户登录和获取访问令牌以代表用户访问 API 的指南: