如何使用 Identity 保护 SPA 的 Web API 后端

ASP.NET Core Identity 提供用于处理身份验证、授权和 identity 管理的 API。 通过 API，可以使用基于 cookie 身份验证保护 Web API 后端的终结点。 基于令牌的选项适用于无法使用 Cookie 的客户端，但在使用此选项时，你负责确保令牌保持安全。 建议对基于浏览器的应用程序使用 Cookie，因为默认情况下，浏览器会自动处理它们，而不会将它们公开给 JavaScript。

本文演示如何使用 Identity 保护 SPA 的 Web API 后端，例如 Angular、React 和 Vue 应用。 同一后端 API 可用于保护 Blazor WebAssembly 应用。

先决条件

本文中介绍的步骤将身份验证和授权添加到 ASP.NET 核心 Web API 应用，该应用：

• 尚未为身份验证配置。
• 以 net8.0 或更高版本为目标。
• 可以是最小 API 或基于控制器的 API。

本文中的一些测试说明使用了项目模板随附的 Swagger UI。 Swagger UI 不需要与 Web API 后端一起使用 Identity。

安装 NuGet 包

安装以下 NuGet 包：

• Microsoft.AspNetCore.Identity.EntityFrameworkCore - 允许 Identity 使用 Entity Framework Core（EF Core）。
• 使 EF Core 能够处理数据库，例如以下包之一：
  • Microsoft.EntityFrameworkCore.SqlServer 或
  • Microsoft.EntityFrameworkCore.Sqlite 或
  • Microsoft.EntityFrameworkCore.InMemory。

若要快速开始使用，请使用内存中数据库。

稍后将数据库更改为 SQLite 或 SQL Server，以便在测试或供生产使用时在会话之间保存用户数据。 与内存中相比，这引入了一些复杂性，因为它需要通过迁移创建数据库，如入门教程EF Core所示。

使用 Visual Studio 中的 NuGet 包管理器或 dotnet add 包 CLI 命令安装这些包。

创建 IdentityDbContext

添加一个从 IdentityDbContext<TUser> 继承的名为 ApplicationDbContext 的类：

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) :
        base(options)
    { }
}

显示的代码提供了一个特殊的构造函数，可用于为不同的环境配置数据库。

添加这些步骤中显示的代码时，根据需要添加以下 using 一个或多个指令。

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

配置 EF Core 下文

如前所述，最简单的入门方法是使用内存中数据库。 在内存中，每次运行都以新的数据库开头，无需使用迁移。 调用 WebApplication.CreateBuilder(args) ，添加以下代码以配置 Identity，以使用内存中数据库：

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseInMemoryDatabase("AppDb"));

若要在测试或供生产使用时在会话之间保存用户数据，请稍后将数据库更改为 SQLite 或 SQL Server。

向容器添加 Identity 服务

调用 WebApplication.CreateBuilder(args) ，调用 AddAuthorization 以将服务添加到依赖项注入 （DI） 容器：

builder.Services.AddAuthorization();

激活 Identity API

调用 WebApplication.CreateBuilder(args) ，调用 AddIdentityApiEndpoints<TUser>(IServiceCollection) 和 AddEntityFrameworkStores<TContext>(IdentityBuilder)。

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

默认情况下，激活 Cookie 令牌和专有令牌。 如果登录终结点中的 useCookies 查询字符串参数为 true，则会在登录时发出 Cookie 和令牌。

映射 Identity 路由

调用 builder.Build() 后，调用 MapIdentityApi<TUser>(IEndpointRouteBuilder) 以映射 Identity 终结点：

app.MapIdentityApi<IdentityUser>();

保护所选的终结点

若要保护终结点，请在定义路由的 Map{Method} 调用上使用 RequireAuthorization 扩展方法。 例如：

app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        })
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi()
.RequireAuthorization();

RequireAuthorization 方法还可用于：

• 保护 Swagger UI 终结点，如以下示例所示：

  app.MapSwagger().RequireAuthorization();
  

• 使用特定声明或权限进行保护，如以下示例所示：

  .RequireAuthorization("Admin");
  

在基于控制器的 Web API 项目中，通过将 [Authorize] 属性应用于控制器或操作来保护终结点。

测试 API

测试身份验证的一种快速方法是使用项目模板附带的内存中数据库和 Swagger UI。 以下步骤演示如何使用 Swagger UI 测试 API。 确保 Swagger UI 终结点不受保护。

尝试访问受保护的终结点

• 运行应用并导航到 Swagger UI。
• 展开受保护的终结点，例如 Web API 模板在项目中创建的 /weatherforecast。
• 选择“试用”。
• 选择“执行”。 响应为 401 - not authorized。

