SSL双向认证配置实战:用 OpenSSL 3 与 Nginx 1.24 校验客户端证书
SSL双向认证配置的核心是三条指令:ssl_verify_client on、ssl_client_certificate 指向签发客户端证书的 CA 证书链、ssl_verify_depth 设为链长(默认值 1),客户端不带证书时 Nginx 直接返回 400 或 495/496。 自建 CA 只需一条命令:openssl req -x509 -newkey rsa:3072 -sha256 -days 3650 -nodes -keyout ca.key -out ca.crt,客户端证书建议有效期 90–365 天,CA 有效期 10 年。 客户端证书必须带 extendedKeyUsage=clientAuth,服务端证书必须带 serverAuth 与 SAN,否则握手阶段会报 tlsv1 alert unknown ca 或 certificate purpose 错误。 吊销要真正生效,需生成 CRL(openssl ca -gencrl)并配置 ssl_crl,同时把 ssl_session_tickets 设为 off,否则 TLS 1.3 会话复用会让已吊销证书继续可用。 验证一条命令就够:curl -v --cert client.crt --key client.key --cacert ca.crt https://api.example.com,输出中出现 SSL certificate verify ok 且 Nginx 日志 $ssl_client_verify 为 SUCCESS 即表示配置生效。
为什么单向 HTTPS 不够用?SSL双向认证配置要解决的根本问题
普通 HTTPS 只验证服务端:客户端校验证书链与域名,服务端对访问者一无所知,身份全靠应用层的账号密码或 Bearer Token。SSL双向认证配置(mTLS)把身份校验提前到 TLS 握手阶段:客户端必须出示 X.509 证书,服务端用 CA 链验签。协议依据来自 RFC 8446(TLS 1.3)第 4.4.2 节:服务端发送 CertificateRequest 后,客户端必须回传 Certificate 与 CertificateVerify 消息,签名覆盖整个握手 transcript,因此中间人无法重放。
| 维度 | 单向 HTTPS | SSL双向认证配置(mTLS) |
|---|---|---|
| 服务端身份 | 客户端校验证书链与域名 | 同左 |
| 客户端身份 | TLS 层无身份,依赖账号密码或 Token | 客户端出示 X.509,服务端用 CA 链验签 |
| 凭据泄露影响 | Token 可被重放至过期 | 私钥不出端,握手签名绑定 transcript |
| 运维成本 | 主要轮换服务端证书 | 需签发、分发、吊销、轮换客户端证书 |
最需要 SSL双向认证配置的四类场景:内部微服务之间的 API 调用、IoT 设备接入网关、B 端开放平台给合作方发证书、Kubernetes admission webhook(apiserver 通过 --client-ca-file 校验回调服务端证书)。成本要提前算清:自建 CA 的证书费用为 0,但需自行承担 CRL 分发、到期轮换、私钥保管;商业 CA 的客户端证书通常按张计费,年费大致在 300–3000 元人民币区间,具体以 CA 商务报价为准。据 Let’s Encrypt 文档,其不提供客户端证书,因此 mTLS 客户端证书需自建 CA 或商业 CA。
Nginx 1.24.0 + OpenSSL 3.0+ 的最小配置如下,注意 ssl_verify_client 默认是 off,ssl_verify_depth 默认是 1:
# /etc/nginx/conf.d/mtls.conf
ssl_client_certificate /etc/nginx/mtls/ca-chain.pem; # 必须含完整中间 CA
ssl_verify_client on; # on=强制;optional=有证书才校验;默认 off
ssl_verify_depth 2; # 默认 1;根→中间→叶证书链需设为 2
# 不带客户端证书,观察握手被拒(OpenSSL 3.0+)
openssl s_client -connect api.example.com:443 -servername api.example.com
-CAfile /etc/ssl/certs/ca-certificates.crt -state
# 预期:tlsv1 alert certificate required;Nginx 返回 400 No required SSL certificate was sent
# 带客户端证书与私钥
openssl s_client -connect api.example.com:443 -servername api.example.com
-cert client.crt -key client.key -CAfile ca-chain.pem -verify_return_error
它不能替代授权:证书只能证明“你是谁”,无法表达“你能访问哪些接口”。生产实践是 mTLS 负责通道与身份,RBAC 或 OPA 负责权限,两者叠加使用。典型失败模式集中在三处:客户端证书缺少 clientAuth 用途,openssl verify -purpose sslclient client.crt 会报 unsupported certificate purpose;服务端未下发完整中间 CA,客户端报 unable to get local issuer certificate;证书过期后未做监控告警,握手报 certificate has expired。这三类问题占线上 SSL双向认证配置故障的多数,监控至少应对客户端证书执行 openssl x509 -checkend 2592000 提前 30 天告警。
SSL双向认证配置完整实操步骤:从自建 CA 到 Nginx 生效(6 步)
想把 ssl双向认证配置 一次跑通,关键是先把”证书链的签发关系”理顺,再谈 Nginx 指令。下面 6 步在 Ubuntu 24.04 + OpenSSL 3.0.13 + Nginx 1.24.0 上实测可复现,整套流程约 10 分钟。
-
步骤 1:确认版本与目录权限。Ubuntu 24.04 仓库自带 OpenSSL 3.0.13(2024-01-30 发布),Nginx 为 1.24.0;据 OpenSSL 官方文档,
-addext自 1.1.1 起可用,x509 -copy_extensions需 3.0 及以上,因此低版本系统必须先升级。# 确认工具链版本 openssl version -a | head -2 # 期望:OpenSSL 3.0.13 30 Jan 2024 nginx -v # 期望:nginx version: nginx/1.24.0 (Ubuntu) nginx -V 2>&1 | tr ' ' 'n' | grep -- --with-http_ssl_module # 有输出即含 SSL 模块 # 工作目录与私钥目录,700 防止其他用户遍历 sudo install -d -m 700 /root/ca /etc/nginx/ssl -
步骤 2:生成根 CA。CA 私钥是全链路信任的根,应放在离线机或 HSM 上,Nginx 主机只保留
ca.crt。CA/Browser Forum 的 398 天上限只约束公开 TLS 服务器证书,私有根 CA 可用 3650 天。cd /root/ca openssl req -x509 -newkey rsa:3072 -sha256 -days 3650 -nodes -keyout ca.key -out ca.crt -subj '/C=CN/O=Example/CN=Example Internal Root CA v1' -addext 'basicConstraints=critical,CA:TRUE' -addext 'keyUsage=critical,keyCertSign,cRLSign' chmod 400 ca.key && chmod 444 ca.crt openssl x509 -in ca.crt -noout -text | grep -A1 'Basic Constraints' # 必须为 CA:TRUE -
步骤 3:签发服务端证书。有效期取 365 天,避免触碰 398 天硬上限(Apple/Chrome 自 2020-09-01 起拒绝超期证书,Let’s Encrypt 则统一签发 90 天)。
openssl genrsa -out server.key 2048 openssl req -new -key server.key -out server.csr -subj '/C=CN/O=Example/CN=api.example.com' -addext 'subjectAltName=DNS:api.example.com' -addext 'extendedKeyUsage=serverAuth' # -copy_extensions copy 把 CSR 里的 SAN/EKU 原样带入证书,需 OpenSSL 3.0+ openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256 -copy_extensions copy -
步骤 4:签发客户端证书。CN 用设备编号或合作方 ID,每张必须唯一——Nginx 日志里的
$ssl_client_s_dn和后续 CRL 吊销都靠它定位。openssl genrsa -out client.key 2048 openssl req -new -key client.key -out client.csr -subj '/C=CN/O=Partner/CN=partner-0001' -addext 'extendedKeyUsage=clientAuth' openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365 -sha256 -copy_extensions copy -
步骤 5:写入 Nginx 配置。把
ca.crt拷到/etc/nginx/ssl/;若客户端证书由中间 CA 签发,需把中间 CA 与根 CA 按”中间在前、根在后”拼成ca-chain.crt再引用。sudo cp ca.crt server.crt server.key /etc/nginx/ssl/ sudo chmod 400 /etc/nginx/ssl/server.key server { listen 443 ssl; server_name api.example.com; ssl_certificate /etc/nginx/ssl/server.crt; ssl_certificate_key /etc/nginx/ssl/server.key; ssl_client_certificate /etc/nginx/ssl/ca.crt; # 校验客户端证书所用的 CA 列表 ssl_verify_client on; # 默认 off;可选 optional / optional_no_ca ssl_verify_depth 2; # 默认 1,链长 = 中间 CA 数 + 1 location / { return 200 "verify=$ssl_client_verify cn=$ssl_client_s_dnn"; } } -
步骤 6:生效与首轮验证。
nginx -t报nginx: [emerg] no "ssl_certificate" is defined for the "listen ... ssl" directive说明证书路径写错;reload 后带证书应 200,不带证书应 400(Nginx 对”未发送客户端证书”返回 400,对”证书无效/过期”返回 495)。sudo nginx -t && sudo systemctl reload nginx curl -sS --cacert /root/ca/ca.crt --cert client.crt --key client.key https://api.example.com/ -w 'nHTTP %{http_code}n' # 期望 HTTP 200 curl -sS --cacert /root/ca/ca.crt https://api.example.com/ -w 'nHTTP %{http_code}n' # 期望 HTTP 400
| 指令 | 默认值 | 取值范围 | 行为差异 |
|---|---|---|---|
ssl_verify_client |
off |
on / off / optional / optional_no_ca | on 必须提供有效证书;optional 允许无证书但提供了就校验;optional_no_ca 只要求提供、不验链 |
ssl_verify_depth |
1 |
≥1 的整数 | 根签叶子用 1;”根 → 中间 → 叶子”必须设为 2 或更高 |
ssl_client_certificate |
无 | PEM 文件路径 | 所列 CA 同时用于校验与下发 CA 列表(除非另配 ssl_trusted_certificate) |
至此一次完整的 ssl双向认证配置 已生效。后续要落地到生产,还需补三件事:用 openssl ca 或 openssl x509 -req 维护 CRL 并在 Nginx 中配置 ssl_crl、给客户端私钥设置口令或迁入系统密钥库、以及按 RFC 5280 的 Key Usage 规则复核 EKU 是否区分了 serverAuth 与 clientAuth。
SSL双向认证配置的命令与 Nginx 参数示例(含默认值)
下面这段配置是 Nginx 1.24 上启用 ssl双向认证配置 的最小可用骨架,去掉任意一行都会让校验失效或降级,注释里标出了每行的作用与默认值差异:
server {
listen 443 ssl;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/server.crt; # 服务端证书(含中间证书时可拼接)
ssl_certificate_key /etc/nginx/ssl/server.key;
ssl_protocols TLSv1.2 TLSv1.3; # 默认 TLSv1 TLSv1.1 TLSv1.2(1.23.4 起默认仅 1.2/1.3)
ssl_client_certificate /etc/nginx/ssl/ca-chain.crt; # 信任锚:根 CA + 中间 CA,必须完整
ssl_verify_client on; # 默认 off;可选 on | off | optional | optional_no_ca
ssl_verify_depth 2; # 默认 1,链上有中间 CA 必须设为 2
ssl_crl /etc/nginx/ssl/ca.crl; # 吊销列表,仅在 reload 时重新读取
ssl_session_tickets off; # 默认 on;做吊销时务必关闭,否则旧票据可绕过 CRL
# ssl_session_cache 默认 none(off 表示明确告知客户端不要复用会话),ssl_session_timeout 默认 5m
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header X-Client-Verify $ssl_client_verify; # 取值 SUCCESS / NONE / FAILED:reason
proxy_set_header X-Client-DN $ssl_client_s_dn; # 客户端证书主题,供后端做二次鉴权
}
}
参数默认值是最容易出错的地方,记住三点即可:ssl_verify_client 默认 off(不加等于没开双向认证);ssl_verify_depth 默认 1,只校验客户端证书的直接签发者,遇到“根 CA → 中间 CA → 客户端证书”的三级链就会报 400 The SSL certificate error;ssl_session_tickets 默认 on,而会话票据恢复的握手不会重新走证书校验路径,所以启用 ssl_crl 后必须把它关掉。据 Nginx 官方文档,ssl_crl 自 0.8.7 起可用,且只在配置加载/reload 时读取文件,吊销后不 nginx -s reload 是不会生效的。
客户端联调先用 curl 跑通,再看握手细节:
# 成功时输出含 “SSL certificate verify ok” 与 HTTP/2 200
curl -v --cert ./client.crt --key ./client.key --cacert ./ca.crt
https://api.example.com/health
# 单独验证 TLS 1.3 下的握手行为(--tlsv1.3 需 curl 7.52.0+ 且底层支持 TLS 1.3)
curl -v --tlsv1.3 --cert ./client.crt --key ./client.key --cacert ./ca.crt
https://api.example.com/health
不依赖 curl 的诊断用 s_client,它能直接告诉你服务端到底信任哪些 CA:
openssl s_client -connect api.example.com:443 -servername api.example.com
-cert client.crt -key client.key -CAfile ca.crt -state
# 关注输出中的 “Acceptable client certificate CA names”:
# 为空 => ssl_client_certificate 未加载成功或路径错误
# 只列出根 CA 而客户端证书由中间 CA 签发 => ca-chain.crt 缺中间证书
吊销列表的生成依赖 openssl.cnf 中的 [CA_default] 段(dir、database、crlnumber 三项必须存在):
# 先吊销(可选),再生成 CRL;-gencrl 每次都会重写整个列表
openssl ca -config openssl.cnf -revoke client.crt
openssl ca -config openssl.cnf -gencrl -out /etc/nginx/ssl/ca.crl
nginx -t && nginx -s reload # ssl_crl 不 reload 不生效
迁移到 Apache httpd 2.4 时语义一一对应,但默认值不同,别照抄数字:
| 能力 | Nginx 1.24 | Apache httpd 2.4 (mod_ssl) | 默认值差异 |
|---|---|---|---|
| 要求客户端证书 | ssl_verify_client on; |
SSLVerifyClient require |
Nginx 默认 off;Apache 默认 none |
| 信任锚 | ssl_client_certificate |
SSLCACertificateFile /etc/httpd/ssl/ca-chain.crt |
均需包含完整中间 CA |
| 链深度 | ssl_verify_depth 2; |
SSLVerifyDepth 2 |
两者默认均为 1,且都从 0 开始计数 |
| 吊销 | ssl_crl |
SSLCARevocationFile |
都需 reload/restart 才重读 |
关于深度计数:Apache mod_ssl 文档明确 SSLVerifyDepth 0 只接受自签名客户端证书,1 表示必须由直接配置的 CA 签发,因此三级链同样要写 2;这与 Nginx 的行为一致,也是从 Nginx 迁移到 Apache 时最常见的“配置看起来对、握手却失败”的原因。证书链与吊销语义的规范依据可参考 RFC 5280 第 6 章(证书路径验证)与第 5 章(CRL),Let’s Encrypt 文档也建议信任链文件按“叶子 → 中间 → 根”顺序拼接以避免部分客户端解析失败。
ssl_verify_client 三个取值与方案选型对比表
为什么说 ssl_verify_client 的取值决定了整条链路的严格程度?
Nginx 从 1.0.3 起提供该指令,默认值是 off——完全不向客户端发 CertificateRequest,握手在 RFC 8446(TLS 1.3)与 RFC 5246(TLS 1.2)定义的单向认证流程里就结束了。一旦改成 on/optional/optional_no_ca,Nginx 会在握手阶段请求证书,三种取值的行为差异如下(依据 Nginx 官方 ngx_http_ssl_module 文档):
| 取值 | 无证书时 | 证书校验失败时 | 适用阶段 |
|---|---|---|---|
on |
返回 400(可用 error_page 接管 495/496) |
握手失败,日志出现 tlsv1 alert unknown ca |
生产环境 |
optional |
正常放行,此时 $ssl_client_verify 为 NONE |
握手失败 | 灰度迁移期 |
optional_no_ca |
返回 400 | 放行,仅把原因写入 $ssl_client_verify |
仅调试,切勿用于生产 |
生产环境推荐的最小可用配置如下(Nginx 1.24.x 内置 http_ssl_module,无需额外编译):
# 先确认版本与模块
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx/|with-http_ssl_module'
server {
listen 443 ssl;
server_name api.example.com;
ssl_certificate /etc/nginx/certs/server.crt;
ssl_certificate_key /etc/nginx/certs/server.key;
ssl_client_certificate /etc/nginx/certs/ca.crt; # 客户端证书的签发 CA 链
ssl_verify_client on; # 默认 off;on = 必须提供且链校验通过
ssl_verify_depth 2; # 默认 1;存在中间 CA 时必须调大
ssl_crl /etc/nginx/certs/ca.crl; # 默认 none,开源版只支持 CRL
# 495 = 证书错误,496 = 未提供证书(Nginx 自定义码)
error_page 495 496 = @cert_err;
location @cert_err {
default_type application/json;
return 401 '{"code":"CLIENT_CERT_INVALID","verify":"$ssl_client_verify"}';
}
}
自测时用 openssl s_client -connect api.example.com:443 -cert client.crt -key client.key,返回码 Verify return code: 0 (ok) 才算通过;不加 -cert 应当看到 400/401。
客户端证书该自建还是买商业 CA?据 Let’s Encrypt 的 CPS 文档,其只签发 TLS 服务器证书、不提供客户端证书,所以双向认证的客户端证书只有两条外部路径:
| 签发方式 | 单张成本 | 运维负担 | 适用规模 |
|---|---|---|---|
| 自建 OpenSSL CA | 0 元 | 自行维护 CRL 与轮换 | 几十到几千张 |
| 商业 CA 客户端证书 | 约 300–3000 元/年 | 厂商协助吊销 | 对外合作方 |
| 云私有 CA(如 AWS Private CA) | 按 CA 数量月费计,量级数百至数千元 | 托管 CRL/OCSP | 多云与自动化 |
选型建议:设备或服务在 500 张以内、且都在自己可控范围内,自建 CA 加 CRL 足够;需要给外部合作方发证并对接其合规审计时,选商业 CA 或云私有 CA,把吊销与审计责任外移。
换到别的网关,写法一样吗?不完全一样。Nginx 开源版只支持 CRL,不支持对客户端证书做 OCSP 校验(OCSP stapling 仅针对服务端证书);Envoy 用 require_client_certificate: true 配合 certificate_revocation 支持 OCSP;ingress-nginx 则通过 nginx.ingress.kubernetes.io/auth-tls-verify-client 与 auth-tls-secret 两个注解实现同等能力,取值同样接受 on/optional/optional_no_ca。
SSL双向认证配置上线后最常见的 6 个报错与排查路径
双向认证的握手失败点无非三类:客户端没带证书、证书链验不过、证书状态失效。下面按线上出现频率从高到低排列,每条都给出可直接复制的排查命令(环境:OpenSSL 3.0.x、Nginx 1.24.x stable)。
Q1:客户端只看到 400 Bad Request: No required SSL certificate was sent,是没带证书还是 CA 列表不匹配?
先看服务端在 CertificateRequest 中下发了哪些可接受 CA 名(TLS 1.3 中即 certificate_authorities 扩展,见 RFC 8446 §4.2.4):
# 打印服务端下发的可接受客户端 CA 列表
openssl s_client -connect example.com:443 -servername example.com -state &1
| sed -n '/Acceptable client certificate CA names/,/^$/p'
# 若输出里没有你签发客户端证书的那个 CA 的 DN,浏览器就"无证书可选",必然 400
该列表由 Nginx 的 ssl_client_certificate 指向的文件决定,文件里必须包含签发客户端证书的 CA(含中间 CA)。注意 Nginx 默认 ssl_verify_client off,开启后默认 ssl_verify_depth 1,链深超过一层需显式调大。
Q2:495 / 496 为什么在浏览器里看不见?
495、496 是 Nginx 内部状态码,只有在用 error_page 映射后才会以自定义页面呈现,否则客户端一律收到 400。据 Nginx 官方文档 ngx_http_ssl_module,对应关系如下:
| 状态码 | 触发条件 | 客户端默认看到 | 需 error_page 才能自定义 |
|---|---|---|---|
| 400 | TLS 层未收到证书,或签发者不在可接受 CA 列表中 | 400(含 “No required SSL certificate was sent”) | 否 |
| 495 | 证书已收到但校验失败:过期、命中 CRL、签名链错误 | 400 | 是 |
| 496 | ssl_verify_client on 但客户端未发送证书 |
400 | 是 |
| 497 | 明文 HTTP 打到 HTTPS 端口 | 400 | 是 |
server {
listen 443 ssl;
ssl_verify_client on; # 默认 off;optional 允许无证书访问
ssl_client_certificate /etc/nginx/ca-chain.crt; # 必须含中间 CA
ssl_verify_depth 3; # 默认 1
error_log /var/log/nginx/ssl_error.log info; # 默认级别为 error,info 才记录 495/496 细节
error_page 495 496 = /custom_4xx.html;
}
Q3:error_log 里出现 SSL_do_handshake() failed (SSL: error:0A000418:SSL routines::tlsv1 alert unknown ca) 怎么办?
含义是客户端证书的签发链在服务端找不到锚点,多半是 ssl_client_certificate 里漏了中间 CA。单独验证一遍:
openssl verify -CAfile /etc/nginx/ca-chain.crt client.crt
# 期望:client.crt: OK
# 缺链时:error 20 at 0 depth lookup: unable to get local issuer certificate
# 补齐顺序:根 CA 在前,中间 CA 在后
cat root.crt intermediate.crt > /etc/nginx/ca-chain.crt && nginx -t && systemctl reload nginx
Q4:curl: (60) unable to verify the first certificate 是服务端证书链没拼全。
服务端只发了叶子证书,未带中间 CA。ssl_certificate 必须指向拼接后的 fullchain,且叶子在前:
cat server.crt intermediate.crt > fullchain.crt # 顺序不可颠倒
# nginx.conf: ssl_certificate /etc/nginx/fullchain.crt;
openssl s_client -connect example.com:443 -showcerts /dev/null | grep -c "BEGIN CERTIFICATE"
# 输出应 ≥2,只有 1 说明链没拼上
Q5:certificate has expired 与 certificate revoked 怎么区分?
openssl x509 -noout -dates -subject -issuer -in client.crt # 核对 notBefore / notAfter
openssl crl -in /etc/nginx/crl/client.crl -noout -lastupdate -nextupdate
# nginx.conf 中启用吊销检查,更新 CRL 后必须 reload 才生效
# ssl_crl /etc/nginx/crl/client.crl;
需特别注意:Nginx 开源版不支持用 OCSP 校验客户端证书,吊销只能依赖 CRL,ssl_stapling 仅作用于服务端证书链。CRL 过期会直接导致全部客户端 495。
Q6:浏览器报 ERR_BAD_SSL_CLIENT_AUTH_CERT 或 ERR_SSL_CLIENT_AUTH_CERT_NO_PRIVATE_KEY?
后者明确表示只导入了 .crt 没有私钥。Windows 需生成 .pfx 后双击导入「个人」存储;macOS 需把证书拖入「登录」钥匙串并将信任设为「始终信任」:
openssl pkcs12 -export -inkey client.key -in client.crt -certfile ca-chain.crt -out client.pfx
# 导入时勾选"包括所有扩展属性",否则中间 CA 会丢失
如何验证 SSL双向认证配置真的生效?4 种可复现的验证方法
改完 ssl_verify_client on 不等于生效:Nginx 允许把双向认证配成 optional,也允许证书链校验通过但用途(EKU)不对,这两种情况正向请求都会返回 200。所以验证必须”正反各一次 + 日志 + 握手细节”四条腿走路,任何一条缺失都可能把故障留到上线后。
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL证书申请 · SSL证书购买 · SSL证书安装配置
- APP/小程序 HTTPS · SSL网站加密证书 · CA证书配置
- NGINX / APACHE / TOMCAT / IIS 证书配置 · SSL证书安装
- HTTPS配置 · SSL证书安装服务(各种服务器)
方法 1:正向 curl,先确认”该通的通了”。把 CA、客户端证书和私钥都带上,同时让 Nginx 把校验结果透传给上游,这样后端才能做二次授权:
# 1) 正向请求:携带客户端证书
curl -v --cert client.crt --key client.key --cacert ca.crt
https://api.example.com/health
# 期望:HTTP/2 200,且响应头含 X-Client-Verify: SUCCESS
# 2) Nginx 侧把校验结果透传给上游(http 或 location 块内)
location /health {
proxy_pass http://backend;
proxy_set_header X-Client-Verify $ssl_client_verify; # SUCCESS / FAILED:reason / NONE
proxy_set_header X-Client-DN $ssl_client_s_dn;
}
$ssl_client_verify 只有三种取值:SUCCESS、FAILED:<reason>、NONE。据 Nginx 官方文档,NONE 表示客户端根本没送证书,而不是”送了但校验失败”——这两个语义在排障时完全不同。
方法 2:反向 curl,这一条比正向更重要。去掉证书再请求一次,如果还能拿到 200,说明你写的是 optional 或 optional_no_ca,双向认证形同虚设:
curl -v https://api.example.com/health # 不带 --cert/--key
# 期望:HTTP/1.1 400 Bad Request
# error_log 中出现:
# [error] client sent no required SSL certificate while reading client request headers,
# client: 203.0.113.9, server: api.example.com, request: "GET /health HTTP/1.1"
这条日志对应 Nginx 内部状态码 496,客户端看到的是 400。记住这个映射关系,抓包时就不会因为”日志里没有 496″而误判。
方法 3:日志字段验证,把”偶然成功”变成”可审计”。在 http 块单独定义一个 mTLS 日志格式(Nginx 1.24 全支持这些变量):
log_format mtls '$remote_addr $ssl_client_verify $ssl_client_s_dn $ssl_client_serial';
access_log /var/log/nginx/mtls.log mtls;
# 正常请求:203.0.113.9 SUCCESS CN=partner-0001 4A1F...9C
# 未送证书:203.0.113.9 NONE - -
日志里出现 NONE 就回头查方法 2;出现 FAILED:unable to verify the first certificate 则多半是客户端没带中间 CA。
方法 4:用 s_client 看握手细节。curl 只告诉你结果,s_client 告诉你原因:
openssl s_client -connect api.example.com:443
-cert client.crt -key client.key -CAfile ca.crt -state
# 关注三处:
# Verify return code: 0 (ok)
# Acceptable client certificate CA names -> 应列出你的 CA 的 Subject
# Client Certificate Types: RSA sign, ECDSA sign
# 单独验证 TLS 1.3(RFC 8446 下 Certificate 在 Server Finished 之后发送,顺序与 1.2 不同)
openssl s_client -connect api.example.com:443 -tls1_3
-cert client.crt -key client.key -CAfile ca.crt
若 Acceptable client certificate CA names 为空,说明 ssl_client_certificate 没配或指向了错误文件,客户端会”不知道送哪张证书”。
交叉校验 EKU:最容易被忽略的一类错配。证书链完全正确,但用途只有 Server Authentication 时,握手照样被拒:
openssl x509 -in client.crt -noout -text | grep -A1 'Extended Key Usage'
# 必须包含:TLS Web Client Authentication
# 只有 TLS Web Server Authentication 的证书不能用于 mTLS
依据 RFC 5280 §4.2.1.12,EKU 存在但不含 clientAuth 时验证方必须拒绝——OpenSSL 与 Nginx 都遵循此规则。
上线前做一次吊销演练。很多团队配好了 CRL 却从没验证过它真的生效:
openssl ca -config openssl.cnf -revoke client.crt # 吊销
openssl ca -config openssl.cnf -gencrl -out ca.crl # 重新生成 CRL
nginx -s reload # 让 ssl_crl 生效
curl -v --cert client.crt --key client.key --cacert ca.crt https://api.example.com/health
# 期望握手失败,error_log:
# client SSL certificate verify error: (23:certificate revoked)
只有看到 23:certificate revoked,才能确认 ssl_crl 路径、reload 流程和 CRL 更新机制都是通的,此时再批量分发证书才安全。
| 验证方法 | 关键命令/配置 | 期望结果 | 能证明什么 |
|---|---|---|---|
| 正向 curl | --cert --key --cacert |
200 + X-Client-Verify: SUCCESS |
合法证书可通行 |
| 反向 curl | 去掉 --cert/--key |
400 + error_log 报 496 | 不是 optional 误配 |
| 日志字段 | $ssl_client_verify |
SUCCESS CN=partner-0001 |
结果可审计、可追溯 |
| s_client | -state / -tls1_3 |
Verify return code: 0 (ok) |
握手层与 CA 列表正确 |
| EKU 校验 | openssl x509 -text |
含 Client Authentication | 证书用途匹配 |
| 吊销演练 | openssl ca -revoke + reload |
23:certificate revoked |
CRL 链路真实生效 |
客户端证书有效期设多长才合理,短周期会不会把运维拖垮?
按用途分层是最省事的做法:根 CA 证书 10 年(离线保管、极少动),服务端证书 365 天,客户端证书 90–365 天。短周期的价值在于压缩私钥泄露窗口——据 Let’s Encrypt 的公开说明,其 90 天证书设计初衷之一就是限制密钥失窃后的滥用期。但证书数量一多,手工轮换成本是线性上升的,所以短周期必须配自动化签发。
用 Vault PKI 时有个容易踩的坑:挂载点默认 max_lease_ttl 是 768h(32 天),直接签发 90 天证书会失败,报错形如 cannot satisfy request, as TTL is greater than the maximum allowed lease ttl of 768h。正确顺序是先抬上限再签发:
# Vault 1.15+:先把 PKI 挂载点的租约上限调到 1 年(默认 768h)
vault secrets tune -max-lease-ttl=8760h pki
# 签发 90 天客户端证书(2160h = 90 天);common_name 用可追溯编号便于吊销定位
vault write pki/issue/client common_name=partner-0001 ttl=2160h
# 生成 .pfx 交给终端用户(密码单独通道传递,勿与文件同行)
openssl pkcs12 -export -inkey client.key -in client.crt -certfile ca.crt -out partner-0001.pfx
K8s 侧用 cert-manager 的 Certificate CRD 等价实现,未显式设置 renewBefore 时,cert-manager 会在证书生命周期约 2/3 处自动续期(见 cert-manager 文档):
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: partner-0001
spec:
secretName: partner-0001-tls
commonName: partner-0001
duration: 2160h # 90 天
renewBefore: 720h # 提前 30 天续期
issuerRef:
name: internal-ca
kind: ClusterIssuer
证书和私钥到底该怎么发给员工、服务器和合作方?
分发渠道要按对象区分,核心红线只有一条:私钥禁止走邮件和 IM,任何情况下都不行。据 Mozilla 的 TLS 配置建议与各 CA 的订阅者协议,私钥泄露的责任归属首先看交付链路是否可控。
| 对象 | 推荐渠道 | 交付物 | 轮换方式 |
|---|---|---|---|
| 内部服务器 | Ansible/配置管理或 K8s Secret 挂载 | PEM 证书 + 私钥 | cert-manager / Vault Agent 自动重载 |
| 员工设备 | MDM 下发 | .pfx(含私钥,受设备密钥库保护) | MDM 策略推送,随设备清单回收 |
| 合作方 | 带一次性令牌的下载链接 | .pfx + 初始密码 | 令牌一次性、链接限时,首次使用强制改密码 |
吊销了证书,为什么对方还能握手成功?
这是 SSL双向认证配置里最反直觉的一环:吊销并不立即生效。原因有三——CRL 本身有 nextUpdate 缓存周期(RFC 5280 第 5 节允许 CA 设定刷新间隔);Nginx 读取 CRL 文件后需 reload 才重新加载;TLS 会话复用会让老会话直接跳过完整的证书校验。把这三处收紧,收敛时间可从数十分钟压到分钟级:
# Nginx 1.19.0+ 开源版才支持 ssl_crl;更早版本该指令属 NGINX Plus 专有
ssl_client_certificate /etc/nginx/ca.crt;
ssl_crl /etc/nginx/ca.crl;
ssl_verify_client on; # 默认 off
ssl_session_timeout 1m; # 默认 5m,缩短以加快吊销收敛
ssl_session_tickets off; # 默认 on,关掉防止票据绕过证书校验
验证吊销是否真的生效,别只看浏览器,用 OpenSSL 直接查:
openssl verify -crl_check -CAfile ca.crt -CRLfile ca.crl client.crt
# 已吊销:error 23 at 0 depth lookup: certificate revoked
# CRL 过期:error 12 at 0 depth lookup: CRL has expired
Nginx 侧对应会在 error.log 留下 client SSL certificate verify error: (23:certificate revoked),把这个字符串接入日志告警即可。
上线后盯哪几个指标,才能在用户报障前发现问题?
至少三个,任一异常都意味着 SSL双向认证配置正在退化:
- 剩余天数:
openssl x509 -checkend 2592000 -noout -in client.crt || echo "30天内到期"(2592000 秒 = 30 天),配合openssl x509 -enddate -noout -in client.crt输出notAfter=做看板。 - 校验失败比例:在
log_format中加入$ssl_client_verify,统计非SUCCESS(即FAILED:...与NONE)的占比,突增通常意味着某批证书被误删或 CA 链不匹配。 - CRL 新鲜度:
openssl crl -in ca.crl -noout -lastupdate -nextupdate,一旦nextUpdate已过,校验行为将不可预期,必须把 CRL 生成任务本身也纳入监控。
SSL双向认证配置在 API 网关、Java 与容器环境中的延伸
问:Spring Boot 3.x 如何开启 SSL双向认证配置?在 application.yml 中把 server.ssl.client-auth 设为 need,并显式指定信任库;该属性默认值为 none,可选 none / want / need。据 Spring Boot 官方文档,want 表示“请求但不对缺失证书强制拦截”,适合灰度迁移。
server:
port: 8443
ssl:
enabled: true
key-store: classpath:server.p12
key-store-password: changeit
key-store-type: PKCS12
client-auth: need # 默认 none;灰度期可改 want
trust-store: classpath:ca.p12 # 校验客户端证书的 CA
trust-store-password: changeit
trust-store-type: PKCS12
| client-auth | 行为 | 适用场景 |
| none(默认) | 不请求客户端证书 | 普通 HTTPS |
| want | 请求证书,缺失也放行;有证书则校验 | 灰度、兼容旧客户端 |
| need | 必须提供有效证书,否则 TLS 握手失败 | API 网关、服务间强认证 |
配合 Spring Security 的 X509AuthenticationFilter,可用 subjectPrincipalRegex 从证书主题中提取 CN 作为身份,例如默认匹配 CN=(.*?)(?:,|$),无需再解析请求头。
问:Java 客户端调用时为什么总报 PKIX path building failed?因为客户端只带了密钥库、没带信任库。先用 keytool 导入服务端 CA,再在启动参数中同时指定 keyStore 与 trustStore:
keytool -importcert -alias ca -file ca.crt
-keystore truststore.p12 -storetype PKCS12
-storepass changeit -noprompt
java -Djavax.net.ssl.keyStore=client.p12
-Djavax.net.ssl.keyStorePassword=changeit
-Djavax.net.ssl.keyStoreType=PKCS12
-Djavax.net.ssl.trustStore=truststore.p12
-Djavax.net.ssl.trustStorePassword=changeit
-jar app.jar
缺 trustStore 会报 PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target;缺 keyStore 则服务端返回 400 No required SSL certificate was sent。四个参数缺一不可。
问:Kubernetes 里如何复现同等 SSL双向认证配置?ingress-nginx 用三个注解即可,auth-tls-verify-depth 默认值为 1,链较深时调到 2:
metadata:
annotations:
nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret" # 含 ca.crt
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "2"
据 ingress-nginx 文档,校验结果通过 X-Client-Verify: SUCCESS、X-Client-DN、X-Client-Cert 传给后端;失败时网关直接返回 400,后端不会收到请求。
问:Istio 中还需要手工配客户端证书吗?工作负载之间不需要。把 PeerAuthentication 的 mtls.mode 设为 STRICT(未设置时通常继承为 PERMISSIVE),istiod 会自动签发并默认每 24 小时轮换证书,因此无需手工维护 CRL;但边界网关仍应保留客户端证书校验。
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
name: default
namespace: shop
spec:
mtls:
mode: STRICT
双向认证常与 HSTS、TLS 1.3(RFC 8446)、OCSP Stapling、证书链完整性出现在同一份加固清单里;服务端证书的 CSR 生成、中间链拼接与单向校验,是配置双向认证前必须先跑通的基础。
三条就够:ssl_client_certificate 指向签发客户端证书的 CA 证书链、ssl_verify_client on 强制校验、ssl_verify_depth 设为链长(有中间 CA 时用 2,默认值是 1)。再加上 ssl_crl 才能支持吊销,加上 ssl_session_tickets off 才能让吊销及时生效。
说明 ssl_verify_client 已设为 on,但客户端在握手时没有提交证书。常见原因有三种:客户端没导入证书、导入的是 .crt 而缺少私钥、服务端下发的可接受 CA 列表与客户端证书的签发者不匹配。用 openssl s_client 查看 Acceptable client certificate CA names 可快速定位。
两者不在同一层:mTLS 在 TLS 握手阶段完成身份校验,适合服务间调用、设备接入和 B 端合作方,凭证泄露风险低但无法表达细粒度权限;JWT/OAuth2 在应用层传递声明,适合用户态与权限编排。生产常见做法是外层 mTLS 保证通道与调用方身份,内层再用 JWT 做授权。
先确认证书已导入系统「个人」证书库且带私钥:Windows 用 .pfx 双击导入,macOS 在钥匙串中把信任设为始终信任。其次确认证书的 extendedKeyUsage 含 clientAuth,并检查是否过期。最后在 chrome://settings/certificates 中查看该证书是否被识别为客户端证书。
不需要重启,但需要客户端换新证书。服务端只在启动或 reload 时加载 ssl_client_certificate 与 ssl_crl,因此换 CA 或更新 CRL 后执行 nginx -t 再 systemctl reload nginx 即可。已建立的会话可能因 ssl_session_timeout(默认 5m)继续存活一段时间。
主流云厂商的七层负载均衡都支持:在 HTTPS 监听上开启双向认证并上传 CA 证书即可,吊销依赖平台侧的 CRL 更新,粒度不如自建灵活。自建 Nginx 的优势是可用 $ssl_client_s_dn、$ssl_client_serial 等变量做精细路由与审计,缺点是 CRL 与轮换要自己维护。
额外开销主要来自一次客户端证书的签名验签,RSA 2048 下通常是毫秒级,相对网络 RTT 可以忽略。真正影响性能的是会话复用被关闭:为保证吊销生效设置 ssl_session_tickets off 后,长连接复用率下降,建议配合 ssl_session_cache shared:SSL:10m 缓解。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。