ASP.NET Core 8.0 Identity配置后无调用文档，如何实现SPA双因素认证

一、为Identity API Endpoints补充Swagger文档 #

ASP.NET Core 8的AddIdentityApiEndpoints默认不会自动将端点的详细说明注入Swagger，需手动配置加载相关注释：

1. 启用项目XML文档生成
   在项目属性的“生成”选项卡中勾选“XML文档文件”，或直接在.csproj中添加：

   <PropertyGroup>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <NoWarn>$(NoWarn);1591</NoWarn> <!-- 忽略未添加注释的编译警告 -->
   </PropertyGroup>
   

2. 加载Identity API官方注释
   在Program.cs的Swagger配置中，同时加载项目自身和Identity API的XML注释文件：

   builder.Services.AddSwaggerGen(c =>
   {
       // 加载项目本地注释
       var projXml = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");
       c.IncludeXmlComments(projXml);
   
       // 加载Identity API官方注释（需确保该文件存在于输出目录）
       var identityXml = Path.Combine(AppContext.BaseDirectory, "Microsoft.AspNetCore.Identity.Api.xml");
       if (File.Exists(identityXml)) c.IncludeXmlComments(identityXml);
   });
   

   若找不到Microsoft.AspNetCore.Identity.Api.xml，可从NuGet包目录（~/.nuget/packages/microsoft.aspnetcore.identity.api/8.0.x/lib/net8.0/）手动复制到项目输出目录。

3. 自定义端点描述（可选）
   若官方注释不够清晰，可通过WithMetadata为端点添加自定义Swagger描述：

   app.MapIdentityApi<IdentityUser>()
       .WithMetadata(new SwaggerOperationAttribute("用户登录", "通过用户名密码获取JWT令牌"))
       .WithMetadata(new SwaggerResponseAttribute(200, "登录成功，返回JWT令牌"));
   

二、SPA中实现双因素认证（2FA） #

基于ASP.NET Core 8 Identity API，SPA的2FA流程分为绑定验证器和登录验证两个环节：

1. 绑定TOTP验证器（以Google Authenticator为例） #

• 用户登录后，前端调用GET /api/Users/TwoFactorAuthentication/Authenticator，获取TOTP密钥和二维码URL，用于用户扫描绑定验证器。
• 用户输入验证器生成的验证码后，前端发送POST /api/Users/TwoFactorAuthentication/Authenticator，携带验证码。验证通过后，后端启用2FA并返回恢复代码，前端需提示用户保存。

2. 登录时的2FA验证流程 #

• 第一步：普通登录
  前端发送POST /api/Users/Login携带用户名密码。若用户已启用2FA，后端返回401 Unauthorized，并在响应体中返回twoFactorToken（临时验证令牌）。
• 第二步：提交验证码
  前端提示用户输入验证码，发送POST /api/Users/TwoFactorAuthentication/Authenticator/Login，携带twoFactorToken、验证码，可选rememberClient: true（记住设备，后续登录跳过2FA）。验证通过后，后端返回正式JWT，前端保存用于后续请求。

React示例代码 #

async function handleLogin(username, password) {
  const loginRes = await fetch('/api/Users/Login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password })
  });

  if (loginRes.status === 401) {
    const { twoFactorToken } = await loginRes.json();
    const code = prompt('请输入2FA验证码');
    const verifyRes = await fetch('/api/Users/TwoFactorAuthentication/Authenticator/Login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ twoFactorToken, code, rememberClient: true })
    });

    if (verifyRes.ok) {
      const { token } = await verifyRes.json();
      localStorage.setItem('jwt', token);
      return true;
    }
  } else if (loginRes.ok) {
    const { token } = await loginRes.json();
    localStorage.setItem('jwt', token);
    return true;
  }
  return false;
}

后端配置要点 #

• 确保Identity服务启用令牌生成器：

  builder.Services.AddIdentityApiEndpoints<IdentityUser>()
      .AddEntityFrameworkStores<AppDbContext>()
      .AddDefaultTokenProviders(); // 用于生成2FA验证码
  

• JWT配置中建议包含TwoFactorEnabled声明，方便前端判断用户2FA状态。

内容的提问来源于stack exchange，提问作者bubi