跳到主要内容
安装配置教程

mTLS 配置教程:Envoy 1.30 与 Spring Boot 3.2 双向认证落地与排错

mtls 配置教程 — mTLS 配置教程:Envoy 1.30 与 Spring Boot 3.2 双向认证落地与排错
核心结论

mTLS 配置教程的核心是让服务端在 TLS 握手时主动发送 CertificateRequest 并校验客户端证书;Envoy 1.30 用 require_client_certificate: true,Spring Boot 3.2 用 server.ssl.client-auth=need,二者都需把 CA 证书放入 validation_context 或 truststore。 证书扩展要写对:客户端证书必须含 extendedKeyUsage=clientAuth,服务端证书含 serverAuth;SAN 建议用 URI:spiffe://acme.internal/payment 便于服务身份校验。 用 openssl s_client -connect host:8443 -cert client.crt -key client.key -CAfile ca.crt -tls1_3 验证,成功输出 Verification: OK 与 Protocol version: TLSv1.3;不带证书应看到 alert certificate required(TLS 1.3 alert 116)。 Envoy 侧看 /stats 中 listener.*.ssl.handshake 与 ssl.fail_verify_no_cert;Spring Boot 侧看 javax.net.ssl.SSLHandshakeException: Empty client certificate chain。 客户端证书有效期建议 90 天,RSA 3072 或 ECDSA P-256;轮换用双证书并行 7 天,避免一次性替换导致 5xx。

mTLS 配置教程先讲根因:单向 TLS 到底缺了哪一步,握手为什么会失败?

很多人第一次配 mTLS 会卡在同一个地方:证书都装好了,客户端一连就断。根因往往不是“没配证书”,而是单向 TLS 的握手里,服务端从来不发出那一条 CertificateRequest。据 RFC 8446 §4.4.2,TLS 1.3 中只有服务端显式请求客户端证书时,才会在 EncryptedExtensions 之后发送 CertificateRequest;客户端收到后才回送 Certificate 与 CertificateVerify。少了这一条消息,客户端证书永远不会出现在链路上。

握手消息(TLS 1.3) 单向 TLS mTLS
ClientHello / ServerHello 发送 发送
CertificateRequest 不发送 服务端发送
Certificate(服务端) 发送 发送
Certificate(客户端) 无 回送完整链
CertificateVerify(客户端) 无 用私钥签名握手摘要
Finished 客户端直接发 双方互验通过后发

两个框架把这个“开关”默认关掉了:Envoy 1.30 的 DownstreamTlsContext.require_client_certificate 默认 false,Spring Boot 3.2 的 server.ssl.client-auth 默认 none。据 Envoy v3 API 文档,只有当它或 validation_context 存在时,下游监听器才会向客户端索要证书。

# Envoy 1.30 最小 mTLS 下游配置(片段,挂在 filter_chains[].transport_socket)
transport_socket:
  name: envoy.transport_sockets.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
    require_client_certificate: true      # 默认 false;不写这一行服务端不会发 CertificateRequest
    common_tls_context:
      tls_params:
        tls_minimum_protocol_version: TLSv1_3
      tls_certificates:
      - certificate_chain: { filename: /etc/envoy/server.crt }
        private_key:       { filename: /etc/envoy/server.key }
      validation_context:
        trusted_ca: { filename: /etc/envoy/clients-ca-bundle.crt }  # 必须是完整 CA 链,只有 leaf 会校验失败
        match_typed_subject_alt_names:
        - san_type: DNS
          matcher: { exact: "svc-a.internal" }   # SAN 不匹配同样握手失败
# Spring Boot 3.2 application.yml
server:
  ssl:
    enabled: true
    client-auth: need        # 默认 none;need=强制,want=请求但不强制(适合灰度期)
    key-store: classpath:server.p12
    key-store-password: changeit
    key-store-type: PKCS12
    trust-store: classpath:clients-truststore.p12   # 用于校验客户端证书链,缺省则校验必然失败
    trust-store-password: changeit
    trust-store-type: PKCS12
    enabled-protocols: TLSv1.3

排错第一步是分清方向。客户端报 tlsv13 alert certificate required,说明服务端要了证书、客户端没发;服务端报 Empty client certificate chain,则是客户端发了空链,或 truststore 没加载成功。用下面两条命令即可复现并定位:

# 不带客户端证书:预期复现 certificate required
openssl s_client -connect api.example.com:8443 -servername api.example.com -tls1_3 </dev/null

# 带客户端证书与 CA 链:预期握手成功
openssl s_client -connect api.example.com:8443 -cert client.crt -key client.key 
  -CAfile ca-bundle.crt -tls1_3 </dev/null

# 检查 EKU:必须出现 TLS Web Client Authentication
openssl x509 -in client.crt -noout -text | grep -A1 "Extended Key Usage"

第二类高频坑是证书内容本身:extendedKeyUsage 缺 clientAuth(据 CA/Browser Forum 基线要求,服务端证书通常只签 serverAuth)、SAN 与服务端校验规则不一致、以及客户端只发 leaf 而未带中间 CA。mTLS 只解决传输层“你是谁”,不解决“你能做什么”——服务间调用仍应在证书身份之上叠加 RBAC 或 OPA 策略。它最适合 API 网关到后端、Kubernetes 集群外服务互调、IoT 设备接入和零信任内网;面向普通浏览器访客的站点通常不必强制客户端证书,否则用户体验与证书分发成本都会失控。

mTLS 配置教程的证书设计:根 CA、服务端证书、客户端证书各要哪些扩展?

