Kubernetes经Ingress配置Keycloak X509认证问题咨询

问题根因 #

从调试日志的核心报错[X509ClientCertificateAuthenticator:authenticate] x509 client certificate is not available for mutual SSL可以直接定位：Keycloak后端未接收到客户端提交的x509证书，因此x509认证分支执行失败，自动回退到用户名密码登录流程。

• NodePort模式可正常运行的原因：双向TLS握手直接在Keycloak Pod侧完成，服务可直接从TLS会话中读取客户端证书
• Ingress场景认证失败的核心原因：默认配置下Ingress控制器会在自身层终止TLS，既未开启双向TLS校验客户端证书，也不会将客户端证书信息透传给后端服务，Keycloak拿不到证书自然无法完成x509认证。

可直接参考的配置示例（以最常用的NGINX Ingress控制器为例） #

前置准备 #

将签发客户端证书的CA证书链（包含根CA、中间CA）创建为K8s Secret，供Ingress校验客户端证书使用：

kubectl create secret generic keycloak-client-ca --from-file=ca.crt=./your-client-ca-bundle.crt -n <keycloak所在命名空间>

Ingress资源配置 #

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: keycloak
  namespace: <keycloak所在命名空间>
  annotations:
    # 开启Ingress层客户端证书校验
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    # 引用提前创建的客户端CA证书Secret
    nginx.ingress.kubernetes.io/auth-tls-secret: "<keycloak所在命名空间>/keycloak-client-ca"
    # 证书链校验深度，根据实际证书链长度调整
    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "2"
    # 将校验通过的客户端证书通过请求头透传给后端Keycloak
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
    # TLS在Ingress层终止，后端用HTTP通信即可，端到端TLS场景可改为HTTPS
    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - keycloak.your-domain.com
    secretName: keycloak-server-tls # 存储Keycloak服务端证书的Secret
  rules:
  - host: keycloak.your-domain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: keycloak-service
            port:
              number: 8080

Keycloak侧配套配置 #

1. 启动参数调整（Quarkus版本Keycloak，即17+正式版），在Keycloak工作负载的环境变量中添加以下配置：
   • KC_PROXY: edge：标记当前为边缘代理模式，TLS在Ingress层终止
   • KC_HTTP_ENABLED: "true"：允许集群内HTTP访问
   • KC_HTTPS_CLIENT_AUTH: none：关闭Keycloak自身的直接客户端证书校验，改由Ingress层校验、透传证书
2. 控制台认证流配置：
   进入Keycloak管理后台，找到当前使用的x509-browser认证流，编辑X509/Validate Username Form执行器：
   • 将User Identity Source从默认的ssl_client_cert修改为ssl_client_cert_header
   • SSL Client Cert Header字段填写Ssl-Client-Cert（和NGINX Ingress透传的请求头保持一致）
   • 开启URL encode certificate in header选项，适配NGINX传递证书的URL编码格式
   • 其余证书字段匹配、用户映射逻辑保持和NodePort模式下的配置一致即可。

其他Ingress控制器适配说明 #

• Traefik Ingress：配置mTLS中间件，开启passClientCert参数，客户端证书默认通过X-Forwarded-Tls-Client-Cert请求头透传，Keycloak侧对应修改读取的请求头名称即可
• AWS ALB Ingress：在HTTPS监听器上开启双向TLS，配置对应信任CA，开启X-Forwarded-Client-Cert头透传
• 注意不要同时开启四层TLS透传和Keycloak侧直接证书校验，容易出现TLS握手截断问题。

常见排错点 #

• 证书透传失败优先检查Ingress注解拼写、Secret所在命名空间是否和注解配置一致
• 提前确认Ingress透传客户端证书的请求头名称、编码格式，必须和Keycloak x509认证器中的配置完全匹配
• 客户端CA Secret中必须包含完整的证书链，否则Ingress层会直接拒绝带无效证书的请求，不会转发到Keycloak

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