测试注册

• 展开 /register 并选择“试用”。

• 在 UI 的“参数”部分中，会显示示例请求正文：

  {
    "email": "string",
    "password": "string"
  }
  

• 将“string”替换为有效的电子邮件地址和密码，然后选择“执行”。

  要遵守默认密码验证规则，密码长度必须至少为 6 个字符，并且至少包含以下每种字符之一：

  • 大写字母
  • 小写字母
  • 数字
  • 非字母数字字符

  如果输入无效的电子邮件地址或密码错误，则结果包括验证错误。 下面是包含验证错误的响应正文的示例：

  {
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
      "PasswordTooShort": [
        "Passwords must be at least 6 characters."
      ],
      "PasswordRequiresNonAlphanumeric": [
        "Passwords must have at least one non alphanumeric character."
      ],
      "PasswordRequiresDigit": [
        "Passwords must have at least one digit ('0'-'9')."
      ],
      "PasswordRequiresLower": [
        "Passwords must have at least one lowercase ('a'-'z')."
      ]
    }
  }
  

  错误是以 ProblemDetails 格式返回的，因此客户端可以对其进行分析，并根据需要显示验证错误。

  成功注册会带来 200 - OK 响应。

测试登录

• 展开 /login 并选择“试用”。示例请求正文显示两个附加参数：

  {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
    "twoFactorRecoveryCode": "string"
  }
  

  此示例不需要额外的 JSON 属性，可以删除。 将 useCookies 设置为 true。

• 将“string”替换为用于注册的电子邮件地址和密码，然后选择“执行”。

  成功登录会带来 200 - OK 响应及响应标头中包含 cookie。

重新测试安全终结点

成功登录后，重新运行受保护的终结点。 cookie 身份验证随请求一起自动发送，并授权终结点。 基于 Cookie 的身份验证安全地内置到浏览器，并“正常工作”。

使用非浏览器客户端进行测试

默认情况下，某些 Web 客户端的标头中可能不包括 Cookie：

• 如果使用工具来测试 API，则可能需要在设置中启用 Cookie。

• 默认情况下，JavaScript fetch API 不包含 Cookie。 通过在选项中将 credentials 设置为值 include，以启用它们。

• 在 Blazor WebAssembly 应用中运行的 HttpClient 需要 HttpRequestMessage，以包括凭据，如下所示：

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

使用基于令牌的身份验证

建议在基于浏览器的应用程序中使用 Cookie，因为默认情况下，浏览器会自动处理它们，而不会将它们公开给 JavaScript。

将颁发一个可用于对后续请求进行身份验证的自定义令牌（ASP.NET Core identity 平台专有的令牌）。 该令牌作为持有者令牌在 Authorization 标头中传递。 还会提供刷新令牌。 此令牌允许应用在旧令牌过期时请求新令牌，而无需强制用户再次登录。

该令牌不是标准的 JSON Web 令牌 (JWT)。 使用自定义令牌是有意而为的，因为内置 Identity API 主要用于简单方案。 令牌选项并不旨在作为全功能 identity 服务提供程序或令牌服务器，而是为无法使用 Cookie 的客户端提供 cookie 选项的备用项。

要使用基于令牌的身份验证，请在调用 /login 终结点时将 useCookies 查询字符串参数设置为 false。 令牌使用持有者身份验证方案。 使用从对 /login 的调用中返回的令牌，对受保护终结点的后续调用应添加标头 Authorization: Bearer <token>，其中 <token> 为访问令牌。 有关详细信息，请参阅本文后面的使用 POST /login 终结点。

注销

要为用户提供注销方法，请定义一个 /logout 终结点，如以下示例所示：

app.MapPost("/logout", async (SignInManager<IdentityUser> signInManager,
    [FromBody] object empty) =>
{
    if (empty != null)
    {
        await signInManager.SignOutAsync();
        return Results.Ok();
    }
    return Results.Unauthorized();
})
.WithOpenApi()
.RequireAuthorization();

调用此终结点时，在请求正文中提供空 JSON 对象 ({})。 以下代码是调用注销终结点的示例：