证书设计决定 mTLS 能不能跑通。先把三张证书的扩展项定死,后面 Envoy 1.30 与 Spring Boot 3.2 的握手才不会在半夜报错。

根 CA:OpenSSL 3.0.13 生成,有效期 3650 天,私钥离线

# 1) 生成 CA 私钥(ECDSA P-256;若需兼容旧客户端可换 RSA 3072)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out ca.key
chmod 600 ca.key                 # 仅属主可读,私钥永不进 Git/镜像

# 2) 自签根证书:CA:TRUE 与 keyCertSign/cRLSign 必须标 critical
openssl req -x509 -new -key ca.key -sha256 -days 3650 -out ca.crt 
  -subj "/C=CN/O=Acme/CN=Acme Internal Root CA" 
  -addext "basicConstraints=critical,CA:TRUE" 
  -addext "keyUsage=critical,keyCertSign,cRLSign" 
  -addext "subjectKeyIdentifier=hash"
openssl x509 -in ca.crt -noout -text | grep -A2 "Basic Constraints"
# 输出应含:CA:TRUE

据 OpenSSL 3.x 文档,-addext 自 1.1.1 起可用,3.0.13 行为一致;critical 缺失会让部分校验器忽略该扩展,等于把 CA 约束废掉。

服务端证书:必须有 serverAuth 与 SAN

# 关键配置片段 server.ext(其余字段略)
basicConstraints=CA:FALSE
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
subjectAltName=DNS:payment.internal,IP:10.20.30.40
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer

openssl req -new -key server.key -out server.csr -subj "/CN=payment.internal"
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial 
  -days 90 -sha256 -extfile server.ext -out server.crt

SAN 缺失是最高频故障。JDK 17 的 sun.security.util.HostnameChecker 会直接抛 SSLHandshakeException: No subject alternative names present,因为自 JDK 7 起 CN 已不再参与主机名校验(RFC 6125 第 6.4.4 节)。域名和实际访问用的 IP 都要写进 SAN,Envoy 上游用 IP 直连时同样校验 IP 条目。

客户端证书:clientAuth,授权看 SAN URI

# client.ext
basicConstraints=CA:FALSE
keyUsage=critical,digitalSignature
extendedKeyUsage=clientAuth
subjectAltName=URI:spiffe://acme.internal/payment,email:ops@acme.internal
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer

CN 放服务名只是给人看;据 SPIFFE 规范,身份应以 URI SAN 表达,Spring Security 里用 X509Certificate.getSubjectAlternativeNames() 取类型 6(URI)做鉴权,比解析 CN 字符串可靠得多。

证书链与信任库的摆放

# 服务端链文件:leaf → intermediate,根 CA 绝不放入
cat server.crt intermediate.crt > server-chain.crt
# 客户端校验只带根 CA
curl --cert client.crt --key client.key --cacert ca.crt https://payment.internal:8443/health
# Spring Boot 3.2 truststore:根 CA + 中间 CA
keytool -importcert -alias root -file ca.crt -keystore trust.p12 -storetype PKCS12
keytool -importcert -alias inter -file intermediate.crt -keystore trust.p12 -storetype PKCS12

把根 CA 塞进服务端链会多发一个字节包并触发部分客户端的链构建告警,Envoy 的 tls_context(1.30 中为 DownstreamTlsContext)只应加载 leaf+intermediate。

算法与有效期怎么选

维度 RSA 3072 ECDSA P-256
安全强度 约 128 位 约 128 位
握手字节数 较大(证书约 1.2 KB) 更小(证书约 0.6 KB)
TLS 1.3 套件 tls13_aes_128_gcm_sha256 等 同上,签名算法为 ecdsa_secp256r1_sha256
兼容风险 几乎无 需确认 JDK 17 与 Envoy 1.30 均启用对应套件
有效期建议 服务端/客户端 90 天,CA 3650 天 同左

据 Let’s Encrypt 的实践,90 天短周期配合 7 天并行轮换窗口,比维护 CRL/OCSP 更易落地;Envoy 1.30 的 certificate_provider 支持热加载,Spring Boot 3.2 侧用 server.ssl.* 重启或 Actuator 刷新即可完成并行期切换。

mTLS 配置教程完整实操步骤:6 步从生成证书到 Envoy 与 Spring Boot 生效

下面这套 6 步流程假设你已经有一台能同时跑 Envoy 与 Spring Boot 的 Linux 主机,证书全部自签、内部使用。关键原则:私钥与 CA 私钥永不落到应用目录,因此第 1 步先分目录,后面每一步都按”产物落在哪个目录”推进。

步骤 1:先对齐版本,再建目录。版本不一致是后续 90% 报错的根因——比如 OpenSSL 3.0 之前不支持 -addext,Envoy 1.28 之前 DownstreamTlsContext 的字段路径有差异。先用表格核对,全部命中再继续。

组件 本节基准版本 校验命令 默认值 / 取值范围说明
OpenSSL 3.0.13(2024-01-30 发布) openssl version 3.0 起 -addext 与 genpkey 为标配
Envoy 1.30.1 envoy --version 默认 TLS 最低版本 TLSv1.2
JDK 17.0.11(LTS) java -version Spring Boot 3.2 要求 JDK 17+
Spring Boot 3.2.x ./mvnw -v server.ssl.client-auth 默认 none
# 分目录,杜绝私钥混放;后续命令均以 /etc/mtls 为根
sudo mkdir -p /etc/mtls/{ca,server,client}
sudo chmod 700 /etc/mtls/ca          # CA 私钥目录仅 root 可进
cd /etc/mtls

