ASP.NET Core Minimal API未映射URL未认证请求返回404而非401问题

你的问题核心是中间件执行顺序导致的：路由匹配中间件在认证之后运行，当请求未匹配到任何端点时，路由会设置404状态码，覆盖了认证处理器已添加的401状态和WWW-Authenticate头。以下几种方案可以修改这个行为，让认证失败时直接终止请求处理或强制返回401：

方案一：在自定义AuthenticationHandler中直接终止请求 #

在你的BasicAuthenticationHandler的HandleAuthenticateAsync方法里，当认证失败时，直接设置响应状态码并完成响应，阻止后续中间件继续处理：

protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
{
    // 提取并验证基础认证凭证的逻辑
    if (!Request.Headers.ContainsKey("Authorization"))
    {
        return AuthenticateResult.Fail("Authorization header missing");
    }

    var authHeader = AuthenticationHeaderValue.Parse(Request.Headers["Authorization"]);
    var credentials = Encoding.UTF8.GetString(Convert.FromBase64String(authHeader.Parameter)).Split(':');
    var username = credentials[0];
    var password = credentials[1];

    // 替换成你的凭证验证逻辑
    if (username != "admin" || password != "password")
    {
        // 添加WWW-Authenticate头
        Response.Headers.WWWAuthenticate = "Basic realm=\"YourApiRealm\"";
        // 设置401状态码
        Response.StatusCode = StatusCodes.Status401Unauthorized;
        // 直接完成响应，终止后续中间件处理
        await Response.CompleteAsync();
        return AuthenticateResult.Fail("Invalid credentials");
    }

    // 认证成功，生成身份凭证
    var claims = new[] { new Claim(ClaimTypes.Name, username) };
    var identity = new ClaimsIdentity(claims, Scheme.Name);
    var principal = new ClaimsPrincipal(identity);
    var ticket = new AuthenticationTicket(principal, Scheme.Name);

    return AuthenticateResult.Success(ticket);
}

Response.CompleteAsync()会立即结束响应流程，路由中间件不会再执行，自然不会覆盖401状态码。

方案二：添加全局拦截中间件 #

如果不想修改认证处理器，可以在路由中间件之后添加一个自定义中间件，拦截未认证的404请求并替换为401：

var builder = WebApplication.CreateBuilder(args);

// 注册服务...
builder.Services.AddAuthentication("Basic").AddScheme<AuthenticationSchemeOptions, BasicAuthenticationHandler>("Basic", null);
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

// 拦截未认证的404请求
app.Use(async (context, next) =>
{
    await next();

    // 仅当响应未启动、用户未认证且当前状态码是404时修改
    if (!context.Response.HasStarted 
        && !context.User.Identity.IsAuthenticated 
        && context.Response.StatusCode == StatusCodes.Status404NotFound)
    {
        context.Response.StatusCode = StatusCodes.Status401Unauthorized;
        context.Response.Headers.WWWAuthenticate = "Basic realm=\"YourApiRealm\"";
    }
});

app.MapControllers();

app.Run();

这个方案的逻辑是让路由先处理端点匹配，若返回404且用户未认证，就把响应替换为401。

方案三：配置认证转发规则强制触发挑战 #

通过配置AuthenticationOptions，让所有未认证请求都触发认证挑战，不管是否匹配端点：

builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = "Basic";
    options.DefaultChallengeScheme = "Basic";
    // 让所有请求都使用Basic认证方案
    options.ForwardDefaultSelector = _ => "Basic";
}).AddScheme<AuthenticationSchemeOptions, BasicAuthenticationHandler>("Basic", null);

同时确保你的认证处理器正确实现HandleChallengeAsync方法：

protected override Task HandleChallengeAsync(AuthenticationProperties properties)
{
    Response.Headers.WWWAuthenticate = "Basic realm=\"YourApiRealm\"";
    Response.StatusCode = StatusCodes.Status401Unauthorized;
    return Task.CompletedTask;
}

这样，当请求未认证时，ASP.NET Core会自动触发认证挑战，返回401，而不是让路由返回404。

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