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

SSL双向认证配置实战:用 OpenSSL 3 与 Nginx 1.24 校验客户端证书

ssl双向认证配置 — 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. 步骤 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. 步骤 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. 步骤 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. 步骤 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. 步骤 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. 步骤 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。所以验证必须”正反各一次 + 日志 + 握手细节”四条腿走路,任何一条缺失都可能把故障留到上线后。

方法 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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