在 spring boot 嵌入式 tomcat 中启用 mtls 后，可通过 `request.getattribute("jakarta.servlet.request.x509certificate")` 安全获取客户端 x.509 证书数组，需注意 jakarta ee 9+ 命名空间迁移及 spring security x.509 配置协同。
Spring Boot 3.x（基于 Jakarta EE 9+）已全面迁移到 jakarta.* 命名空间，而不再使用 javax.*。这直接影响了 Servlet API 中标准属性的键名——包括客户端证书的传递标识符。原 javax.servlet.request.X509Certificate 在 Tomcat 10+（对应 Jakarta Servlet 6.0）中已被废弃，正确键名为：
X509Certificate[] certs = (X509Certificate[]) request.getAttribute("jakarta.servlet.request.X509Certificate");✅ 正确用法（Spring Boot 3.x + Tomcat 10.x） ❌ 错误用法（导致 NullPointerException）："javax.servlet.request.X509Certificate"
? 关键配置要点
1. application.yml 必须启用双向认证并正确配置信任库
server:
port: 8081
ssl:
enabled: true
key-store: "classpath:server.p12"
key-store-password: "123456"
key-store-type: PKCS12
client-auth: need # ← 强制要求客户端提供证书
enabled-protocols: TLSv1.2
trust-store: "classpath:server.p12" # ← 必须包含受信任的 CA 或客户端证书（如示例中的 bcc/torsho）
trust-store-password: "123456"
trust-store-type: PKCS12⚠️ 注意：trust-store 必须包含用于验证客户端证书签名的 CA 证书（即客户端证书的签发者），而非仅服务端私钥。若 server.p12 中仅有服务端密钥和自签名 CA，需确保客户端证书由其中任一 trustedCertEntry 签发。
2. Spring Security X.509 配置需与证书提取逻辑兼容
您的 WebSecurityConfig 已启用 .x509() 认证，这是正确的——它会自动解析 jakarta.servlet.request.X509Certificate 并尝试通过 UserDetailsService 查找匹配用户（例如基于证书主题 DN）。但请注意：
- 若未实现自定义 X509PrincipalExtractor，默认仅支持 CN= 作为用户名；
- X509AuthenticationFilter 的执行早于 Controller，因此证书属性一定存在（只要 TLS 握手成功且 client-auth: need 生效）；
- 不需要手动调用 filter.setContinueFilterChainOnUnsuccessfulAuthentication(false)，除非你希望认证失败时仍放行请求（不推荐用于 mTLS 场景）。
3. Controller 中安全读取证书的完整示例
@Controller
public class UserController {
@GetMapping("/user")
public String user(HttpServletRequest request, Model model) {
// ✅ 使用 Jakarta EE 9+ 标准属性名
X509Certificate[] certs = (X509Certificate[]) request.getAttribute("jakarta.servlet.request.X509Certificate");
if (certs == null || certs.length == 0) {
model.addAttribute("error", "No client certificate presented.");
return "error";
}
X509Certificate clientCert = certs[0];
try {
model.addAttribute("subject", clientCert.getSubjectX500Principal().getName());
model.addAttribute("issuer", clientCert.getIssuerX500Principal().getName());
model.addAttribute("serial", clientCert.getSerialNumber().toString(16));
model.addAttribute("validFrom", clientCert.getNotBefore());
} catch (Exception e) {
model.addAttribute("error", "Failed to parse certificate: " + e.getMessage());
}
return "user";
}
}? 常见错误排查清单
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| certs == null | 使用了 javax. 前缀；或 client-auth: want（非强制）；或客户端未发送证书 | ✅ 改为 jakarta.servlet.request.X509Certificate；确认 client-auth: need；用 curl --cert client.pem --key client.key https://localhost:8081/user 测试 |
| ClassCastException | 未导入 java.security.cert.X509Certificate | ✅ 添加 import java.security.cert.X509Certificate; |
| Bad Certificate 错误响应 | trust-store 不包含签发客户端证书的 CA | ✅ 用 keytool -list -v -keystore server.p12 检查是否含对应 trustedCertEntry；必要时将客户端 CA 导入 |
| Spring Security 拦截 /user 前未认证 | 路径未被 .x509() 覆盖，或 permitAll() 覆盖了该路径 | ✅ 确保 /user 不在 permitAll() 列表中；检查 authorizeHttpRequests 规则顺序 |
✅ 最终验证方式
使用 OpenSSL 或 curl 发起带证书的 HTTPS 请求：
curl -k --cert ./client.crt --key ./client.key https://localhost:8081/user
同时开启 Tomcat debug 日志（logging.level.org.apache.catalina=DEBUG）可观察 SSL handshake 是否成功协商证书。
掌握这一 Jakarta 命名空间变更，是 Spring Boot 3.x mTLS 开发的基石。务必同步更新所有 Servlet 属性访问、依赖坐标（如 jakarta.servlet-api）及文档引用，避免隐式兼容性陷阱。
