Nginx原生不支持基于TLS证书指纹的白名单，但可通过OpenResty+Lua或新版Nginx（≥1.19.7）的$ssl_client_fingerprint变量结合map模块实现等效控制，前提为启用mTLS并校验客户端证书。
在 Nginx 中无法直接基于 TLS 证书指纹（如 SHA-256 Fingerprint）配置白名单来控制访问——Nginx 的标准模块不支持在运行时提取并比对客户端证书的指纹。但可通过组合使用 客户端证书双向认证（mTLS） 和 OpenSSL 命令预生成指纹 + Nginx 变量匹配 的方式，实现等效的“证书指纹级严格准入”。关键在于：将指纹校验逻辑前置到证书验证阶段，并利用 Nginx 的 $ssl_client_fingerprint（需 patch 或新版支持）或更通用可靠的 $ssl_client_raw_cert + Lua/OpenResty 方案。
前提：启用并强制双向 TLS 认证
只有启用 mTLS，Nginx 才能获取客户端证书原始内容，这是后续提取指纹的基础：
- 配置受信任的 CA 证书（
ssl_client_certificate），用于验证客户端证书签名有效性 - 开启证书验证要求（
ssl_verify_client on或optional_no_ca仅用于调试） - 确保客户端实际提供证书（浏览器、curl、内部服务需正确配置 client cert + key）
方案一：使用 OpenResty + Lua 提取并比对指纹（推荐、可靠）
OpenResty 内置 OpenSSL 绑定，可在 access 阶段实时计算客户端证书指纹并与白名单比对：
- 安装 OpenResty（替代原生 Nginx），启用
lua_ssl_trusted_certificate和lua_ssl_ciphers - 在 server 块中使用
access_by_lua_block：
access_by_lua_block {
local ssl = require "ngx.ssl"
local openssl_x509 = require "openssl.x509"
local digest = require "openssl.digest"
<pre class="brush:php;toolbar:false;">local raw_cert = ngx.var.ssl_client_raw_cert
if not raw_cert or #raw_cert == 0 then
ngx.exit(403)
end
local x509, err = openssl_x509.read(raw_cert, "pem")
if not x509 then
ngx.log(ngx.ERR, "failed to parse cert: ", err)
ngx.exit(403)
end
local der = x509:to_der()
local fp = digest.new("sha256"):update(der):final()
local fp_hex = string.gsub(fp, "(..)", "%1:"):sub(1, -2) -- 格式如 A1:B2:...:F0
local whitelist = {
["A1:B2:C3:...:F0"] = true,
["D4:E5:F6:...:A9"] = true,
}
if not whitelist[fp_hex] then
ngx.log(ngx.WARN, "rejected cert fingerprint: ", fp_hex)
ngx.exit(403)
end
}
方案二：用 Nginx 变量 + map 模块（需 Nginx ≥ 1.19.7 + OpenSSL ≥ 3.0）
较新版本 Nginx 支持 $ssl_client_fingerprint（SHA-256，默认十六进制无分隔符），可结合 map 实现静态白名单：
- 确认编译时启用了
--with-http_ssl_module且 OpenSSL ≥ 3.0 - 在 http 块中定义指纹映射：
map $ssl_client_fingerprint $allowed_client {
default 0;
"a1b2c3...f0" 1; # 注意：此处为小写无冒号 SHA256 值
"d4e5f6...a9" 1;
}- 在 location 中限制访问：
location /internal/ {
if ($allowed_client = 0) {
return 403;
}
# 后续代理或处理逻辑
}补充：如何提前获取合法证书的指纹
供运维人员生成白名单值，避免线上试错：
- 从 PEM 文件提取（推荐）：
openssl x509 -in client.crt -noout -fingerprint -sha256 | sed 's/://g' | awk -F'=' '{print tolower($2)}' - 从已建立连接的 Nginx 日志中临时记录（调试用）：
log_format debug "$ssl_client_fingerprint | $ssl_client_s_dn"; - 注意区分指纹来源：务必使用证书主体（Subject）对应公钥的 DER 编码 SHA256，而非私钥或 CSR
不复杂但容易忽略：指纹白名单本质是强化 mTLS 的细粒度控制，它不能替代 CA 信任链校验，而是叠加在可信证书之上的二次身份精筛。只要确保 CA 签发环节可控、客户端证书生命周期管理到位，该机制即可成为内部系统间零信任通信的有效实践。