步骤 2:生成根 CA。RSA 3072 位是 NIST SP 800-57 建议的、在 2030 年前足够安全的最小档位。注意 basicConstraints 与 keyUsage 必须带 critical,这是 RFC 5280 第 4.2.1.9 节的硬性要求,缺了会让部分 TLS 实现对 CA 证书”视而不见”。

cd /etc/mtls/ca
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out ca.key
openssl req -x509 -new -key ca.key -sha256 -days 3650 
  -subj "/CN=Acme Internal Root CA/O=Acme" 
  -addext "basicConstraints=critical,CA:TRUE" 
  -addext "keyUsage=critical,keyCertSign,cRLSign" 
  -out ca.crt
openssl x509 -in ca.crt -noout -text | grep -A1 "Basic Constraints"   # 应看到 CA:TRUE

步骤 3:签发服务端证书(90 天)。90 天与 Let’s Encrypt 的证书有效期策略一致,便于把”续期”变成肌肉记忆。据 Let’s Encrypt 文档,缩短有效期是行业方向,内部 CA 也建议照此节奏。SAN 必须写,因为 OpenSSL 3.x 与 Java 17 都已忽略 CN 做主机名校验。

cd /etc/mtls/server
cat > server-ext.cnf <<'EOF'
basicConstraints = critical,CA:FALSE
keyUsage         = critical,digitalSignature,keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName   = DNS:payment.internal
EOF

openssl req -new -newkey rsa:3072 -nodes -keyout server.key -out server.csr 
  -subj "/CN=payment.internal/O=Acme"
openssl x509 -req -in server.csr -CA ../ca/ca.crt -CAkey ../ca/ca.key 
  -CAcreateserial -out server.crt -days 90 -sha256 -extfile server-ext.cnf

步骤 4:签发客户端证书。EKU 必须是 clientAuth,否则 Envoy 会以 verify error:num=26:unsupported certificate purpose 拒掉握手。SAN 用 SPIFFE URI 是云原生主流做法(SPIFFE 规范 v1.0),为后续接入 SPIRE 留出扩展位。

cd /etc/mtls/client
cat > client-ext.cnf <<'EOF'
basicConstraints = critical,CA:FALSE
keyUsage         = critical,digitalSignature
extendedKeyUsage = clientAuth
subjectAltName   = URI:spiffe://acme.internal/payment
EOF

openssl req -new -newkey rsa:3072 -nodes -keyout client.key -out client.csr 
  -subj "/CN=payment-client/O=Acme"
openssl x509 -req -in client.csr -CA ../ca/ca.crt -CAkey ../ca/ca.key 
  -CAcreateserial -out client.crt -days 90 -sha256 -extfile client-ext.cnf
chmod 600 client.key          # 私钥仅属主可读,避免被同机进程窃取

步骤 5:导入 truststore 并配置 Spring Boot 3.2。Java 不认 PEM 里的 CA 列表,必须转成 PKCS12。这一步就是让 mtls 配置教程里的”信任锚”真正落到 JVM 里。

cd /etc/mtls/ca
keytool -importcert -alias acme-ca -file ca.crt 
  -keystore truststore.p12 -storetype PKCS12 -storepass changeit -noprompt
# 产物放到 src/main/resources/truststore.p12
# application.yml —— Spring Boot 3.2
server:
  port: 8443
  ssl:
    enabled: true
    client-auth: need                     # none | want | need;need=强制双向
    key-store: classpath:server.p12
    key-store-password: changeit
    key-store-type: PKCS12
    trust-store: classpath:truststore.p12
    trust-store-password: changeit
    trust-store-type: PKCS12
    enabled-protocols: TLSv1.3,TLSv1.2

步骤 6:配置 Envoy 1.30 并做正反向验证。核心是 require_client_certificate: true 与 validation_context.trusted_ca 同时存在——只写前者不写后者,Envoy 会拒绝启动并报 require_client_certificate set but no validation context configured。

# /etc/envoy/envoy.yaml(节选 filter_chains 部分)
transport_socket:
  name: envoy.transport_sockets.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
    require_client_certificate: true
    common_tls_context:
      tls_params:
        tls_minimum_protocol_version: TLSv1_2
      tls_certificates:
      - certificate_chain: { filename: /etc/envoy/server.crt }
        private_key:       { filename: /etc/envoy/server.key }
      validation_context:
        trusted_ca: { filename: /etc/envoy/ca.crt }
# 启动前静态校验,输出 configuration '/etc/envoy/envoy.yaml' OK 才继续
envoy --mode validate -c /etc/envoy/envoy.yaml

# 反向验证:不带客户端证书,必须被拒
openssl s_client -connect 127.0.0.1:8443 -CAfile /etc/mtls/ca/ca.crt -servername payment.internal
# 预期报错(TLS 1.3):tlsv13 alert certificate required

# 正向验证:带客户端证书,握手成功且 Verify return code: 0 (ok)
openssl s_client -connect 127.0.0.1:8443 
  -cert /etc/mtls/client/client.crt -key /etc/mtls/client/client.key 
  -CAfile /etc/mtls/ca/ca.crt -servername payment.internal -brief

排错提示:若 Spring Boot 侧日志出现 PKIX path building failed,八成是 trust-store 指向的 p12 没包含 CA,或 trust-store-password 与导入时不一致;若 Envoy 侧出现 verify error:num=20:unable to get local issuer certificate,检查 trusted_ca.filename 是否指向完整链而非中间 CA 单独文件。

mTLS 配置教程配置示例:Envoy 1.30 与 Spring Boot 3.2 的关键参数怎么写?

