Keycloak mTLS认证返回401未授权问题排查求助

问题背景 #

在AWS EC2上部署Keycloak 25.0.4，通过SSL透传的ALB对外提供服务，使用mTLS（X509）认证客户端myclient_mTLS时，调用/token接口始终返回401，日志显示invalid_client_credentials。客户端证书和根CA已放置在Keycloak指定目录，curl命令已指定客户端证书、密钥和CA证书。

排查与解决步骤 #

1. 确认ALB是否正确传递客户端证书

如果ALB是终止SSL（而非纯TCP转发），Keycloak无法直接获取客户端证书，需配置ALB将证书通过头部传递：

• 登录AWS控制台，进入ALB监听器配置，启用客户端证书验证，关联包含rootCA的信任存储
• 在转发规则中添加X-SSL-CERT头部，将客户端证书的PEM格式内容传递给后端
• 修改Keycloak启动参数，添加：

  --x509certificate-header=X-SSL-CERT \
  --x509certificate-trust-proxies=* \
  

  确保Keycloak能识别ALB传递的证书头部

2. 修复Keycloak信任库配置

Keycloak 25+不会自动加载conf/truststores下的零散证书，需手动创建信任库并指定：

• 用keytool将rootCA导入PKCS12信任库：

  keytool -importcert -file /certificates/rootCA-crt.pem -alias rootCA -keystore /certificates/truststore.p12 -storetype PKCS12 -storepass your-truststore-password -noprompt
  

• 修改Keycloak启动命令，添加信任库参数（移除无效的/conf/truststores挂载）：

  --https-trust-store-file=/certificates/truststore.p12 \
  --https-trust-store-password=your-truststore-password \
  

3. 调整客户端与Realm认证配置

• Realm层面：进入master Realm → Authentication → Flows，确保Client X509流已启用，X509 Client Authenticator步骤正常执行
• 客户端层面：确认X509 Certificate Authenticator的身份源配置与客户端证书匹配：
  • 如果用Subject DN，需保证客户端证书的Subject DN与配置的Subject DN Pattern完全一致（例如CN=fredflinstone,OU=...）
  • 如果用SAN字段，需确保证书包含对应邮箱/URI/IP，且客户端配置中选择了正确的源
• 将Keycloak启动参数--https-client-auth=request改为--https-client-auth=required（仅当SSL在Keycloak终止时适用）

4. 验证curl命令的证书完整性

• 确保客户端证书文件包含完整链：将客户端证书+中间CA（若有）合并为一个PEM文件：

  cat fredflinstone-crt.pem intermediate-ca.pem > full-chain.pem
  

  然后curl使用--cert full-chain.pem
• 添加--trace-ascii debug.log到curl命令，查看证书是否被正确发送

5. 开启详细日志定位问题

修改Keycloak启动参数，添加调试日志：

--log-level=org.keycloak.authentication:debug

重启后重新请求，查看日志中客户端证书解析、验证的具体错误信息

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