使用 Azure AD B2C 在 Web 应用中启用身份验证选项

2025-05-09

重要

自 2025 年 5 月 1 日起，Azure AD B2C 将不再可供新客户购买。在我们的常见问题解答中了解详细信息。

本文介绍如何为 Web 应用程序启用、自定义和增强 Azure Active Directory B2C （Azure AD B2C）身份验证体验。

在开始之前，请务必熟悉以下文章：

使用自定义域

通过使用自定义域，可以完全打造身份验证 URL 的品牌。从用户的角度来看，用户在身份验证过程中停留在您的域名上，而不是被重定向到 Azure AD B2C 的 b2clogin.com 域名。

若要删除 URL 中提到“b2c”的所有内容，还可以将身份验证请求 URL 中的 B2C 租户名称 contoso.onmicrosoft.com 替换成租户 ID GUID。例如，可以更改为 https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/https://account.contosobank.co.uk/<tenant ID GUID>/.

若要在身份验证 URL 中使用自定义域和租户 ID，请按照 “启用自定义域”中的指南进行作。在项目根文件夹下，打开 appsettings.json 文件。此文件包含有关 Azure AD B2C 标识提供者的信息。

在 appsettings.json 文件中，执行以下作：

使用 Instance 自定义域更新条目。
Domain使用租户 ID 更新条目。有关详细信息，请参阅 “使用租户 ID”。

以下 JSON 显示更改前的应用设置：

"AzureAdB2C": {
  "Instance": "https://contoso.b2clogin.com",
  "Domain": "tenant-name.onmicrosoft.com",
  ...
}

以下 JSON 显示更改后的应用设置：

"AzureAdB2C": {
  "Instance": "https://login.contoso.com",
  "Domain": "00000000-0000-0000-0000-000000000000",
  ...
}

支持高级方案

Microsoft AddMicrosoftIdentityWebAppAuthentication 标识平台 API 中的方法允许开发人员为高级身份验证方案添加代码或订阅 OpenIdConnect 事件。例如，可以订阅 OnRedirectToIdentityProvider，以便自定义应用发送到 Azure AD B2C 的身份验证请求。

若要支持高级方案，请打开 Startup.cs 文件，并在函数中 ConfigureServices 替换为 AddMicrosoftIdentityWebAppAuthentication 以下代码片段：

// Configuration to sign-in users with Azure AD B2C

//services.AddMicrosoftIdentityWebAppAuthentication(Configuration, "AzureAdB2C");

services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
        .AddMicrosoftIdentityWebApp(options =>
{
    Configuration.Bind("AzureAdB2C", options);
    options.Events ??= new OpenIdConnectEvents();
    options.Events.OnRedirectToIdentityProvider += OnRedirectToIdentityProviderFunc;
});

前面的代码使用对方法的引用 OnRedirectToIdentityProviderFunc 添加 OnRedirectToIdentityProvider 事件。将以下代码片段添加到 Startup.cs 类。

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
    // Custom code here
    
    // Don't remove this line
    await Task.CompletedTask.ConfigureAwait(false);
}

可以使用上下文参数在控制器和 OnRedirectToIdentityProvider 函数之间传递参数。

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

若要预填充登录名称，请执行以下作：

如果使用自定义策略，请添加所需的输入声明，如设置直接登录中所述。
完成支持高级方案过程。

将以下代码行添加到 OnRedirectToIdentityProvider 函数：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  context.ProtocolMessage.LoginHint = "emily@contoso.com";

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

预先选择标识提供者

如果将应用程序的登录旅程配置为包含社交帐户（如 Facebook、LinkedIn 或 Google），则可以指定 domain_hint 参数。此查询参数向 Azure AD B2C 提供有关应该用于登录的社交标识提供者的提示。例如，如果应用程序指定 domain_hint=facebook.com，登录流将直接转到 Facebook 登录页。

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

检查外部标识提供者的域名。有关详细信息，请参阅将登录重定向到社交服务提供商。
完成支持高级方案过程。

在 OnRedirectToIdentityProviderFunc 函数中，将以下代码行添加到 OnRedirectToIdentityProvider 函数：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  context.ProtocolMessage.DomainHint = "facebook.com";

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

指定 UI 语言

Azure AD B2C 中的语言自定义使用户流能够适应各种语言以满足客户的需求。有关详细信息，请参阅语言自定义。

若要设置首选语言，请执行以下作：

配置语言自定义。
完成支持高级方案过程。