先把两端的“信任锚”对齐,再谈参数。Envoy 1.30 的下游 TLS 配置写在 DownstreamTlsContext 里(字段定义见 Envoy v1.30 API reference 的 extensions.transport_sockets.tls.v3):

transport_socket:
  name: envoy.transport_sockets.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
    require_client_certificate: true          # 关键:不写这行时 Envoy 只“请求”证书,客户端可空手而来,等价 want
    common_tls_context:
      tls_certificates:
      - certificate_chain: { filename: "/etc/envoy/server.crt" }   # 必须是「叶证书 + 中间 CA」全链
        private_key: { filename: "/etc/envoy/server.key" }
      validation_context:
        trusted_ca: { filename: "/etc/envoy/ca.crt" }              # 签发客户端证书的 CA
        match_typed_subject_alt_names:                             # 链校验之外的 SAN 白名单
        - san_type: URI
          matcher: { prefix: "spiffe://acme.internal/" }           # 遵循 SPIFFE ID 规范

这段 match_typed_subject_alt_names 是 mTLS 配置教程里最容易被忽略的一行:trusted_ca 只证明“证书由我方 CA 签发”,不区分是哪个客户端;加上 URI 前缀匹配后,Envoy 会在握手阶段直接拒绝 SAN 不匹配的证书,等价于把授权前移到 TLS 层。不写 tls_params 时 Envoy 默认允许 TLS 1.2 与 1.3(RFC 8446),需要收紧可加 tls_maximum_protocol_version: TLSv1_3。

Spring Boot 3.2 侧对应配置(client-auth 取值 none|want|need,默认 none):

server:
  port: 8443
  http2:
    enabled: true                 # 默认 false,不开则 curl 拿到 HTTP/1.1 200
  ssl:
    enabled: true
    key-store: classpath:server.p12
    key-store-password: ${KEYSTORE_PASS}
    key-store-type: PKCS12
    key-alias: server             # 必须与 pkcs12 -name 完全一致
    client-auth: need             # need = 强制,want = 请求但可缺省
    trust-store: classpath:truststore.p12
    trust-store-password: ${TRUSTSTORE_PASS}
    trust-store-type: PKCS12
    enabled-protocols: TLSv1.3,TLSv1.2   # Spring Boot 3.x 默认即此值
语义 Envoy 1.30 字段 Spring Boot 3.2 属性 差异要点
强制客户端证书 require_client_certificate: true server.ssl.client-auth: need Envoy 默认 false,Boot 默认 none,两端都必须显式打开
信任锚 validation_context.trusted_ca trust-store Envoy 读 PEM 文件,Boot 读 PKCS12/JKS
身份白名单 match_typed_subject_alt_names 无内置等价项 Boot 只做链校验,SAN 校验需自定义 X509AuthenticationFilter
协议版本 tls_params.tls_maximum_protocol_version enabled-protocols 两者默认均为 1.2/1.3

PEM 转 PKCS12 与 key-alias 的对应关系,是本节 mTLS 配置教程里报错率最高的一步:

openssl pkcs12 -export 
  -out server.p12 
  -inkey server.key -in server.crt -certfile ca.crt 
  -name server                 # 这个值必须等于 application.yml 的 key-alias
  -passout pass:${KEYSTORE_PASS}

若 -name 写成 mycert 而 yml 里仍是 key-alias: server,启动会抛 java.io.IOException: Alias name [server] does not identify a key entry。据 Spring Boot 3.2 Reference 的 “SSL” 章节,3.1 起也支持直接挂 PEM(server.ssl.certificate / certificate-private-key / trust-certificate),可绕开 keystore 转换。

正向验证两条命令,先看 curl:

curl -v --cert client.crt --key client.key --cacert ca.crt 
  https://payment.internal:8443/healthz
# 期望:*  SSL certificate verify ok.
#       < HTTP/2 200
openssl s_client -connect payment.internal:8443 -servername payment.internal 
  -cert client.crt -key client.key -CAfile ca.crt -tls1_3 -brief
# 期望:Verification: OK
#       Protocol version: TLSv1.3
#       Cipher: TLS_AES_256_GCM_SHA384

Envoy 改完静态证书别直接重启,先校验再优雅退出:

envoy --mode validate -c /etc/envoy/envoy.yaml   # 只校验不启动
envoy -c /etc/envoy/envoy.yaml --drain-time-s 30 --parent-shutdown-time-s 60
# drain-time-s 期间停止接受新连接,parent-shutdown-time-s 为进程总超时

恢复判定看统计项 listener.<address>.ssl.handshake(如 listener.0.0.0.0_8443.ssl.handshake)是否重新增长;若 ssl.fail_verify_error 上升,问题在客户端证书链,而非监听器本身。

mTLS 配置教程选型对比:Envoy、Spring Boot、HAProxy、Istio 怎么选?

如果你在搜索引擎里翻 mTLS 配置教程,最容易踩的坑不是”证书怎么签”,而是”选了不匹配的组件”:Envoy 能做 SPIFFE 级别的 SAN 精确匹配,Spring Boot 3.2 的 client-auth=need 却只校验到 CA 链为止,HAProxy 要在 ACL 里手写 DN 匹配,Istio 则把整套身份体系收进控制面。先把四者的能力边界摊开看:

