.NET 8 JWT项目2FA恢复码登录失败的原因及解决办法

我在为.NET 8应用实现双因素认证（2FA），该应用不使用Razor Pages，采用JWT令牌授权而非Cookie。目前已完成以下功能：

• 成功为用户启用验证器
• 生成并在数据库中存储恢复码
• 通过验证器应用的验证码可正常登录

但使用恢复码登录时，调用signInManager.TwoFactorRecoveryCodeSignInAsync(code)始终返回Failed。已确认恢复码有效，甚至尝试提前临时登录用户，问题仍未解决。相关接口代码如下：

[HttpPost("RecoveryCodeLogin")]
public async Task<IActionResult> RecoveryCodeLogin(RecoveryCodeLoginModel model)
{
    var user = await userManager.FindByEmailAsync(model.UserEmail);

    if (user == null)
    {
        return Unauthorized();
    }

    var result = await signInManager.TwoFactorRecoveryCodeSignInAsync(model.RecoveryCode);

    if (!result.Succeeded)
    {
        return BadRequest();
    }

    return Ok(GenerateToken(user));
}

请问该问题的原因是什么，以及如何修复？

原因分析与修复方案 #

原因 #

TwoFactorRecoveryCodeSignInAsync方法的设计依赖当前已完成第一步验证（用户名/密码登录，进入2FA验证阶段）的用户上下文，它不会直接通过恢复码匹配用户。在你的JWT场景中，没有提前建立用户的预登录会话，方法无法定位到对应用户，因此验证失败。

修复方案 #

方案一：先完成用户预登录（推荐）

在验证恢复码前，先通过用户名+密码完成第一步登录，建立临时用户上下文，再调用恢复码验证方法：

[HttpPost("RecoveryCodeLogin")]
public async Task<IActionResult> RecoveryCodeLogin(RecoveryCodeLoginModel model)
{
    var user = await userManager.FindByEmailAsync(model.UserEmail);

    if (user == null)
    {
        return Unauthorized("用户不存在");
    }

    // 第一步：验证用户密码，建立预登录上下文
    var passwordSignInResult = await signInManager.CheckPasswordSignInAsync(user, model.Password, lockoutOnFailure: false);
    if (!passwordSignInResult.Succeeded)
    {
        return Unauthorized("密码错误");
    }

    // 第二步：验证恢复码
    var result = await signInManager.TwoFactorRecoveryCodeSignInAsync(model.RecoveryCode);

    if (!result.Succeeded)
    {
        return BadRequest("恢复码无效或已使用");
    }

    // 恢复码验证成功后会自动作废，生成JWT返回
    return Ok(GenerateToken(user));
}

方案二：手动验证恢复码并更新状态

如果不想依赖预登录流程，可以直接使用UserManager的方法手动验证恢复码，验证通过后手动标记该码为已使用：

[HttpPost("RecoveryCodeLogin")]
public async Task<IActionResult> RecoveryCodeLogin(RecoveryCodeLoginModel model)
{
    var user = await userManager.FindByEmailAsync(model.UserEmail);

    if (user == null)
    {
        return Unauthorized("用户不存在");
    }

    // 手动验证恢复码有效性
    var isValidRecoveryCode = await userManager.VerifyTwoFactorRecoveryCodeAsync(user, model.RecoveryCode);
    if (!isValidRecoveryCode)
    {
        return BadRequest("恢复码无效或已使用");
    }

    // 验证成功后，生成新的恢复码替换旧的（移除已使用的码）
    var remainingCodes = await userManager.GenerateNewTwoFactorRecoveryCodesAsync(user, 10);
    await userManager.SetTwoFactorEnabledAsync(user, true); // 确保2FA保持启用状态

    // 生成JWT返回
    return Ok(GenerateToken(user));
}

关键注意点 #

• 恢复码是一次性的，验证成功后必须从用户存储中移除，避免重复使用
• 在无Cookie的JWT架构中，UserManager的方法比依赖会话的SignInManager更适配场景

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