.NET Core 6中基于Keycloak Realm URL实现JWT认证方法咨询

一、前置准备 #

你需要提前确认以下Keycloak配置信息：

• Keycloak服务器地址（如https://your-keycloak-server.com）
• 目标Realm名称（比如my-realm）
• 已在该Realm下创建的客户端ID（对应Keycloak控制台里的客户端配置）

Keycloak的OIDC发现端点会自动提供证书等验证所需的元数据，地址为{Keycloak地址}/realms/{Realm名称}/.well-known/openid-configuration，不需要手动下载证书。

二、项目配置与代码实现 #

1. 配置文件（appsettings.json） #

先在配置文件里存储Keycloak相关参数，方便后续修改：

{
  "Keycloak": {
    "Host": "https://your-keycloak-server.com",
    "Realm": "my-realm",
    "ClientId": "my-dotnet-client"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

2. 注册认证与授权服务（Program.cs） #

在.NET 6的顶级语句中配置JWT认证，核心是通过Authority参数关联Realm，并利用Keycloak的OIDC自动获取验证证书：

var builder = WebApplication.CreateBuilder(args);

// 注册JWT认证服务
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        var keycloakConfig = builder.Configuration.GetSection("Keycloak");
        var realm = keycloakConfig["Realm"];
        var host = keycloakConfig["Host"];
        
        // 构造包含Realm的授权服务器地址，这是关联Realm的核心
        options.Authority = $"{host}/realms/{realm}";
        // 设置要验证的受众（对应Keycloak客户端ID）
        options.Audience = keycloakConfig["ClientId"];
        
        // 配置Token验证规则
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            // 无需手动指定签名密钥，AddJwtBearer会自动从Authority的OIDC端点获取JWKS
        };
        
        // 可选：自定义Realm验证逻辑，确保Token来自指定Realm
        options.Events = new JwtBearerEvents
        {
            OnTokenValidated = context =>
            {
                var expectedIssuer = $"{host}/realms/{realm}";
                if (!context.SecurityToken.Issuer.Equals(expectedIssuer, StringComparison.OrdinalIgnoreCase))
                {
                    context.Fail("Token不属于指定的Realm");
                }
                return Task.CompletedTask;
            }
        };
    });

// 注册授权服务
builder.Services.AddAuthorization();

var app = builder.Build();

// 启用认证、授权中间件（顺序不能错）
app.UseAuthentication();
app.UseAuthorization();

// 示例：受保护的API端点
app.MapGet("/api/protected", (HttpContext context) =>
{
    var user = context.User.Identity?.Name;
    return Results.Ok($"欢迎访问受保护端点，当前用户：{user}");
}).RequireAuthorization();

// 示例：基于Realm角色的授权
app.MapGet("/api/admin", () => Results.Ok("管理员权限验证通过"))
   .RequireAuthorization(policy => policy.RequireClaim("realm_access", "admin"));

app.Run();

三、Realm参数的核心作用与验证逻辑 #

1. 通过Authority关联Realm：Authority参数直接包含Realm名称，AddJwtBearer会自动访问该Realm的OIDC发现端点，获取对应的签名证书、颁发者信息等，确保只验证来自该Realm的Token。
2. 手动验证Realm：在OnTokenValidated事件中，可以对比Token的iss声明（格式为{host}/realms/{realm}）与配置的预期值，进一步防止其他Realm的Token被误通过。
3. 基于Realm角色的授权：Keycloak颁发的Token会包含realm_access声明，其中存储了用户在该Realm下的角色，你可以通过授权策略验证这些角色，实现细粒度权限控制。

四、测试验证 #

1. 获取Keycloak Token：向{Keycloak地址}/realms/{Realm名称}/protocol/openid-connect/token发送POST请求，参数如下：
   • grant_type: password
   • client_id: 你的客户端ID
   • client_secret: 客户端密钥（如果是保密客户端）
   • username: Keycloak用户账号
   • password: 用户密码
2. 访问受保护端点：将获取到的Token放在请求头的Authorization字段（格式为Bearer {Token}），请求/api/protected或/api/admin，验证权限是否生效。

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