.NET8 FastEndpoints修改密码接口未带JWT返回404而非401问题

问题描述 #

在.NET8项目中使用FastEndpoints框架开发change-password接口时，发现未携带Authorization请求头测试该接口时，返回的是404状态码，而非预期的401（未授权）状态码。其他标记为匿名的接口工作正常，推测是配置问题但无法定位错误。

相关接口代码：

public class ChangePasswordEndpoint : Endpoint<ChangePasswordRequest>
{
    private readonly IAuthService _authService;

    public ChangePasswordEndpoint(IAuthService authService) => _authService = authService;

    public override void Configure()
    {
        Post("/auth/change-password");
        Claims("UserId");
    }

    public override async Task HandleAsync(ChangePasswordRequest req, CancellationToken ct)
    {
        var userId = User.FindFirstValue("UserId");
        req.UserId = Convert.ToInt32(userId);
        await _authService.ChangePasswordAsync(req);
        await SendOkAsync(ct);
    }
}

Program.cs相关配置：

var builder = WebApplication.CreateBuilder();
builder.Services
    .AddFastEndpoints()
    .AddJWTBearerAuth(builder.Configuration.GetSection("GeneralSettings:JwtSecret").Value)
    .AddAuthorization();
builder.Services.SwaggerDocument();

// 其他服务注册代码...

var app = builder.Build();
app.UseAuthentication()
   .UseAuthorization()
   .UseFastEndpoints(c =>
{
    c.Endpoints.RoutePrefix = "api";
    c.Serializer.Options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase; 
});
// 其他中间件配置...

app.Run();

原因分析 #

1. FastEndpoints默认行为：使用Claims("UserId")方法时，框架会将接口标记为需要特定声明，并且默认对未认证请求返回404（隐藏接口存在性），而非401。
2. 授权策略未显式配置：仅通过Claims方法声明权限，未关联到ASP.NET Core的授权系统，导致认证中间件无法正确拦截未授权请求。
3. JWT配置可能不完整：仅传递JwtSecret的情况下，Token验证参数可能缺失，影响认证逻辑的正确性。

解决方案 #

方案1：显式使用授权策略替代Claims方法 #

修改接口的Configure方法，使用Authorize方法并指定需要的声明，触发ASP.NET Core的授权流程，未认证请求会返回401：

public override void Configure()
{
    Post("/auth/change-password");
    // 显式声明需要UserId声明的授权策略
    Authorize(policy => policy.RequireClaim("UserId"));
}

方案2：全局配置未认证请求返回401 #

如果希望所有需要认证的接口在未携带Token时都返回401，可以在FastEndpoints的全局配置中自定义错误响应：

app.UseFastEndpoints(c =>
{
    c.Endpoints.RoutePrefix = "api";
    c.Serializer.Options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    // 自定义错误响应构建器
    c.ErrorResponseBuilder = (failure, context) =>
    {
        if (failure.FailureType == FailureType.Unauthorized)
        {
            context.Response.StatusCode = StatusCodes.Status401Unauthorized;
            return new { Message = "未授权访问，请携带有效Token" };
        }
        // 其他错误类型使用默认处理
        return FastEndpoints.DefaultErrorResponseBuilder(failure, context);
    };
});

方案3：完善JWT认证配置 #

确保JWTBearer认证的参数配置完整，避免因Token验证逻辑异常导致的问题：

builder.Services
    .AddFastEndpoints()
    .AddJWTBearerAuth(options =>
    {
        var jwtSecret = builder.Configuration.GetSection("GeneralSettings:JwtSecret").Value;
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwtSecret)),
            ValidateIssuer = false, // 根据实际业务需求设置是否验证Issuer
            ValidateAudience = false, // 根据实际业务需求设置是否验证Audience
            ClockSkew = TimeSpan.Zero // 关闭时钟偏移容忍
        };
    })
    .AddAuthorization();

验证 #

修改完成后，重新启动项目，未携带Authorization头请求/api/auth/change-password接口，此时应该返回401状态码，符合预期。

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