.NET 2.2集成Keycloak JWT认证遇401错误（Swagger异常）

核心根源：.NET 2.2与.NET 6的Swagger认证配置差异 #

.NET 2.2依赖的Swashbuckle.AspNetCore是4.x系列版本，和.NET 6使用的6.x+版本在OAuth2/Bearer认证的配置逻辑上有明显区别，这是导致Swagger调用失败的最可能原因。

分步排查与修复方案 #

1. 补全Swagger的Bearer Token传递配置 #

.NET 2.2的Swagger不会自动携带Authorization请求头，必须显式添加安全定义和要求：

// Startup.cs -> ConfigureServices
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "你的API名称", Version = "v1" });
    
    // 定义Bearer认证规则
    c.AddSecurityDefinition("Bearer", new ApiKeyScheme
    {
        Description = "JWT认证格式：Authorization: Bearer {token}",
        Name = "Authorization",
        In = "header",
        Type = "apiKey"
    });
    
    // 为所有接口添加Bearer认证要求
    c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>>
    {
        { "Bearer", new string[] {} }
    });
});

如果缺少这段配置，Swagger发送的请求不会携带token，直接触发401。

2. 修正Swagger OAuth2授权流程配置（若使用Swagger直接登录Keycloak） #

如果你的Swagger是通过OAuth2对接Keycloak自动获取token，需确保配置参数与Keycloak完全匹配：

// Startup.cs -> Configure
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "你的API V1");
    // 配置Keycloak OAuth2参数
    c.OAuthClientId("swagger客户端ID"); // Keycloak后台创建的客户端ID
    c.OAuthClientSecret("swagger客户端密钥"); // 若Keycloak客户端设为机密类型，需填写
    c.OAuthRealm("你的Realm名称"); // Keycloak的Realm名
    c.OAuthAppName("Swagger UI");
    c.OAuthScopeSeparator(" ");
    c.OAuthUseBasicAuthenticationWithAccessCodeGrant(); // Keycloak环境下需开启此选项
});

注意：Keycloak客户端必须配置正确的Valid Redirect URIs（例如http://localhost:5000/swagger/oauth2-redirect.html），否则授权后无法回调获取token。

3. 检查中间件执行顺序 #

.NET 2.2对中间件顺序要求严格，认证中间件必须在MVC之前执行：

// Startup.cs -> Configure
app.UseAuthentication(); // 必须放在UseMvc之前
app.UseAuthorization();
app.UseMvc();

// Swagger中间件放在MVC之后
app.UseSwagger();
app.UseSwaggerUI(c => { ... });

如果UseAuthentication在UseMvc之后，请求会先进入MVC管道，未经过认证就被拦截返回401。

4. 验证Keycloak JWT认证配置兼容性 #

对比.NET 6的认证扩展类，检查.NET 2.2中的JWT配置是否正确：

// 认证扩展类示例
public static class AuthenticationExtensions
{
    public static IServiceCollection AddKeycloakAuthentication(this IServiceCollection services, IConfiguration config)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddJwtBearer(options =>
            {
                options.Authority = config["Keycloak:Authority"]; // 格式：https://你的Keycloak地址/auth/realms/你的Realm名
                options.Audience = config["Keycloak:Audience"]; // Keycloak客户端的Client ID
                options.RequireHttpsMetadata = false; // 开发环境可关闭，生产必须开启
                options.TokenValidationParameters = new TokenValidationParameters
                {
                    ValidateIssuer = true,
                    ValidIssuer = config["Keycloak:Authority"],
                    ValidateAudience = true,
                    ValidAudience = config["Keycloak:Audience"],
                    ValidateLifetime = true
                };
            });
        return services;
    }
}

注意：Keycloak的Authority路径需与Postman中获取token的地址一致，旧版本Keycloak路径包含/auth，新版本可能仅为/realms。

5. 确认Swagger的Token输入格式 #

在Swagger UI的"Authorize"弹窗中输入token时，必须完整填写Bearer {token}，不能只输入token字符串。如果之前未配置AddSecurityDefinition，Swagger不会自动添加Bearer前缀，导致认证失败。

辅助验证手段 #

1. 开启认证日志排查具体失败原因：
   在appsettings.json中添加日志配置：

{
  "Logging": {
    "LogLevel": {
      "Microsoft.AspNetCore.Authentication": "Debug"
    }
  }
}

启动项目后查看日志，可明确是token无效、Audience不匹配还是请求头缺失导致的401。

2. 对比Postman与Swagger的请求头：
   通过Chrome开发者工具查看Swagger发送的请求头，确认Authorization: Bearer {token}是否存在，且与Postman的请求头完全一致。

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