基于Keycloak与APISIX实现X.509客户端证书认证
2026-8-11
Apache APISIX + Keycloak X.509客户端证书认证核心解析
APISIX在X.509认证中的核心角色
- TLS层证书前置校验：作为流量入口网关，APISIX首先在TLS握手阶段接收客户端提交的X.509证书，完成基础合法性校验——包括证书有效期、链完整性、是否由信任CA签发等。这是拦截非法请求的第一道关卡，避免无效流量进入后续认证流程。
- 身份信息传递与认证触发：校验通过后，APISIX提取证书关键信息（如Subject DN、证书内容），通过自定义请求头（如
X-Client-Cert-DN）转发给Keycloak，触发Keycloak的X.509身份映射流程。 - 令牌转换与下游管控：Keycloak验证证书与用户的绑定关系后，会返回标准JWT令牌或用户身份信息。APISIX可借助现有OIDC插件逻辑，将令牌附加到下游请求中，或直接基于身份信息完成路由级权限校验；同时继续承担限流、熔断等统一流量管控职责。
- 认证流程适配衔接：APISIX作为中间层，打通了TLS层证书校验与Keycloak身份系统的衔接，无需下游微服务单独处理证书认证逻辑，保持微服务的无侵入性。
与访问令牌认证的核心差异
| 维度 | 访问令牌认证（OIDC） | X.509客户端证书认证 |
|---|---|---|
| 认证触发时机 | 客户端先从Keycloak获取令牌，请求时在应用层携带 | TLS握手阶段自动触发，无需额外令牌获取步骤 |
| 身份载体 | 加密JWT字符串，包含用户声明、权限等信息 | 基于PKI的数字证书，身份信息存储在证书字段中 |
| 校验链路 | APISIX调用Keycloak令牌 introspection 接口校验 | APISIX先做TLS层证书有效性校验，再由Keycloak完成用户绑定验证 |
| 安全性等级 | 应用层认证，令牌存在被截获复用风险 | TLS层端到端加密，私钥通常存储于安全硬件，泄露风险更低 |
| 用户/客户端体验 | 需要处理令牌过期、刷新逻辑 | 证书有效期内自动完成认证，无需额外操作 |
快速实现流程要点
- APISIX侧配置：开启mTLS，上传信任的CA根证书，强制客户端提交证书；通过插件（如
openid-connect或自定义Lua脚本）提取证书信息并转发至Keycloak。 - Keycloak侧配置：创建X.509认证器，设置证书与用户的映射规则（如用Subject DN匹配用户属性），启用对应认证流。
- 下游授权衔接：复用现有OIDC流程的授权逻辑，APISIX将Keycloak返回的令牌转发给下游，或直接通过RBAC插件完成路由权限控制。
内容的提问来源于stack exchange，提问作者ZeroDefect
相关产品推荐
相关产品推荐