方案 适用场景 开启客户端证书校验的参数 SAN/SPIFFE 校验 证书热更新
Envoy 1.30.1 边缘网关、服务入口、多租户前置代理 require_client_certificate: true + validation_context.trusted_ca 支持 match_typed_subject_alt_names(按 URI/DNS 精确匹配) SDS 热更新;静态 bootstrap 配置需重启进程
Spring Boot 3.2.5 Java 单体、内部服务、快速验证 server.ssl.client-auth=need + server.ssl.trust-store 无内置 SAN 策略,需自定义 X509TrustManager 或 Servlet 过滤器 默认需重启;SSL Bundle 可配合 Actuator 触发重载
HAProxy 2.9.7 TCP/HTTP 入口、传统 IDC 架构 bind :8443 ssl crt server.pem ca-file ca.crt verify required 需 ACL 匹配 ssl_c_s_dn / ssl_c_used reload -sf 平滑生效,连接不中断
Istio 1.22 Kubernetes 服务网格内东西向流量 PeerAuthentication 的 mode: STRICT 原生 SPIFFE 身份 spiffe://<trust-domain>/ns/<ns>/sa/<sa> 自动轮换,istiod 默认 defaultCertTTL 约 24 小时

Envoy 的关键差异点在于”能校验到身份层”。据 Envoy 官方文档,CertificateValidationContext 的 match_typed_subject_alt_names 支持 exact/prefix/suffix/contains 四种匹配方式,这是 HAProxy 2.9 的 ssl_c_s_dn(仅 DN 字段)做不到的。最小片段如下,注意 require_client_certificate 默认为 false,漏写就等于只做了单向 TLS:

# envoy.yaml 片段(Envoy 1.30.1,DownstreamTlsContext)
transport_socket:
  name: envoy.transport_sockets.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
    require_client_certificate: true          # 默认 false,必须显式开启
    common_tls_context:
      tls_certificates:
        - certificate_chain: { filename: /etc/certs/server.crt }
          private_key: { filename: /etc/certs/server.key }
      validation_context:
        trusted_ca: { filename: /etc/certs/ca.crt }
        match_typed_subject_alt_names:
          - san_type: URI
            matcher: { exact: "spiffe://cluster.local/ns/payment/sa/gateway" }

Spring Boot 3.2.5 的门槛最低但语义最弱。据 Spring Boot 官方文档,server.ssl.client-auth 只有 none/want/need 三值,need 表示握手阶段强制要求客户端证书,但校验终点是 trust-store 里的 CA 链——链对上就放行,不区分是哪个客户端。客户端没带证书时,服务端日志里会出现典型的 javax.net.ssl.SSLHandshakeException: PKIX path building failed(对端不受信)或 Received fatal alert: bad_certificate。

# application.yml(Spring Boot 3.2.5)
server:
  port: 8443
  ssl:
    enabled: true
    client-auth: need                 # none | want | need,默认 none
    key-store: classpath:server.p12
    key-store-password: changeit
    key-store-type: PKCS12
    trust-store: classpath:ca.p12     # 用于校验客户端证书的 CA
    trust-store-password: changeit
    trust-store-type: PKCS12

HAProxy 2.9.7 胜在运维友好。verify required 与 ca-file 绑定在 bind 行上,改证书只需 haproxy -c -f haproxy.cfg 校验后执行 reload -sf $(pidof haproxy),老进程在处理完存量连接后退出,不会掐断长连接。但要做身份白名单,就得在 http-request 里写 ACL,且只认 DN 字段:

# haproxy.cfg(HAProxy 2.9.7)
frontend mtls_in
  bind :8443 ssl crt /etc/haproxy/server.pem ca-file /etc/haproxy/ca.crt verify required
  acl is_partner ssl_c_s_dn(OU) -i partner
  http-request deny unless is_partner        # 无匹配 OU 直接 403
  default_backend app

# 平滑生效(不断开存量连接)
# haproxy -c -f /etc/haproxy/haproxy.cfg && haproxy -f /etc/haproxy/haproxy.cfg -sf $(pidof haproxy)

Istio 1.22 把 mTLS 变成”默认态”而非”配置项”。据 Istio 官方文档,PeerAuthentication 的 STRICT 模式拒绝一切明文流量,证书由 istiod 通过 SDS 下发并自动轮换,你不需要持有任何私钥文件。代价是它只解决网格内部的东西向流量,南北向仍需 Gateway 承接——这也是”Envoy + Istio”常被组合使用的原因:同一套 xDS/SDS 心智模型,边缘和网格用同一份 validation_context 语义。

# peer-authentication.yaml(Istio 1.22,命名空间级 STRICT)
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: payment
spec:
  mtls:
    mode: STRICT      # PERMISSIVE | STRICT | DISABLE,命名空间默认 PERMISSIVE
  portLevelMtls:
    "8080":
      mode: DISABLE   # 例外端口(如健康检查)单独放行

选型可以用一条判据收口:需要按客户端身份(而不只是”是否受信”)做授权时,Envoy 或 Istio 是唯一省事的选择;纯 Java 栈且客户端集合固定、规模在十几个以内,Spring Boot 3.2.5 的 client-auth=need 配合过滤器足够;已有 HAProxy 承载核心入口、不想引入数据平面新组件,就用 verify required + DN ACL,热更新成本最低。无论选哪个,CA 的 basicConstraints=CA:TRUE 与证书的 extendedKeyUsage=clientAuth 都必须正确——这是 RFC 5280 的硬性要求,也是绝大多数”握手失败”的真正根因,与代理软件无关。

mTLS 配置教程常见错误与排查:certificate required、unknown ca、空证书链怎么定位?

先把报错按”谁发的 alert”分三类:客户端发的(unknown ca、bad certificate)、服务端发的(certificate required、empty client certificate chain)、代理层转译的(Envoy 的 connection failure)。OpenSSL 3.x 的错误串里 0A00045C 中 0A 是库标识 SSL routines,据 OpenSSL 官方文档,它比错误文本更稳定,排错时优先看错误码。