public signOut() {
  return this.http.post('/logout', {}, {
    withCredentials: true,
    observe: 'response',
    responseType: 'text'

MapIdentityApi<TUser> 终结点

对 MapIdentityApi<TUser> 进行调用会向应用添加以下终结点：

• POST /register
• POST /login
• POST /refresh
• GET /confirmEmail
• POST /resendConfirmationEmail
• POST /forgotPassword
• POST /resetPassword
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

使用 POST /register 终结点

请求正文必须包含 Email 和 Password 属性：

{
  "email": "string",
  "password": "string",
}

有关详细信息，请参阅：

• 本文前面的测试注册。
• RegisterRequest。

使用 POST /login 终结点

在请求正文中，Email 和 Password 是必需的。 如果启用了双因素身份验证 (2FA)，则 TwoFactorCode 或 TwoFactorRecoveryCode 是必需的。 如果未启用 2FA，则省略 twoFactorCode 和 twoFactorRecoveryCode。 有关详细信息，请参阅本文后面的使用 POST /manage/2fa 终结点。

下面是未启用 2FA 的请求正文示例：

{
  "email": "string",
  "password": "string"
}

下面是启用了 2FA 的请求正文示例：

• {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
  }
  

• {
    "email": "string",
    "password": "string",
    "twoFactorRecoveryCode": "string"
  }
  

终结点需要查询字符串参数：

• useCookies - 设置为 true，以进行基于 cookie 的身份验证。 设置为 false 或将其省略，以进行基于令牌的身份验证。

有关基于 cookie 的身份验证的详细信息，请参阅本文前面的测试登录。

基于令牌的身份验证

如果 useCookies 为 false 或省略，则启用基于令牌的身份验证。 响应正文包含以下属性：

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

有关这些属性的详细信息，请参阅 AccessTokenResponse。

将访问令牌放在标头中以发出经过身份验证的请求，如以下示例所示

Authorization: Bearer {access token}

当访问令牌即将过期时，调用 /refresh 终结点。

使用 POST /refresh 终结点

仅用于基于令牌的身份验证。 获取新的访问令牌，而无需强制用户再次登录。 请在访问令牌即将过期时调用此终结点。

请求正文仅包含 RefreshToken。 下面是请求正文示例：

{
  "refreshToken": "string"
}

如果调用成功，响应正文为新的 AccessTokenResponse，如以下示例所示：

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

使用 GET /confirmEmail 终结点

如果设置 Identity 以确认电子邮件，则成功调用终结点 /register 会发送一封电子邮件，其中包含指向 /confirmEmail 终结点的链接。 该链接包含以下查询字符串参数：

• userId
• code
• changedEmail - 仅当用户在注册期间更改了电子邮件地址时才包含。

Identity 为确认电子邮件提供默认文本。 默认情况下，电子邮件主题为“确认电子邮件”，电子邮件正文的外观则如以下示例所示：

 Please confirm your account by <a href='https://contoso.com/confirmEmail?userId={user ID}&code={generated code}&changedEmail={new email address}'>clicking here</a>.

如果将 RequireConfirmedEmail 属性设置为 true，则在通过单击电子邮件中的链接确认电子邮件地址之前，用户无法登录。 /confirmEmail 终结点：

• 确认电子邮件地址，以支持用户登录。
• 在响应正文中返回文本“感谢确认电子邮件”。

要设置 Identity 以实现电子邮件确认，请在 Program.cs 中添加代码，以将 RequireConfirmedEmail 设置为 true，并向 DI 容器添加可实现 IEmailSender 的类。 例如：

builder.Services.Configure<IdentityOptions>(options =>
{
    options.SignIn.RequireConfirmedEmail = true;
});

builder.Services.AddTransient<IEmailSender, EmailSender>();

有关详细信息，请参阅 ASP.NET Core 中的帐户确认和密码恢复。

Identity 还为需要发送的其他电子邮件提供默认文本，例如 2FA 和密码重置。 若要自定义这些电子邮件，请提供 IEmailSender 接口的自定义实现。 在前面的示例中，EmailSender 是实现 IEmailSender 的类。 有关详细信息，包括实现 IEmailSender的类的示例，请参阅 在 ASP.NET Core 中确认帐户和恢复密码。

使用 POST /resendConfirmationEmail 终结点

仅当地址对已注册用户有效时，才发送电子邮件。

请求正文仅包含 Email。 下面是请求正文示例：

{
  "email": "string"
}

有关详细信息，请参阅本文前面的使用 GET /confirmEmail 终结点。

使用 POST /forgotPassword 终结点

生成包含密码重置代码的电子邮件。 使用新密码将该代码发送到 /resetPassword。

请求正文仅包含 Email。 下面是一个示例：

{
  "email": "string"
}

有关如何启用 Identity 来发送电子邮件的信息，请参阅使用 GET /confirmEmail 终结点。

使用 POST /resetPassword 终结点

通过调用 /forgotPassword 终结点在获取重置代码后调用此终结点。

请求正文需要 Email、ResetCode 和 NewPassword。 下面是一个示例：

{
  "email": "string",
  "resetCode": "string",
  "newPassword": "string"
}

使用 POST /manage/2fa 终结点

为用户配置双因素身份验证 (2FA)。 启用 2FA 后，除了电子邮件地址和密码之外，成功登录还需要使用验证器应用生成的代码。

启用 2FA

要为当前经过身份验证的用户启用 2FA，请：

• 调用 /manage/2fa 终结点，以在请求正文中发送一个空的 JSON 对象 ({})。

• 响应正文会提供 SharedKey，以及目前并不需要的一些其他属性。 共享密钥用于设置验证器应用。 响应正文示例：

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 0,
    "recoveryCodes": null,
    "isTwoFactorEnabled": false,
    "isMachineRemembered": false
  }
  

• 使用共享密钥获取基于时间的一次性密码 (TOTP)。 有关详细信息，请参阅在 ASP.NET Core 中为 TOTP 验证器应用启用 QR 码生成。

• 调用 /manage/2fa 终结点，以在请求正文中发送 TOTP 和 "enable": true。 例如：

  {
    "enable": true,
    "twoFactorCode": "string"
  }
  

• 响应正文会确认 IsTwoFactorEnabled 为 true 并提供 RecoveryCodes。 恢复代码用于在验证器应用不可用时进行登录。 成功启用 2FA 后的响应正文示例：

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 10,
    "recoveryCodes": [
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string"
    ],
    "isTwoFactorEnabled": true,
    "isMachineRemembered": false
  }
  

使用 2FA 登录

调用 /login 终结点，以在请求正文中发送电子邮件地址、密码和 TOTP。 例如：

{
  "email": "string",
  "password": "string",
  "twoFactorCode": "string"
}

如果用户无权访问验证器应用，请使用启用 2FA 时提供的恢复代码之一调用 /login 终结点来进行登录。 请求正文如下方示例所示：

{
  "email": "string",
  "password": "string",
  "twoFactorRecoveryCode": "string"
}

重置恢复代码

要获取新的恢复代码集合，请在将 ResetRecoveryCodes 设置为 true 的情况下调用此终结点。 下面是请求正文示例：

{
  "resetRecoveryCodes": true
}

获取共享密钥

要获取新的随机共享密钥，请在将 ResetSharedKey 设置为 true 的情况下调用此终结点。 下面是请求正文示例：

{
  "resetSharedKey": true
}

在以后的请求重新启用要求已经过身份验证的用户进行双因素登录之前，重置密钥会自动禁用该要求。

忘记计算机

要清除 cookie“记住我标记”（如果存在），请在将 ForgetMachine 设置为 true 的情况下调用此终结点。 下面是请求正文示例：

{
  "forgetMachine": true
}

此终结点不会影响基于令牌的身份验证。

使用 GET /manage/info 终结点

获取已登录用户的电子邮件地址和电子邮件确认状态。 出于安全原因，已从此终结点中省略声明。 如果需要声明，请使用服务器端 API 为声明设置终结点。 或提供接受声明并响应用户是否拥有该声明的验证终结点，而不是共享所有用户的声明。

请求不需要任何参数。 响应正文包括属性 Email 和 IsEmailConfirmed，如以下示例所示：

{
  "email": "string",
  "isEmailConfirmed": true
}

使用 POST /manage/info 终结点

更新已登录用户的电子邮件地址和密码。 在请求正文中发送 NewEmail、NewPassword 和 OldPassword，如以下示例所示：

{
  "newEmail": "string",
  "newPassword": "string",
  "oldPassword": "string"
}

下面是响应正文的示例：

{
  "email": "string",
  "isEmailConfirmed": false
}

另请参阅

有关更多信息，请参阅以下资源：

• 选择 identity 管理解决方案
• 适用于 .NET Web 应用的Identity管理解决方案
• ASP.NET Core 中的简单授权
• 在 ASP.NET Core 项目中向 Identity 添加和下载用户数据，以及从中删除用户数据
• 通过授权保护的用户数据创建 ASP.NET Core 应用
• ASP.NET Core 中的帐户确认和密码恢复
• 为 ASP.NET Core 中的 TOTP 验证器应用启用 QR 码生成
• SPA的示例 Web API 后端 .http 文件显示基于令牌的身份验证。 例如：
  • 未设置 useCookies
  • 使用授权标头传递令牌
  • 显示刷新以扩展会话，而无需强制用户再次登录
• 示例 Angular 应用，该应用使用 Identity 来保护 Web API 后端