将以下代码行添加到 OnRedirectToIdentityProvider 函数：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  context.ProtocolMessage.UiLocales = "es";

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

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

使用自定义策略，可以传递自定义查询字符串参数。良好的用例示例是想要动态更改页面内容。

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

配置 ContentDefinitionParameters 元素。
完成支持高级方案过程。

将以下代码行添加到 OnRedirectToIdentityProvider 函数：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  context.ProtocolMessage.Parameters.Add("campaignId", "123");

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

传递 ID 令牌提示

信赖方应用程序可以将入站 JSON Web 令牌（JWT）作为 OAuth2 授权请求的一部分发送。入站令牌是有关用户或授权请求的提示。 Azure AD B2C 验证令牌，然后提取声明。

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

完成支持高级方案过程。
在自定义策略中，定义 ID 令牌提示技术配置文件。

将以下代码行添加到 OnRedirectToIdentityProvider 函数：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
  // The idTokenHint variable holds your ID token 
  context.ProtocolMessage.IdTokenHint = idTokenHint

  // More code
  await Task.CompletedTask.ConfigureAwait(false);
}

帐户控制器

如果要自定义 SignIn、 SignUp 或 SignOut 作，建议创建自己的控制器。使用自己的控制器可以在控制器和身份验证库之间传递参数。 AccountController 是 NuGet 包的 Microsoft.Identity.Web.UI 一部分，用于处理登录和注销作。可以在 Microsoft标识 Web 库中找到其实现。

添加帐户控制器

在 Visual Studio 项目中，右键单击 “控制器 ”文件夹，然后添加新 的控制器。选择 MVC - 空控制器，然后提供名称 MyAccountController.cs。

以下代码片段演示了MyAccountController作的自定义。

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;


namespace mywebapp.Controllers
{
    [AllowAnonymous]
    [Area("MicrosoftIdentity")]
    [Route("[area]/[controller]/[action]")]
    public class MyAccountController : Controller
    {

        [HttpGet("{scheme?}")]
        public IActionResult SignIn([FromRoute] string scheme)
        {
            scheme ??= OpenIdConnectDefaults.AuthenticationScheme;
            var redirectUrl = Url.Content("~/");
            var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
            return Challenge(properties, scheme);
        }

    }
}

在 _LoginPartial.cshtml 视图中，将登录链接更改为控制器。

<form method="get" asp-area="MicrosoftIdentity" asp-controller="MyAccount" asp-action="SignIn">

传递 Azure AD B2C 策略 ID

以下代码片段演示了使用 MyAccountController 和 SignUp作的自定义。该作将传递给身份验证库的参数 policy 。这样，就可以为特定作提供正确的 Azure AD B2C 策略 ID。

public IActionResult SignIn([FromRoute] string scheme)
{
    scheme ??= OpenIdConnectDefaults.AuthenticationScheme;
    var redirectUrl = Url.Content("~/");
    var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
    properties.Items["policy"] = "B2C_1_SignIn";
    return Challenge(properties, scheme);
}

public IActionResult SignUp([FromRoute] string scheme)
{
    scheme ??= OpenIdConnectDefaults.AuthenticationScheme;
    var redirectUrl = Url.Content("~/");
    var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
    properties.Items["policy"] = "B2C_1_SignUp";
    return Challenge(properties, scheme);
}

在 _LoginPartial.cshtml 视图中，将 asp-controller 值更改为 MyAccountController 任何其他身份验证链接（例如注册或编辑配置文件）。

传递自定义参数

以下代码片段演示了MyAccountController作的自定义。该作将传递给身份验证库的参数 campaign_id 。

public IActionResult SignIn([FromRoute] string scheme)
{
    scheme ??= OpenIdConnectDefaults.AuthenticationScheme;
    var redirectUrl = Url.Content("~/");
    var properties = new AuthenticationProperties { RedirectUri = redirectUrl };
    properties.Items["policy"] = "B2C_1_SignIn";
    properties.Items["campaign_id"] = "1234";
    return Challenge(properties, scheme);
}

完成支持高级方案过程，然后在方法中 OnRedirectToIdentityProvider 读取自定义参数：

private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
{
    // Read the custom parameter
    var campaign_id = context.Properties.Items.FirstOrDefault(x => x.Key == "campaign_id").Value;

    // Add your custom code here
    if (campaign_id != null)
    {
        // Send parameter to authentication request
        context.ProtocolMessage.SetParameter("campaign_id", campaign_id);
    }
    
    await Task.CompletedTask.ConfigureAwait(false);
}

