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

⚠️ 重要提醒：

歌者PPT

歌者PPT，AI 写 PPT 永久免费

下载

• 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 配置为准。

?️ 安全增强建议

1. 启用 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 属性。

2. 日志与调试：
   启用 Tomcat SSL 调试日志，确认握手阶段是否收到客户端证书：

   mvn spring-boot:run -Djavax.net.debug=ssl:handshake

   观察日志中是否出现 *** CertificateRequest 和 *** Certificate 字段。

✅ 总结

遵循以上步骤，即可在 Spring Boot 3.x + Tomcat 10+ 环境中稳定、安全地读取并验证客户端 X.509 证书。