Apereo CAS X.509 认证之证书提取:从反向代理请求头解析客户端证书

原创2026-09-24 14:47:211,851 阅读
文章标签:认证鉴权单点登录身份认证应用安全后端企业应用

Apereo CAS X.509 认证之证书提取:从反向代理请求头解析客户端证书

导读

在大多数生产部署中,CAS 服务器通常位于 Apache HTTPD、Nginx、HAProxy、BigIP F5 等反向代理之后,SSL/TLS 握手在代理层终止,Servlet 容器拿不到标准的 jakarta.servlet.request.X509Certificate 请求属性。此时,Apereo CAS 提供了一套"证书提取"机制:由代理把 base64 编码的客户端证书写入 HTTP 请求头,CAS 再按 Apache Tomcat SSLValve 兼容的解析逻辑把它还原为 X509Certificate 并用于认证。本文将围绕 X509-Authentication-Certificate-Extraction.md 展开,结合当前仓库源码讲清两个核心配置项(cas.authn.x509.extract-cert 与 cas.authn.x509.ssl-header)的语义、底层解析实现、安全前提以及 Webflow / REST 两种消费场景,帮助你在反向代理架构下正确开启 X.509 证书认证。

一、为什么需要"从请求头提取证书"

按 CAS 官方文档 X509-Authentication.md 的说明,X.509 组件本身要求:客户端证书必须作为名为 jakarta.servlet.request.X509Certificate 的请求属性暴露给 Servlet 容器,CAS 才能读取。这一要求在"Servlet 容器直接终止 SSL"或"使用 Apache/mod_jk"的架构下自然满足;但对于反向代理、负载均衡器做 SSL 终结的架构,证书并不会自动传递到后端应用。

证书提取机制正是为此设计的:由代理把证书以 base64 PEM 文本形式放入请求头,CAS 读取该请求头并按 Tomcat SSLValve 兼容的规则还原证书。这样,证书链上的"SSL 握手"与"应用层认证"被解耦,CAS 自身无需再参与 TLS 双向认证,只需要信任代理注入的请求头数据。

二、核心配置项与默认值

证书提取相关配置集中定义在配置模型类 X509Properties.java 中,对应两个属性:

配置项 对应字段 默认值 作用
cas.authn.x509.extract-cert extractCert false 是否从 HTTP 请求头中提取证书并启用基于请求头的 X.509 认证
cas.authn.x509.ssl-header sslHeaderName ssl_client_cert 存放 base64 编码证书的请求头名称

源码中的默认头名称常量为 DEFAULT_CERT_HEADER_NAME = "ssl_client_cert"(见 X509Properties.java),注释明确指出该头的内容格式必须与 Tomcat SSLValve 兼容。extractCert 字段的注释则强调:默认必须为 false,因为一旦启用,就必须确保 CAS 位于"不会让浏览器直接携带该请求头到达 CAS"的代理之后(安全前提详见下文)。

需要说明:cas.authn.x509.ssl-header 通常写作 cas.authn.x509.sslHeaderName 的 Spring Boot 松绑定形式,两种写法等价。

启用前提:必须位于受控代理之后

原文档特别强调两点安全前提,缺一不可:

  1. 用户无法绕过该代理直接访问 CAS——否则可伪造请求头;
  2. 代理必须保证该请求头绝不来源于浏览器——即代理必须覆写(overwrite)同名头,浏览器注入的任何同名头都不能透传。

只有在满足这两点的情况下才应把 extract-cert 设为 true。这一点在源码注释中反复出现,例如 X509Properties 的 extractCert 字段注释以及 RequestHeaderX509CertificateExtractor.java 中的 Note: Ensure that the headers are always set by httpd for all requests to prevent a client spoofing SSL information by sending fake headers.(确保 httpd 对所有请求都设置这些头,防止客户端通过发送伪造头来欺骗 SSL 信息)。

三、提取器的实现与 Tomcat SSLValve 兼容解析逻辑

3.1 提取器接口与 Bean 装配

