Keycloak KubeAPI认证失败求助：Python Kubernetes Client授权异常

我来分享几个实用的排查方向，都是我之前处理类似OIDC认证问题时踩过的坑、总结的经验：

• 对比令牌内容，找出核心差异
  先把kube login生成的令牌和Keycloak返回的令牌都解析出来，仔细对比Claims字段的区别：

  • 用jwt decode工具（比如echo <token> | base64 -d | jq，或者本地的JWT解析工具）查看两个令牌的iss（颁发者）字段，必须和K8s API服务器配置的oidc-issuer-url完全一致——包括是否带结尾斜杠这类细节，这是非常常见的出错点。
  • 检查sub（主体）、username或者email字段，确认K8s的RBAC规则里有没有对应用户的权限配置。
  • 如果用组权限做认证，看看Keycloak令牌里的groups字段是否包含K8s中已授权的组名。
  • 确认exp（过期时间）字段，确保Keycloak令牌没有过期失效。

• 验证Keycloak令牌的签名有效性
  K8s API服务器需要信任Keycloak的签名，这一步可以直接用curl做简单测试：

  curl -H "Authorization: Bearer <你的Keycloak令牌>" https://<K8s API地址>/api/v1/namespaces
  

  看返回的具体错误：如果是签名无效，那要检查K8s集群的OIDC配置里oidc-ca-file是否包含Keycloak的CA证书（自签证书场景下），以及oidc-issuer-url是否正确；如果是权限不足，再往下排查RBAC配置。

• 检查K8s RBAC绑定是否匹配
  确认Keycloak返回的用户/组在K8s中有对应的权限绑定：

  • 如果是用户认证，用命令检查是否有匹配的RoleBinding/ClusterRoleBinding：

    kubectl get rolebindings -A -o json | jq '.items[] | select(.subjects[]?.name=="<Keycloak返回的用户名>")'
    

  • 如果是组认证，要确保绑定的subjects里kind: Group的名称和Keycloak令牌里的groups字段完全一致。

• 检查Keycloak客户端配置
  确认Keycloak中对应K8s的客户端配置正确：

  • 客户端的audience要和K8s API服务器配置的oidc-client-id一致，令牌的aud字段必须包含这个client-id。
  • 客户端需要开启必要的Scope，比如openid（必填）、email、profile等，或者直接开启Full Scope Allowed。
  • 检查客户端的Access Type是否设置为confidential或者public（根据你的K8s OIDC配置场景选择）。

• 确认Python Kubernetes Client的配置
  确保用Keycloak令牌时，Client的配置没有遗漏关键参数：
  正确的手动配置应该类似这样：

  from kubernetes import client, config
  
  # 手动构建配置，不依赖kube-config
  cfg = client.Configuration()
  cfg.host = "https://<K8s API地址>"
  cfg.verify_ssl = True  # 生产环境建议开启，同时指定ca_cert路径
  cfg.ca_cert = "/path/to/k8s-ca.pem"
  cfg.api_key = {"authorization": f"Bearer {keycloak_token}"}
  
  api_client = client.ApiClient(cfg)
  core_v1 = client.CoreV1Api(api_client)
  # 测试调用
  print(core_v1.list_namespace())
  

  对比用kube-config时的配置，看是否有CA证书、API地址等参数的差异。

• 查看K8s API服务器日志找细节
  直接看kube-apiserver的日志，能得到最准确的错误原因：

  kubectl logs -n kube-system <kube-apiserver-pod-name> | grep -i "oidc\|token\|unauthorized\|forbidden"
  

  日志里会明确告诉你是令牌验证失败、用户不存在，还是权限不足，这是定位问题最快的方式之一。

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