使用 Azure AD B2C 在 WPF 桌面应用中启用验证选项

项目
10/14/2024

本文介绍如何自定义和增强 Windows Presentation Foundation (WPF) 桌面应用程序的 Azure Active Directory B2C (Azure AD B2C) 身份验证体验。

在开始之前，请先熟悉使用 Azure AD B2C 在示例 WPF 桌面应用中配置身份验证一文。

在登录用户旅程中，你的应用可能会针对特定用户。当应用针对用户时，它可以在授权请求中使用用户登录名指定 login_hint 查询参数。 Azure AD B2C 自动填充登录名，用户只需要提供密码。

若要预填充登录名，请执行下列操作：

如果使用的是自定义策略，请按照设置直接登录中的说明添加所需的输入声明。
查找 Microsoft 身份验证库 (MSAL) 配置对象，然后添加带有登录提示的 withLoginHint() 方法。

authResult = await app.AcquireTokenInteractive(App.ApiScopes)
    .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
    .WithLoginHint("bob@contoso.com")
    .ExecuteAsync();

预先选择标识提供程序

如果已将应用程序的登录旅程配置为包括社交帐户，则可以指定 domain_hint 参数。此查询参数向 Azure AD B2C 提供有关应该用于登录的社交标识提供者的提示。

要将用户重定向到外部标识提供程序，请执行以下操作：

检查外部标识提供者的域名。有关详细信息，请参阅将登录重定向到社交服务提供商。
创建或使用现有的 Dictionary 对象来存储额外的查询参数。
将具有相应域名的 domain_hint 参数添加到字典中（如 qq.com）。
将额外的查询参数对象传递到 MSAL 配置对象的 WithExtraQueryParameters 方法中。

Dictionary<string, string> extraQueryParameters = new Dictionary<string, string>();
extraQueryParameters.Add("domain_hint", "qq.com");

authResult = await app.AcquireTokenInteractive(App.ApiScopes)
    .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
    .WithExtraQueryParameters(extraQueryParameters)
    .ExecuteAsync();

指定 UI 语言

可使用 Azure AD B2C 中的语言自定义让用户流适应各种不同的语言，从而满足客户需求。有关详细信息，请参阅语言自定义。

要设置首选语言，请执行下列操作：

配置语言自定义。
创建或使用现有的 Dictionary 对象来存储额外的查询参数。
将具有相应语言代码的 ui_locales 参数添加到字典中（如 en-us）。
将额外的查询参数对象传递到 MSAL 配置对象的 WithExtraQueryParameters 方法中。

Dictionary<string, string> extraQueryParameters = new Dictionary<string, string>();
extraQueryParameters.Add("ui_locales", "en-us");

authResult = await app.AcquireTokenInteractive(App.ApiScopes)
    .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
    .WithExtraQueryParameters(extraQueryParameters)
    .ExecuteAsync();

传递自定义查询字符串参数

借助自定义策略，可以传递自定义查询字符串参数。例如，当你需要动态更改页面内容时。

若要传递自定义查询字符串参数，请执行以下操作：

配置 ContentDefinitionParameters 元素。
创建或使用现有的 Dictionary 对象来存储额外的查询参数。
添加自定义查询字符串参数（如 campaignId）。设置参数值（如 germany-promotion）。
将额外的查询参数对象传递到 MSAL 配置对象的 WithExtraQueryParameters 方法中。

Dictionary<string, string> extraQueryParameters = new Dictionary<string, string>();
extraQueryParameters.Add("campaignId", "germany-promotion");

authResult = await app.AcquireTokenInteractive(App.ApiScopes)
    .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
    .WithExtraQueryParameters(extraQueryParameters)
    .ExecuteAsync();

传递 ID 令牌提示

信赖方应用可随附 OAuth2 授权请求发送入站 JSON Web 令牌 (JWT)。入站令牌是有关用户或授权请求的提示。 Azure AD B2C 会验证令牌，然后提取声明。

要在身份验证请求中包含 ID 令牌提示，请执行以下操作：

在自定义策略中，定义 ID 令牌提示技术配置文件。
在代码中，生成或获取 ID 令牌，然后将令牌设置为变量（如 idToken）。
创建或使用现有的 Dictionary 对象来存储额外的查询参数。
使用可存储 ID 令牌的相应变量添加 id_token_hint 参数。
将额外的查询参数对象传递到 MSAL 配置对象的 extraQueryParameters 属性中。

Dictionary<string, string> extraQueryParameters = new Dictionary<string, string>();
extraQueryParameters.Add("id_token_hint", idToken);

authResult = await app.AcquireTokenInteractive(App.ApiScopes)
    .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
    .WithExtraQueryParameters(extraQueryParameters)
    .ExecuteAsync();

配置日志记录

MSAL 库生成可帮助诊断问题的日志消息。应用可配置日志记录。应用还可以让你对详细程度以及是否记录个人和组织数据进行自定义控制。

建议创建 MSAL 日志记录回叫，并提供一种方式来让用户在遇到身份验证问题时提交日志。 MSAL 提供以下级别的日志记录详细信息：

错误：出现问题并已生成错误。此级别用于调试并确定问题。
警告：不一定会出现错误或故障，但该信息用于诊断和找到问题。
信息：MSAL 记录用于参考但不一定用于调试的事件。
详细：这是默认级别。 MSAL 将记录库行为的完整详细信息。

默认情况下，MSAL 记录器不捕获任何个人或组织数据。该库提供相关选项，允许你自行决定是否记录个人和组织数据。

下面的代码片段演示如何配置 MSAL 日志记录：

PublicClientApp = PublicClientApplicationBuilder.Create(ClientId)
    .WithB2CAuthority(AuthoritySignUpSignIn)
    .WithRedirectUri(RedirectUri)
    .WithLogging(Log, LogLevel.Info, false) // don't log P(ersonally) I(dentifiable) I(nformation) details on a regular basis
    .Build();

配置重定向 URI

在桌面应用注册过程中，在选择重定向 URI 时，请记住以下重要注意事项：

开发：对于桌面应用中的开发用途，可将重定向 URI 设置为 http://localhost，Azure AD B2C 将遵循请求中的任何端口。如果注册的 URI 包含端口，Azure AD B2C 将仅使用该端口。例如，如果注册的重定向 URI 为 http://localhost，则请求中的重定向 URI 可为 http://localhost:<randomport>。如果注册的重定向 URI 为 http://localhost:8080，则请求中的重定向 URI 必须为 http://localhost:8080。
唯一：每个应用程序的重定向 URI 的方案必须是唯一的。在示例 com.onmicrosoft.contosob2c.exampleapp://oauth/redirect 中，com.onmicrosoft.contosob2c.exampleapp 为方案。应遵循此模式。如果两个应用程序共享同一方案，则用户可选择应用程序。如果用户选择错误，登录会失败。
完整：重定向 URI 必须同时包含方案和路径。路径必须在域之后包含至少一个斜杠字符。例如，//oauth/ 有效，而 //oauth 会失败。请勿在 URI 中包含特殊字符。例如，不允许包含下划线字符 (_)。

后续步骤

若要了解详细信息，请参阅适用于 .NET、UWP、NetCore 和 Xamarin 的 MSAL 配置选项。

通过