报错原文 发出方 最可能根因 一条定位命令
tlsv13 alert certificate required 服务端 客户端未带 --cert/--key,或只发了叶子证书 curl -v --cert client.crt --key client.key ...
sslv3 alert bad certificate 服务端 签发 CA 不在服务端信任列表,或中间 CA 缺失 openssl verify -CAfile ca.crt -untrusted intermediate.crt client.crt
tlsv1 alert unknown ca(curl 35) 客户端 --cacert 指错 CA,或服务端链缺中间 CA openssl s_client -connect host:443 -showcerts
Empty client certificate chain Java 服务端 client-auth=need 但 truststore 为空 keytool -list -v -keystore truststore.p12
Path does not chain with any of the trust anchors Java 服务端 truststore 只导入了 leaf,缺根/中间 CA 同上,看 Owner 是否为 CA
reset before headers ... connection failure Envoy DownstreamTlsContext 缺 validation_context envoy --mode validate -c envoy.yaml

客户端侧先用 curl 复现,注意 TLS 1.3 下服务端索要证书发生在握手后段,-v 输出里能看到 Request CERT (13) 与 Server certificate Verify (15):

# 同时指定客户端证书与私钥,并用正确的根 CA 校验服务端
curl -v https://api.example.com/health 
  --cert client.crt --key client.key 
  --cacert ca.crt          # 若报 unknown ca,先确认这个文件是签发服务端证书的根 CA

证书链问题用 openssl verify 逐段切断,比反复重启服务快得多(OpenSSL 3.0+ 均支持 -untrusted):

# 期望输出 client.crt: OK
# 报 "unable to get local issuer certificate" = 缺中间 CA,用 -untrusted 补上再验
openssl verify -CAfile ca.crt -untrusted intermediate.crt client.crt

# 直接观察握手是否真的发送了客户端证书
openssl s_client -connect api.example.com:443 -tls1_3 
  -cert client.crt -key client.key -CAfile ca.crt -servername api.example.com

Envoy 1.30 的坑在于:require_client_certificate: true 只表示”要求”,真正决定信任谁的是 validation_context;漏写它 Envoy 会接受 TLS 连接但在上游失败,日志只给你一句 connection failure。据 Envoy 1.30 文档,改动后务必先做静态校验(返回 configuration ... OK 才算过):

# DownstreamTlsContext 最小可用片段(Envoy 1.30)
transport_socket:
  name: envoy.transport_sockets.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
    require_client_certificate: true            # 等价 Spring 的 client-auth=need
    common_tls_context:
      tls_certificates:
        - certificate_chain: { filename: /certs/server.crt }
          private_key:       { filename: /certs/server.key }
      validation_context:
        trusted_ca: { filename: /certs/ca.crt } # 路径写错 → reset before headers
envoy --mode validate -c /etc/envoy/envoy.yaml  # 改完先跑这条

Spring Boot 3.2 侧,server.ssl.client-auth 默认值是 none,设成 need 才强制;但若 trust-store 指向空库,握手会以 Empty client certificate chain 或 CertPathValidatorException 结束。据 Spring Boot 3.2 参考文档,PKCS12 是默认 store 类型,导 CA 时别用 leaf 别名覆盖:

# 检查 truststore 里到底有几条、是不是 CA
keytool -list -v -keystore truststore.p12 -storetype PKCS12 
  | grep -E "Alias name|Entry type|Owner"
# 导入根 CA(-alias 必须唯一,重复会报 certificate not imported)
keytool -importcert -alias root-ca -file ca.crt 
  -keystore truststore.p12 -storetype PKCS12 -storepass changeit -noprompt
# application.yml
server:
  ssl:
    enabled: true
    client-auth: need          # none(默认) / want(请求但不强制) / need(强制)
    trust-store: classpath:truststore.p12
    trust-store-password: changeit
    trust-store-type: PKCS12

还有一个容易被忽略的点:据 Let’s Encrypt 文档,服务端必须发送完整链(leaf + 中间 CA),根 CA 不进链;客户端 truststore 里则应放根 CA。服务端多发根、客户端少放中间,正是 unknown ca 与 Path does not chain 两类报错最常见的成因组合。

mTLS 配置教程效果验证:如何确认双向认证真的生效而不是“看起来生效”?

验证 mTLS 最容易踩的坑,是把”连接成功”当成”双向认证成功”。TLS 1.3(RFC 8446)把客户端证书请求放在握手后半段的加密记录里,明文抓包看不到,加上很多服务端配置成”请求但不强制”(Envoy 中 require_client_certificate 默认为 false),于是无证书连接照样返回 200。下面用五个互相独立的证据链交叉验证,任何一条不成立就说明 mTLS 没有真正落地。

1. 正向验证:带客户端证书握手

# -tls1_3 强制 TLS 1.3;-brief 只输出摘要;-servername 触发 SNI
# 证书与私钥必须匹配,ca.crt 用于校验服务端证书链
openssl s_client -connect payment.internal:8443 
  -servername payment.internal 
  -cert client.crt -key client.key 
  -CAfile ca.crt -tls1_3 -brief
# 期望输出(OpenSSL 3.x):
# CONNECTION ESTABLISHED
# Protocol version: TLSv1.3
# Cipher: TLS_AES_256_GCM_SHA384
# Verification: OK

注意 Verification: OK 只表示服务端证书链校验通过,不表示服务端接受了你的客户端证书。真正的确认在服务端日志或统计里(见第 4 条)。OpenSSL 1.1.1 及以上才完整支持 TLS 1.3,-brief 自 1.1.0 起可用。

2. 反向验证:故意不带证书