保护注销重定向

注销后，无论为应用程序指定的回复 URL 如何，用户都会重定向到参数中指定的 post_logout_redirect_uri URI。但是，如果传递了有效 id_token_hint 并且启用了注销请求中的“要求 ID 令牌 ”，Azure AD B2C 将验证是否与应用程序配置的重定向 URI 之一匹配的值 post_logout_redirect_uri ，然后再执行重定向。如果未为应用程序配置匹配的回复 URL，则会显示错误消息，并且不会重定向用户。

若要在应用程序中支持安全的注销重定向，请先遵循帐户控制器和支持高级方案部分中的步骤。然后执行以下步骤：

在 MyAccountController.cs 控制器中，使用以下代码片段添加注销作：

[HttpGet("{scheme?}")]
public async Task<IActionResult> SignOutAsync([FromRoute] string scheme)
{
    scheme ??= OpenIdConnectDefaults.AuthenticationScheme;

    //obtain the id_token
    var idToken = await HttpContext.GetTokenAsync("id_token");
    //send the id_token value to the authentication middleware
    properties.Items["id_token_hint"] = idToken;            

    return SignOut(properties,CookieAuthenticationDefaults.AuthenticationScheme,scheme);
}

在 Startup.cs 类中，分析 id_token_hint 值并将该值追加到身份验证请求。以下代码片段演示如何将 id_token_hint 值传递给身份验证请求：

private async Task OnRedirectToIdentityProviderForSignOutFunc(RedirectContext context)
{
    var id_token_hint = context.Properties.Items.FirstOrDefault(x => x.Key == "id_token_hint").Value;
    if (id_token_hint != null)
    {
        // Send parameter to authentication request
        context.ProtocolMessage.SetParameter("id_token_hint", id_token_hint);
    }

    await Task.CompletedTask.ConfigureAwait(false);
}

在函数中ConfigureServicesSaveTokens，添加控制器有权访问id_token值的选项：

services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        Configuration.Bind("AzureAdB2C", options);
        options.Events ??= new OpenIdConnectEvents();        
        options.Events.OnRedirectToIdentityProviderForSignOut += OnRedirectToIdentityProviderForSignOutFunc;
        options.SaveTokens = true;
    });

在 appsettings.json 配置文件中，将注销重定向 URI 路径添加到 SignedOutCallbackPath 密钥。

"AzureAdB2C": {
  "Instance": "https://<your-tenant-name>.b2clogin.com",
  "ClientId": "<web-app-application-id>",
  "Domain": "<your-b2c-___domain>",
  "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
  "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
}

在上面的示例中，传入注销请求的post_logout_redirect_uri采用以下格式： https://your-app.com/signout/<your-sign-up-in-policy> 必须将此 URL 添加到应用程序注册的答复 URL。

基于角色的访问控制

使用 ASP.NET Core 中的授权，可以检查用户是否有权使用以下方法之一访问受保护的资源：

在 ConfigureServices 方法中，添加 AddAuthorization 添加授权模型的方法。以下示例创建名为的策略。策略检查以验证声明 EmployeeNumber 是否存在。声明的值必须是以下 ID 之一：1、2、3、4 或 5。

services.AddAuthorization(options =>
    {
        options.AddPolicy("EmployeeOnly", policy =>
              policy.RequireClaim("EmployeeNumber", "1", "2", "3", "4", "5"));
    });

通过使用 AuthorizeAttribute 及其各种参数来控制 ASP.NET Core 中的授权。在最基本的窗体中，将 Authorize 属性应用于控制器、作或 Razor 页面会限制对该组件的经过身份验证的用户的访问。

将策略应用于控制器，方法是使用 Authorize 具有策略名称的属性。以下代码限制对由Claims策略授权的用户对作的访问EmployeeOnly：

[Authorize(Policy = "EmployeeOnly")]
public IActionResult Claims()
{
    return View();
}

后续步骤

若要了解有关授权的详细信息，请参阅 ASP.NET Core 中的授权简介。

通过

使用 Azure AD B2C 在 Web 应用中启用身份验证选项

使用自定义域

支持高级方案

预填充登录名称

预先选择标识提供者

指定 UI 语言

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

传递 ID 令牌提示

帐户控制器

添加帐户控制器

传递 Azure AD B2C 策略 ID

传递自定义参数

保护注销重定向

基于角色的访问控制

后续步骤

反馈

其他资源