ASP.NET Framework Web API基于Keycloak与JWT的认证及401问题排查

针对程序间无用户参与的通信场景，以下是完整配置步骤及401错误排查方案：

1. 先完成Keycloak客户端配置 #

• 登录Keycloak后台，进入drugdev realm
• 创建或编辑目标客户端：
  • 客户端类型设为机密（Confidential）
  • 开启服务账号（Service Accounts Enabled）
  • 有效重定向URI可留空（客户端凭证模式无需跳转）
  • 切换到「凭据」标签，复制客户端密钥（Client Secret）备用
  • 若API有角色权限要求，需给该客户端的服务账号分配对应角色

2. 完善OWIN Startup认证配置 #

现有配置缺失签名密钥动态获取逻辑，这是导致401的核心原因之一。修改后的完整配置如下：

using Microsoft.Owin;
using Owin;
using Microsoft.Owin.Security.Jwt;
using System.IdentityModel.Tokens.Jwt;
using System.Net.Http;

[assembly: OwinStartup(typeof(YourApiNamespace.Startup))]
namespace YourApiNamespace
{
    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            var realmUrl = "https://staging.com/auth/realms/drugdev";
            var clientId = "irt-api"; // 对应Keycloak客户端ID
            var clientSecret = "你的客户端密钥"; // 从Keycloak凭据标签复制

            app.UseJwtBearerAuthentication(new JwtBearerAuthenticationOptions
            {
                AuthenticationMode = AuthenticationMode.Active,
                Realm = realmUrl,
                TokenValidationParameters = new TokenValidationParameters
                {
                    ValidateIssuer = true,
                    ValidIssuer = realmUrl,
                    ValidateAudience = true,
                    ValidAudience = clientId, // 客户端凭证模式下，aud默认是客户端ID
                    ValidateIssuerSigningKey = true,
                    ValidateLifetime = true,
                    // 从Keycloak的JWKS端点动态获取签名公钥
                    IssuerSigningKeyResolver = (token, securityToken, kid, parameters) =>
                    {
                        var jwksEndpoint = $"{realmUrl}/protocol/openid-connect/certs";
                        using (var httpClient = new HttpClient())
                        {
                            var response = httpClient.GetAsync(jwksEndpoint).Result;
                            response.EnsureSuccessStatusCode();
                            var jwks = response.Content.ReadAsStringAsync().Result;
                            return new JsonWebKeySet(jwks).GetSigningKeys();
                        }
                    }
                }
            });

            // 确保认证中间件在Web API路由之前注册
            app.UseWebApi(GlobalConfiguration.Configuration);
        }
    }
}

3. 调用方获取Token并访问API #

程序间通信时，调用方需先向Keycloak申请Token，再携带Token访问受保护API：

using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;

public async Task<string> FetchKeycloakToken()
{
    var realmUrl = "https://staging.com/auth/realms/drugdev";
    var clientId = "irt-api";
    var clientSecret = "你的客户端密钥";
    var tokenEndpoint = $"{realmUrl}/protocol/openid-connect/token";

    using (var httpClient = new HttpClient())
    {
        var formData = new FormUrlEncodedContent(new Dictionary<string, string>
        {
            {"grant_type", "client_credentials"},
            {"client_id", clientId},
            {"client_secret", clientSecret}
        });

        var response = await httpClient.PostAsync(tokenEndpoint, formData);
        response.EnsureSuccessStatusCode();
        var tokenResult = await response.Content.ReadAsAsync<Dictionary<string, string>>();
        return tokenResult["access_token"];
    }
}

// 访问受保护API示例
public async Task AccessProtectedApi()
{
    var token = await FetchKeycloakToken();
    using (var httpClient = new HttpClient())
    {
        httpClient.DefaultRequestHeaders.Authorization = 
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
        var apiResponse = await httpClient.GetAsync("https://你的API地址/api/protected-endpoint");
        apiResponse.EnsureSuccessStatusCode();
        // 处理响应内容
    }
}

4. 401错误常见排查点 #

• 签名密钥不匹配：检查Keycloak的JWKS端点{realmUrl}/protocol/openid-connect/certs是否可访问，返回的密钥kid需与Token中的kid一致
• Audience/Issuer不匹配：验证Token的aud（客户端ID）和iss（realm地址）是否与配置中的ValidAudience、ValidIssuer完全一致
• Token过期：查看Token的exp声明，确认调用时Token未过期
• 中间件顺序错误：UseJwtBearerAuthentication必须在UseWebApi之前注册，否则认证逻辑不会生效
• 权限不足：若API使用了[Authorize(Roles = "xxx")]，需确认Keycloak客户端的服务账号已被授予对应角色

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