如何在ASP.NET Core Web API中配置HTTP-Only Cookie实现JWT认证？

核心问题分析 #

你的配置思路是对的：通过JwtBearerEvents.OnMessageReceived从HTTP-Only Cookie中提取Access Token，替代默认的Bearer头传递方式。当前[Authorize]失效的原因大概率是中间件顺序、参数匹配或日志缺失导致的隐藏验证失败，而非逻辑方向错误。

分步排查与修复 #

1. 强制确认中间件顺序 #

ASP.NET Core中间件的执行顺序直接决定认证授权是否生效，必须严格遵循以下顺序：

var app = builder.Build();

// ... 其他中间件（如静态文件、CORS等）
app.UseRouting();

// 先执行认证，再执行授权 - 顺序绝对不能反
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();
app.Run();

2. 完善OnMessageReceived逻辑（添加验证日志） #

修改事件处理代码，添加日志输出确认Token是否被正确捕获，同时保留兼容Bearer头的逻辑（可选）：

options.Events = new JwtBearerEvents
{
    OnMessageReceived = ctx =>
    {
        // 优先从Cookie获取Access Token
        if (ctx.Request.Cookies.TryGetValue("access-token", out var accessToken) && !string.IsNullOrEmpty(accessToken))
        {
            ctx.Token = accessToken;
            // 建议添加日志验证，确认Token已被赋值
            ctx.HttpContext.RequestServices.GetRequiredService<ILogger<Program>>()
                .LogDebug("Access Token retrieved from HTTP-Only Cookie");
        }
        // 兼容Bearer头传递（可选，用于调试或特殊场景）
        else
        {
            var bearerToken = ctx.Request.Headers.Authorization.FirstOrDefault()?.Split(" ").Last();
            if (!string.IsNullOrEmpty(bearerToken))
            {
                ctx.Token = bearerToken;
            }
        }
        return Task.CompletedTask;
    },
    // 可选：添加认证失败日志，直接定位问题
    OnAuthenticationFailed = ctx =>
    {
        ctx.HttpContext.RequestServices.GetRequiredService<ILogger<Program>>()
            .LogError(ctx.Exception, "JWT Authentication Failed");
        return Task.CompletedTask;
    }
};

3. 确保Token生成与验证参数完全一致 #

你的TokenValidationParameters必须和生成JWT时的参数完全匹配，比如：

• 生成Token时指定的Issuer必须和ValidIssuer一致
• 签名密钥IssuerSigningKey必须和生成时使用的密钥完全相同
• 如果生成Token时设置了Audience，则不能将ValidateAudience设为false（或同步设置ValidAudience）

4. 启用调试日志定位验证失败原因 #

在appsettings.json中添加日志配置，查看认证过程的详细错误信息：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore.Authentication": "Debug",
      "Microsoft.AspNetCore.Authentication.JwtBearer": "Debug"
    }
  }
}

启动程序后，查看控制台日志中与JWT认证相关的Debug信息，会明确提示验证失败的具体原因（如令牌过期、签名错误、Issuer不匹配等）。

5. 确认HTTP-Only Cookie的设置正确性 #

设置Cookie时必须确保以下属性配置正确，否则浏览器不会在请求中携带Cookie：

// 生成Access Token后的Cookie设置代码示例
var accessCookieOptions = new CookieOptions
{
    HttpOnly = true,
    Secure = Environment.IsProduction(), // 生产环境必须开启HTTPS并设为true
    SameSite = SameSiteMode.Strict, // 防止CSRF，根据业务场景可调整为Lax
    Expires = DateTime.UtcNow.AddMinutes(15), // 与Access Token过期时间保持一致
    Path = "/" // 确保所有请求路径都能携带该Cookie
};
Response.Cookies.Append("access-token", generatedAccessToken, accessCookieOptions);

6. 验证[Authorize]属性的使用 #

如果你的系统存在多个认证方案，需要明确指定JWT方案：

[Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme)]
[HttpGet("protected")]
public IActionResult ProtectedEndpoint()
{
    return Ok("Authorized access granted");
}

额外补充：Refresh Token的HTTP-Only实现要点 #

1. Refresh Token的Cookie过期时间应远长于Access Token（如7天）
2. 刷新Token的端点必须允许匿名访问（添加[AllowAnonymous]）
3. 刷新时需验证Refresh Token的有效性（建议存储到数据库/缓存，避免仅依赖JWT验证）
4. 刷新成功后，应生成新的Access Token和Refresh Token，并覆盖旧的HTTP-Only Cookie

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