使用OpenIddict时AddJwtBearer认证失败无法返回自定义错误求助

我之前也碰到过一模一样的情况——配置完OnAuthenticationFailed后，接口要么返回空内容，要么浏览器直接显示请求失败(failed)。核心问题在于没正确终止请求管道，也没完整处理响应的异步写入操作。下面是一步到位的解决方案：

1. 正确配置JwtBearer事件逻辑 #

在Startup.cs的ConfigureServices方法里，给AddJwtBearer补充完整的OnAuthenticationFailed处理逻辑：

using System.Text.Json;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Http;

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        // 基础配置请根据你的OpenIddict服务器调整
        options.Authority = "https://your-openiddict-server-url";
        options.Audience = "your-api-resource-name";
        options.RequireHttpsMetadata = true; // 生产环境建议开启

        options.Events = new JwtBearerEvents
        {
            OnAuthenticationFailed = async context =>
            {
                // 1. 设置自定义状态码与响应格式
                context.Response.StatusCode = StatusCodes.Status401Unauthorized;
                context.Response.ContentType = "application/json";

                // 2. 构造用户友好的自定义错误信息（可根据异常类型细化）
                var errorDetails = new
                {
                    error = "authentication_failed",
                    error_description = GetUserFriendlyMessage(context.Exception),
                    timestamp = DateTime.UtcNow.ToString("o")
                };

                // 3. 异步写入响应内容
                var jsonResponse = JsonSerializer.Serialize(errorDetails);
                await context.Response.WriteAsync(jsonResponse);

                // 4. 终止请求管道，避免后续中间件干扰响应
                context.HandleResponse();
            }
        };
    });

// 辅助方法：根据异常类型返回友好提示，生产环境隐藏敏感细节
private string GetUserFriendlyMessage(Exception ex)
{
    if (ex is SecurityTokenExpiredException)
    {
        return "认证令牌已过期，请重新登录。";
    }
    else if (ex is SecurityTokenInvalidSignatureException)
    {
        return "令牌签名无效，请检查请求参数。";
    }
    // 生产环境返回通用信息，开发环境可展示具体异常
    return Environment.IsDevelopment() ? ex.Message : "认证失败，请检查你的凭证。";
}

2. 确保中间件顺序正确 #

在Configure方法里，中间件的顺序直接影响认证逻辑是否生效——认证中间件必须放在路由和端点中间件之前：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...其他中间件（如异常处理、静态文件等）

    // 先启用认证，再启用授权
    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

常见问题排查 #

• 浏览器显示请求失败(failed)：大概率是没await响应写入就终止了管道，一定要确保await context.Response.WriteAsync(jsonResponse)执行完成后再调用context.HandleResponse()。
• 响应为空：检查是否忘记设置ContentType，或者没调用context.HandleResponse()导致后续中间件清空了响应内容。
• 异常信息不符合预期：生产环境记得不要直接返回原始异常消息，避免泄露服务器内部细节。

按这个配置完成后，当JWT认证失败时，你的API会返回带有自定义状态码和清晰错误信息的JSON响应，浏览器也能正常解析展示。

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