ASP.NET Core 5 Web API未认证请求返回404而非401如何解决

问题根因 #

你遇到的现象是ASP.NET Core的默认未授权请求处理逻辑导致的：默认配置下，框架接收到未授权的受保护端点请求时，会尝试将请求重定向到预设的登录页面，由于你的Web API没有配置对应登录页的路由，就会返回404状态码。

解决方法 #

方案1：配置认证服务的挑战行为，禁用重定向 #

修改你ConfigureServices方法中AddAuthentication的配置，覆盖默认的挑战逻辑，直接返回401格式响应：

services.AddAuthentication("BasicAuthentication")
    .AddScheme<AuthenticationSchemeOptions, BasicAuthenticationHandler>("BasicAuthentication", options =>
    {
        // 覆盖默认挑战逻辑，禁用重定向
        options.Events = new AuthenticationEvents
        {
            OnChallenge = context =>
            {
                // 跳过默认的挑战处理逻辑，不会触发重定向
                context.HandleResponse();
                context.Response.StatusCode = 401;
                context.Response.ContentType = "application/json";
                return context.Response.WriteAsJsonAsync(new 
                { 
                    code = 401,
                    message = "未授权，请提供有效身份凭证" 
                });
            }
        };
    });

方案2：全局状态码拦截（通用兼容方案） #

如果需要统一处理所有状态码的返回格式，或者你的404不是由认证重定向导致的，可以用全局状态码中间件拦截响应，按需修改返回内容。在Configure方法的最开头（优先于所有其他中间件）添加如下配置即可：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 全局状态码拦截中间件，必须放在最前面
    app.UseStatusCodePages(async context =>
    {
        var response = context.HttpContext.Response;
        var request = context.HttpContext.Request;

        // 拦截未授权/无权限的响应，返回自定义JSON
        if (response.StatusCode is 401 or 403)
        {
            response.ContentType = "application/json";
            await response.WriteAsJsonAsync(new
            {
                code = response.StatusCode,
                message = response.StatusCode == 401 ? "未授权，请提供有效身份凭证" : "无权限访问该资源"
            });
        }

        // 如果需要将特定场景的404改为401，可以在这里加逻辑
        // 示例：判断请求路径属于API接口，且返回404时修改为401
        // else if (response.StatusCode == 404 && request.Path.StartsWithSegments("/api"))
        // {
        //     response.StatusCode = 401;
        //     response.ContentType = "application/json";
        //     await response.WriteAsJsonAsync(new { code = 401, message = "未授权，无法访问该资源" });
        // }
    });

    // 下方保留你原本的中间件配置即可
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/error");
        app.UseHsts();
    }
    // ... 其余原有代码保持不变
}

注意事项 #

• 请确认你自定义的BasicAuthenticationHandler中，认证失败时直接返回AuthenticateResult.Fail("失败原因")即可，不需要额外处理重定向逻辑。
• 你当前的中间件顺序UseAuthentication在UseAuthorization之前是正确的，不需要调整。

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