X509CertificateExtractor 是获取证书的顶层抽象,定义为函数式接口,入参为 HttpServletRequest,返回 X509Certificate<a href="https://link.gitcode.com/i/3d0bcb80e80ec6694f3ab65ff566e125" target="_blank">](数组首元素即用户客户端证书),见 [X509CertificateExtractor.java。

提取器 Bean 由 CasX509CertificateExtractorAutoConfiguration.java 装配:读取 cas.authn.x509.sslHeaderName 配置,构造 RequestHeaderX509CertificateExtractor,且仅在 X509 feature 开启(@ConditionalOnFeatureEnabled(feature = CasFeatureModule.FeatureCatalog.X509))时生效。换言之,两个配置项中真正决定"从头提取"行为的开关是 extract-cert,而 ssl-header 决定从哪个头读取。

3.2 RequestHeaderX509CertificateExtractor:逐行解析

核心实现类 RequestHeaderX509CertificateExtractor.java 的类注释声明:本类改编自 Tomcat SSLValve 类并使用其解析逻辑,但并非运行在每个请求上的 Valve,而只处理 CAS 使用的主证书。其关键行为:

  • 空值与 (null) 处理:getCertFromHeader 中,头为空(blank)或值为 "(null)"(httpd mod_header 在 SSL 变量未填充时写入的字面值)都会被当作头不存在,返回 null,见 RequestHeaderX509CertificateExtractor.java。
  • 长度守卫:若头值长度不足以容纳 -----BEGIN CERTIFICATE----- 与 -----END CERTIFICATE----- 两个标记,直接判为无法解析,见 RequestHeaderX509CertificateExtractor.java。
  • 兼容两种代理换行行为:注释明确说明已知的反向代理行为——mod_header 会把 \n 转成空格,nginx 会把 \n 转成多个空格。因此 sanitizeCertificateBody 先把头值中 BEGIN/END 之间的内容取出,再把所有空格和制表符替换为换行符,然后重新拼接成标准 PEM 文本(见 RequestHeaderX509CertificateExtractor.java)。这也是该实现能与 Apache HTTPD、Nginx、Haproxy、BigIP F5 等各类代理协同工作的原因。
  • 证书还原:清洗后的 PEM 文本以 ISO_8859_1 编码写入 ByteArrayInputStream,交由 CertUtils.readCertificate(内部经 CertUtils.java 调用 cryptacular 的 CertUtil.readCertificate)解析为 X509Certificate,成功则返回单元素数组。
  • 失败即返回 null:任何解析异常只记录日志并返回 null,由调用方决定后续流程。

3.3 测试验证

仓库为提取器提供了专门的单元测试 RequestHeaderX509CertificateExtractorTests.java,覆盖了六类场景,可作为行为契约参考:

  • 头值为 "(null)" → 返回 null(对应 httpd 空 SSL 变量);
  • 头值为普通文本(header-value)→ 返回 null;
  • 头值仅为 -----BEGIN CERTIFICATE----- → 返回 null(长度不足);
  • 头值仅含 BEGIN+END 标记 → 返回 null;
  • 头值 BEGIN 与 END 之间只有一个空格 → 返回 null;
  • 头值中间夹着非法内容(\nwhatever\n)→ 返回 null。

四、配置示例:如何开启

4.1 标准 Webflow 场景

在 application.yml(或 cas.properties)中加入:

cas:
  authn:
    x509:
      extract-cert: true
      ssl-header: ssl_client_cert

同时按 X509-Authentication.md 的说明,在 WAR overlay 中加入模块依赖 cas-server-support-x509-webflow,否则 cas.authn.x509.* 配置不生效。

4.2 代理端:以 Apache httpd 为例

原文档与源码注释给出的 Apache httpd 配置如下(放在 httpd.conf 的 SSL 模块段内),作用是把客户端证书写入请求头:

<IfModule ssl_module>
RequestHeader set SSL_CLIENT_CERT "%{SSL_CLIENT_CERT}s"
</IfModule>
  • 若保持默认头名 ssl_client_cert,代理应写入名为 ssl_client_cert 的头;
  • 若改用其他头名(如 X-Client-Cert),则需同步修改 cas.authn.x509.ssl-header,且同样要求代理对所有请求强制覆写该头,杜绝浏览器伪造。

4.3 运行时的解析过程

开启后,一次请求的证书流转可归纳为:

  1. 浏览器与代理完成 TLS 双向认证(互送证书);
  2. 代理将 base64 PEM 证书写入指定请求头(可能经 mod_header/nginx 发生换行符变形);
  3. CAS 的 Webflow 动作读取请求头 → sanitizeCertificateBody 清洗 → CertUtils.readCertificate 还原为 X509Certificate;
  4. 证书被封装为 X509CertificateCredential 进入后续认证链(信任链校验、Principal 解析等)。

五、底层消费方:Webflow 与 REST 两条链路

5.1 Webflow:x509Check 动作的二选一

Webflow 侧由 CasX509AuthenticationWebflowAutoConfiguration.java 中的 x509Check 动作 Bean 决定采用哪种凭证构造策略:

X509CertificateCredentialsRequestHeaderAction 的执行顺序是:先尝试从请求属性取证书(非交互动作的父类逻辑),取不到时再调用 x509CertificateExtractor.extract(request) 从请求头提取,提取成功则封装为 X509CertificateCredential.java(该凭证内部持有证书数组,getId() 基于首张证书的 subjectDN 与序列号生成)。

5.2 REST API:请求头凭证工厂

除 Webflow 登录流程外,同一提取器也服务于 REST 认证接口。cas-server-support-rest-x509 模块中的 CasX509RestAutoConfiguration.java 将提取器注入 X509RestHttpRequestHeaderCredentialFactory.java:REST 请求若携带证书头,则提取并构造凭证;若请求头中没有证书,则回退到默认的凭证捕获行为。这使同一份 ssl-header 配置同时作用于浏览器登录与 REST 客户端。

六、安全边界与常见误区

关注点 结论 依据
默认开关 extract-cert 默认 false,避免误开启后信任浏览器可伪造的头 X509Properties.java
默认头名 ssl_client_cert,与 Tomcat SSLValve 生态约定一致 X509Properties.java
安全前提 代理必须不可绕过,且必须对所有请求覆写该请求头 RequestHeaderX509CertificateExtractor.java
空值语义 头缺失或为 (null) 视为无证书,不中断流程 提取器源码 getCertFromHeader
换行兼容 空格/制表符统一还原为换行符,兼容 httpd 与 nginx sanitizeCertificateBody

七、关联文档导航

X.509 认证在 CAS 文档体系中由一组文档协同描述,便于进一步阅读:

总结

在反向代理终结 SSL 的架构中,"从请求头提取证书"是 CAS 落地 X.509 认证的关键一环。只需正确设置 cas.authn.x509.extract-cert=true 与 cas.authn.x509.ssl-header(默认 ssl_client_cert),并保证代理不可绕过且覆写请求头,CAS 即可通过兼容 Tomcat SSLValve 的解析逻辑,把来自 Apache HTTPD、Nginx、Haproxy、BigIP F5 等代理的 base64 证书还原为可信凭证,同时服务于浏览器 Webflow 登录与 REST 认证两条链路。

登录后查看全文
cas