# 去掉 -cert/-key,其余参数不变
openssl s_client -connect payment.internal:8443 
  -servername payment.internal -CAfile ca.crt -tls1_3 -brief
# 期望(服务端强制 mTLS):
# 40B7...:error:...:tlsv1 alert certificate required:...
# alert 编号 116 = certificate_required(RFC 8446 §6.2)

如果这条命令仍能建立连接并返回 HTTP 200,说明服务端只是”请求”而非”强制”客户端证书。在 Envoy 中对应的开关是 DownstreamTlsContext.require_client_certificate(默认 false),必须显式设为 true,否则 require_client_certificate: false 下客户端不提供证书也能握手成功。

3. curl 的状态码语义区分

# 带证书:期望 HTTP/2 200
curl -sS -o /dev/null -w '%{http_code} %{http_version}n' 
  --cert client.crt --key client.key --cacert ca.crt 
  https://payment.internal:8443/health

# 不带证书:期望 curl: (56) ... tlsv1 alert certificate required
curl -sS -o /dev/null -w '%{http_code}n' 
  --cacert ca.crt https://payment.internal:8443/health

关键判据:无证书时应当是 curl 错误码 56(接收失败),而不是 401/403。401 意味着 TLS 层已放行、失败发生在应用层鉴权(Spring Security 的 X509AuthenticationFilter 未取到证书),这恰恰证明 mTLS 没生效。

4. Envoy 管理端口统计

# 9901 是 Envoy admin 默认端口(address 默认 127.0.0.1)
curl -s localhost:9901/stats | grep -E 'ssl.handshake|ssl.fail_verify_no_cert|ssl.connection_error'
# 期望:ssl.handshake 随每次请求递增
# ssl.fail_verify_no_cert 与 ssl.connection_error 保持 0

ssl.fail_verify_no_cert 增长说明有客户端未带证书却试图连接——这本身就是 mTLS 已强制的证据;若它恒为 0 而 ssl.handshake 也在涨,需回到第 2 条确认。

5. 抓包确认 CertificateRequest 确实发出

sudo tcpdump -i eth0 -nn -s0 -w mtls.pcap port 8443
# Wireshark 过滤:tls.handshake.type == 13
# 13 = CertificateRequest(RFC 8446 §4.3.2)
# 还需能看到 type == 11(Certificate)从客户端发往服务端

没有 type 13 记录,说明服务端根本没请求客户端证书,问题在 Envoy 的 DownstreamTlsContext 或 validation_context 未配置;有 13 但没有 11,说明客户端未发送证书。

现象 含义 定位方向
Verification: OK + TLSv1.3 TLS 层通过,证书未强制 查 require_client_certificate
alert certificate required(116) 服务端强制 mTLS 生效 符合预期
无证书返回 401/403 TLS 通过,应用层拒绝 Spring Security 证书映射
ssl.fail_verify_no_cert 增长 有客户端漏配证书 客户端证书分发
抓包无 type 13 服务端未请求证书 Envoy TLS 上下文

据 Let’s Encrypt 与 Mozilla Server Side TLS 指南的建议,验证阶段应同时保留正向与反向两条命令作为回归用例;据 OpenSSL 文档,s_client 的 -brief 输出在 1.1.1 与 3.x 间格式略有差异,脚本断言时建议匹配 Protocol version 与 Verification 两个关键字而非整行。这套五步验证同样适用于其它 mTLS 场景(如 Istio、Nginx ssl_verify_client on),只是统计端点与配置项名称不同。

mTLS 配置教程上线建议:证书轮换、吊销与监控怎么做?

上线后最容易翻车的时刻不是首次握手,而是第 89 天和吊销之后。先说结论:客户端证书 90 天、CA 3650 天,到期前 14 天告警,轮换走”先加新、双信任 7 天、再摘旧”的三段式。这也是本 mTLS 配置教程里唯一一条”时间参数错了会直接断流”的规则,建议直接写进值班手册。

证书什么时候换、换的顺序是什么?按下表执行,注意双信任窗口必须有明确结束日期,否则 truststore 会越滚越大:

对象 有效期 告警提前量 轮换动作
客户端证书(业务侧) 90 天(参考 Let’s Encrypt 短周期理念) 到期前 14 天 新证书与旧证书并存下发,客户端优先用新证书
服务端 CA 3650 天 到期前 180 天 新 CA 先进入 truststore,7 天双信任后再移除旧 CA
服务端叶子证书 90 天 到期前 14 天 热更新(SDS / Actuator),无需重启监听
# 1) 核对现有客户端证书剩余寿命,notAfter 距今 < 14 天即触发轮换
openssl x509 -in client.crt -noout -subject -enddate
# notAfter=Apr 12 08:00:00 2025 GMT

# 2) 签发新客户端证书,-days 90 对应 90 天策略
openssl req -new -newkey rsa:2048 -nodes -keyout client-new.key 
  -out client-new.csr -subj "/CN=svc-order/O=example"
openssl x509 -req -in client-new.csr -CA ca.crt -CAkey ca.key 
  -CAcreateserial -days 90 -sha256 -out client-new.crt

Envoy 1.30 怎么改配置才不断流?静态配置走”校验 + 优雅重启”,先把新旧 CA 拼成一个 bundle(cat ca-old.crt ca-new.crt > ca-bundle.pem),让 validation_context.trusted_ca 同时信任两者:

