Spring Boot mTLS 中正确读取客户端 X.509 证书的完整指南_技术教程

在 spring boot 嵌入式 tomcat 中启用 mtls 后，需通过 `jakarta.servlet.request.x509certificate` 属性获取客户端证书，而非已废弃的 `javax.*` 包路径；否则将返回 null 并触发 npe。

Spring Boot 3.x（及 Spring Security 6.x）全面迁移到 Jakarta EE 9+ 命名空间，所有 Servlet API 类型（包括 HttpServletRequest 及其属性常量）均已从 javax.servlet.* 升级为 jakarta.servlet.*。这意味着：javax.servlet.request.X509Certificate 已失效，必须使用 jakarta.servlet.request.X509Certificate —— 否则 request.getAttribute(...) 将始终返回 null，导致 NullPointerException。

✅ 正确读取客户端证书的代码示例

修改 UserController.java 中的证书获取逻辑：

@Controller
public class UserController {

    @GetMapping("/user")
    public String user(HttpServletRequest request, Model model) {
        // ✅ 使用 Jakarta EE 9+ 标准属性名
        Object certAttr = request.getAttribute("jakarta.servlet.request.X509Certificate");

        if (certAttr instanceof X509Certificate[] certs && certs.length > 0) {
            X509Certificate clientCert = certs[0];
            model.addAttribute("subject", clientCert.getSubjectX500Principal().getName());
            model.addAttribute("issuer", clientCert.getIssuerX500Principal().getName());
            model.addAttribute("serial", clientCert.getSerialNumber().toString(16).toUpperCase());
            System.out.println("✅ Client certificate loaded: " + clientCert.getSubjectX500Principal());
        } else {
            System.err.println("❌ No client certificate found — verify mTLS handshake succeeded.");
            model.addAttribute("error", "Missing client certificate");
        }

        return "user";
    }
}

? 关键点：request.getAttribute("jakarta.servlet.request.X509Certificate") 返回的是 X509Certificate[] 数组（即使仅一个证书），且仅在 TLS 握手成功完成双向认证后由 Tomcat 自动注入。

⚙️ 配置注意事项（application.yml）

确保服务端 SSL 配置显式启用并强制客户端认证：

server:
  port: 8081
  ssl:
    enabled: true
    key-store: classpath:server.p12
    key-store-password: 123456
    key-store-type: PKCS12
    # ✅ 必须设为 'need'（非 'want'）以强制验证客户端证书
    client-auth: need
    enabled-protocols: TLSv1.2
    # ✅ trust-store 必须包含客户端证书的签发 CA（非仅 server.p12 自签名内容）
    trust-store: classpath:truststore.p12  # ← 推荐单独配置信任库
    trust-store-password: 123456
    trust-store-type: PKCS12

⚠️ 重要提醒：

trust-store 应包含用于验证客户端证书签名的CA 证书（如你 keytool -list 输出中的 bcc 或 torsho 条目），而非仅服务端私钥/证书。混用 server.p12 作 trust store 仅在自签名场景下临时可行，生产环境务必分离。
client-auth: need 是强制双向认证的关键；若设为 want，Tomcat 会接受无证书请求，此时该属性值为 null。
Spring Boot 不支持通过 -DclientAuth=true JVM 参数启用 mTLS —— 此参数对嵌入式 Tomcat 无效，一切以 application.yml 配置为准。

?️ 安全增强建议

启用 X.509 认证链校验（推荐替代手动解析）：
在 WebSecurityConfig 中启用 Spring Security 的 X.509 支持，自动完成证书解析、DN 映射与用户授权：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(authz -> authz
            .requestMatchers("/", "/home").permitAll()
            .anyRequest().authenticated()
        )
        .x509(x509 -> x509
            .subjectPrincipalRegex("CN=(.*?)(?:,|$)") // 提取 CN 作为用户名
        );
    return http.build();
}

此方式由 Spring Security 自动处理证书提取与 Authentication 构建，避免手动操作 HttpServletRequest 属性。

日志与调试：
启用 Tomcat SSL 调试日志，确认握手阶段是否收到客户端证书：
```
mvn spring-boot:run -Djavax.net.debug=ssl:handshake
```
观察日志中是否出现 *** CertificateRequest 和 *** Certificate 字段。

✅ 总结

问题根源	解决方案
使用过时的 javax.servlet.request.X509Certificate 属性名	✅ 替换为 jakarta.servlet.request.X509Certificate
trust-store 配置错误或缺失可信 CA	✅ 使用独立 truststore.p12，导入客户端证书的签发 CA
client-auth 未设为 need 或 SSL 配置未生效	✅ 确认 application.yml 中 client-auth: need 且无拼写错误
期望通过 JVM 参数启用 mTLS	❌ 移除 -DclientAuth=true，完全依赖配置文件