Apereo CAS X.509 认证之证书提取:从反向代理请求头解析客户端证书
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 松绑定形式,两种写法等价。
启用前提:必须位于受控代理之后
原文档特别强调两点安全前提,缺一不可:
- 用户无法绕过该代理直接访问 CAS——否则可伪造请求头;
- 代理必须保证该请求头绝不来源于浏览器——即代理必须覆写(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 运行时的解析过程
开启后,一次请求的证书流转可归纳为:
- 浏览器与代理完成 TLS 双向认证(互送证书);
- 代理将 base64 PEM 证书写入指定请求头(可能经 mod_header/nginx 发生换行符变形);
- CAS 的 Webflow 动作读取请求头 →
sanitizeCertificateBody清洗 →CertUtils.readCertificate还原为X509Certificate; - 证书被封装为
X509CertificateCredential进入后续认证链(信任链校验、Principal 解析等)。
五、底层消费方:Webflow 与 REST 两条链路
5.1 Webflow:x509Check 动作的二选一
Webflow 侧由 CasX509AuthenticationWebflowAutoConfiguration.java 中的 x509Check 动作 Bean 决定采用哪种凭证构造策略:
- 当
cas.authn.x509.extract-cert=true时,构造 X509CertificateCredentialsRequestHeaderAction.java; - 否则退化为默认的 X509CertificateCredentialsNonInteractiveAction.java,它只从请求属性
jakarta.servlet.request.X509Certificate读取证书(即标准 Servlet 容器直连 / mod_jk 场景)。
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 文档体系中由一组文档协同描述,便于进一步阅读:
- X509-Authentication.md:X.509 认证总体架构、证书交换流程与全部
cas.authn.x509.*配置入口; - X509-Authentication-CRL.md:证书吊销(CRL)检查策略;
- X509-Authentication-Principal-Resolution.md:从证书中解析 Principal 的各类策略(SUBJECT_DN、RFC822_EMAIL、SERIAL_NO 等);
- X509-Authentication-WebServer-Configuration.md:Servlet 容器/Web 服务器侧 TLS 双向认证配置。
总结
在反向代理终结 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 认证两条链路。