# /etc/envoy/envoy.yaml 片段(Envoy 1.30,DownstreamTlsContext)
filter_chains:
- transport_socket:
    name: envoy.transport_sockets.tls
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
      require_client_certificate: true          # 强制客户端证书,缺失时计入 ssl.fail_verify_no_cert
      common_tls_context:
        validation_context:
          trusted_ca:
            filename: /etc/certs/ca-bundle.pem  # 7 天双信任窗口:新旧 CA 拼接
          # crl: { filename: /etc/certs/ca.crl } # 需要 CRL 时启用,见下文

# 改完先校验,输出 "configuration '...' OK" 再重启
envoy --mode validate -c /etc/envoy/envoy.yaml
# 优雅退出:--drain-time-s 默认 600 秒,入口网关建议显式降到 30 秒
envoy -c /etc/envoy/envoy.yaml --drain-time-s 30 --drain-strategy gradual

如果已经在用 SDS(envoy.extensions.transport_sockets.tls.v3.Secret + xDS),证书下发与配置变更解耦,轮换完全不需要碰入口网关进程——这是把 90 天轮换做成常态化的前提。

Spring Boot 3.2 侧要不要重启?SSL bundle 支持热刷新,但 server.ssl.client-auth 属于启动期绑定,改了必须重启:

spring:
  ssl:
    bundle:
      pem:
        mtls-server:
          keystore:
            certificate: file:/etc/certs/server.crt
            private-key: file:/etc/certs/server.key
          truststore:
            certificate: file:/etc/certs/ca-bundle.pem  # 双信任窗口期间含新旧 CA
server:
  ssl:
    bundle: mtls-server
    client-auth: need          # 变更此项仍需重启

# 触发 bundle 重载(需 management.endpoints.web.exposure.include=refresh)
curl -X POST http://localhost:8080/actuator/refresh

滚动发布时保留旧实例 10 分钟,观察 5xx 与握手失败率是否回落,再摘除旧 Pod。这正是本 mTLS 配置教程强调”灰度窗口”而非”一次性全量”的原因:客户端缓存旧 CA 的时间往往比你想的久。

吊销:为什么优先靠短有效期而不是 CRL?RFC 5280 定义的 CRL 存在 nextUpdate 空窗期,CRL 拉取失败时多数实现是”放行”而非”拒绝”。Envoy 的 validation_context.crl.filename 只支持文件,意味着你要自己解决分发;Spring Boot 没有内置 CRL 开关,需自定义 X509TrustManager:

// 关键:CRL 过期或被吊销都必须抛异常,而不是静默放行
X509CRL crl = (X509CRL) CertificateFactory.getInstance("X.509")
        .generateCRL(new FileInputStream("/etc/certs/ca.crl"));
if (crl.getNextUpdate().before(new Date()))
    throw new CertificateException("CRL 已过期,拒绝握手");
if (crl.isRevoked(chain[0]))
    throw new CertificateException("客户端证书已被吊销");

# 运维核对 CRL 新鲜度,重点看 Next Update
openssl crl -in ca.crl -noout -text | head -20
openssl crl -in ca.crl -noout -nextupdate

监控看哪几个数?阈值直接抄:

信号 采集位置 告警条件 首查方向
ssl.fail_verify_no_cert Envoy listener 统计 > 5 次/分钟 客户端未带证书,或 truststore 漏了新 CA
ssl.handshake Envoy listener 统计 环比下降 30% 证书过期、CRL 拉取失败、SNI 错配
SSLHandshakeException Spring Boot 日志 连续出现 3 次 立即开工单,附 openssl s_client -connect host:8443 -cert client.crt -key client.key 结果

Envoy 的 TLS 统计默认开启,指标形如 listener.0.0.0.0_8443.ssl.handshake,抓取时按 listener 维度聚合即可;据 Envoy 官方文档,ssl.fail_verify_error、ssl.connection_error 也应一并纳入面板,才能区分”证书不对”和”TCP 就没通”。

mTLS 就是双向 TLS 认证,通常指服务端在握手时校验客户端证书。是否改代码取决于客户端类型:curl、openssl s_client、Envoy 只需加证书参数;Java HttpClient 需要构造 SSLContext 并加载 keystore/truststore。

可以共用同一个根 CA,但建议把客户端证书和服务端证书放在不同中间 CA 下,便于按用途吊销和限制信任范围。共用根 CA 时,服务端 truststore 只导入根 CA 或对应中间 CA,不要导入无关的业务 CA。

先确认 curl 同时带了 –cert 和 –key,且证书链文件包含 leaf 与中间 CA。若仍报错,检查 Envoy validation_context.trusted_ca 是否指向签发该客户端证书的 CA,以及客户端证书是否含 extendedKeyUsage=clientAuth。

mTLS 做传输层身份认证,JWT 做应用层授权,Istio STRICT 是网格内自动启用 mTLS 的方式。若服务在 Kubernetes 且已用 Istio,优先用 PeerAuthentication mode: STRICT;若不在网格内,用 Envoy 1.30 或 HAProxy 2.9 手工配置更直接。

健康检查客户端也要带客户端证书,或给健康检查单独开一个不强制 mTLS 的端口。不要为了健康检查把 client-auth 改成 want,否则未带证书的请求仍可能进入应用层,削弱 mTLS 的强制效果。

先签发新客户端证书,服务端 truststore 同时信任新旧证书 7 天;客户端切到新证书后观察 ssl.handshake 与 5xx 指标,再移除旧证书。Envoy 静态配置需重启,建议用 –drain-time-s 30 平滑退出。

mTLS 能证明调用方持有私钥,但无法表达细粒度权限;API Key 和 IP 白名单仍有防误用和限流价值。生产环境常见组合是 mTLS 做传输层身份,JWT/OPA 做应用层授权,IP 白名单只作为外围补充。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。