nginx 通过启用 mtls 并配置 ssl_verify_client on、ssl_client_certificate 等指令，在 location 块中用 proxy_set_header 透传 $ssl_client_escaped_cert 等变量实现客户端证书安全传递。
要在 Nginx 中通过 nginx.conf 配置代理服务透传客户端证书，关键不是“转发原始证书”，而是启用双向 TLS（mTLS），由 Nginx 完成客户端证书校验后，再将验证结果和安全编码的证书内容以 HTTP 头形式传递给后端。整个过程依赖正确配置、变量可用性及头字段安全性。
必须开启并确保客户端证书校验生效
透传的前提是 Nginx 成功验证了客户端证书。否则所有相关变量为空，后端收不到任何有效信息。
-
ssl_verify_client on; —— 必须启用，不可用
optional或省略 - ssl_client_certificate /path/to/ca-bundle.crt; —— 指向可信 CA 的 PEM 格式公钥文件（权限应为 644，不能含私钥）
- ssl_certificate 和 ssl_certificate_key —— 已正确配置服务端证书与私钥
- Nginx 版本需 ≥ 1.19.7 —— 否则
$ssl_client_escaped_cert不可用
在 location 块中设置 proxy_set_header 透传关键信息
所有 proxy_set_header 指令必须写在具体的 location 块内（如 location /api/ { ... }），不能放在 http 或 server 全局块中，否则变量无法解析。
- X-Client-Cert-Escaped: $ssl_client_escaped_cert —— 唯一安全传递完整证书的方式（URL 编码，避免换行符破坏 header）
-
X-Client-Verify: $ssl_client_verify —— 返回
SUCCESS/FAILED/NONE，后端据此判断是否信任 - X-Client-DN: $ssl_client_s_dn —— 主题可读名（已自动转义，相对安全）
- X-Client-CN: $ssl_client_s_dn_cn —— 仅提取 CN 字段，轻量且无格式风险
避免常见配置错误
这些看似合理但实际无效或危险的做法要避开：
- 使用
$ssl_client_cert直接赋值给 header —— 因含换行符和空格，HTTP 协议不支持，会导致 header 截断或请求失败 - 未启用
ssl_verify_client on就引用证书变量 —— 变量始终为空，后端收不到任何值 - CA 文件路径错误、权限设为 600、或混入私钥/多余空行 —— 造成校验静默失败（Nginx 不报错，但
$ssl_client_verify恒为NONE） - 把透传配置写在非 HTTPS 的 server 块下 —— mTLS 只在启用了 SSL 的上下文中有效
后端需配合解码与校验
透传只是第一步，后端必须主动处理：
- 收到
X-Client-Cert-Escaped后，用对应语言解码：Python 用urllib.parse.unquote()，Node.js 用decodeURIComponent() - 检查
X-Client-Verify是否为SUCCESS，拒绝FAILED或NONE的请求 - 建议结合
X-Client-Fingerprint（需 Nginx ≥ 1.19.0）做白名单校验，增强安全性
