在 Nginx 中实现 HMAC 验签，最稳妥的方案是基于 OpenResty 搭配 lua-resty-string 库，在 access_by_lua 阶段完成计算与比对。这适合需要高性能网关鉴权的场景。
先说结论：使用 OpenResty 的 lua-resty-string 模块处理加密运算，配合 access_by_lua 拦截请求，是兼顾性能与维护性的做法。
- 先判断：确认 Nginx 已编译 lua 模块且可加载 resty 库
- 优先做：在 Lua 脚本中统一构建签名字符串，避免前后端规则不一致
- 再验证：通过 curl 携带签名头请求，观察日志与状态码
完整配置示例
以下配置展示了如何在 http 块加载模块，并在 location 中集成验签逻辑。注意密钥不要硬编码，生产环境建议使用环境变量或配置中心。
http {lua_package_path "/usr/local/openresty/lualib/?.lua;;";server {location /api/ {access_by_lua_block {-- 引入依赖local hmac = require "resty.hmac"local str = require "resty.string"local ngx_var = ngx.var-- 1. 获取请求头参数，防止 nil 报错local timestamp = ngx_var.http_x_timestamplocal client_sign = ngx_var.http_x_signatureif not timestamp or not client_sign thenngx.log(ngx.ERR, "missing timestamp or signature")return ngx.exit(403)end-- 2. 检查时间戳过期 (假设允许 5 分钟误差)local now = ngx.time()if math.abs(now - tonumber(timestamp)) > 300 thenngx.log(ngx.ERR, "timestamp expired")return ngx.exit(403)end-- 3. 构建待签名字符串 (必须与客户端一致)local str_to_sign = ngx_var.request_method .. ":" .. ngx_var.uri .. ":" .. timestamplocal secret = "your_secret_key" -- 生产环境请替换为动态获取-- 4. 计算 HMAC SHA256local hm = hmac:new(secret, hmac.ALG_SHA256)hm:update(str_to_sign)local sign_binary = hm:final()-- 5. 转为 hex 并比对 (关键步骤：binary 转 hex)local server_sign = str.to_hex(sign_binary)if server_sign ~= client_sign thenngx.log(ngx.ERR, "signature mismatch")return ngx.exit(403)end}proxy_pass http://backend;}}
}客户端签名生成脚本
为了验证 Nginx 配置，可以使用以下 Python 脚本生成合法的签名头。确保待签名字符串拼接规则与 Nginx 端完全一致。
import hmac
import hashlib
import timesecret = "your_secret_key"
timestamp = str(int(time.time()))
method = "GET"
uri = "/api/test"# 构建待签名字符串
str_to_sign = f"{method}:{uri}:{timestamp}"# 计算 HMAC SHA256
signature = hmac.new(secret.encode(), str_to_sign.encode(), hashlib.sha256).hexdigest()print(f"X-Timestamp: {timestamp}")
print(f"X-Signature: {signature}")
# 使用示例：curl -H "X-Timestamp: {timestamp}" -H "X-Signature: {signature}" http://your-domain.com/api/test验证与排查
使用 curl 命令模拟携带签名的请求，并观察 Nginx 错误日志。
curl -H "X-Timestamp: 1700000000" -H "X-Signature: 计算出的 hex 值" http://your-domain.com/api/test观察 Nginx 错误日志（通常位于 /usr/local/openresty/nginx/logs/error.log）。如果验签失败，应看到自定义的日志记录；如果验签成功，请求应正常返回 200 状态码。也可以故意篡改签名值，确认是否返回 403。
常见坑
- 时间同步：客户端与服务端时间偏差过大会导致验签失败。通常允许±5 分钟误差，需在 Lua 脚本中做时间差判断。
- 字符串构建规则：前后端构建“待签名字符串”的顺序必须完全一致（例如参数是否排序、是否包含查询字符串）。一致性是生效的前提。
- 密钥安全：密钥不能明文写在代码库里。如果 Nginx 配置被泄露，密钥也会泄露。建议结合 IP 白名单或定期轮换密钥。
- HTTPS 强制：签名本身不加密传输内容。如果通过 HTTP 传输，签名和密钥可能被中间人截获。务必在 Nginx 层强制跳转 HTTPS。
参考来源
- OpenResty 官方文档，页面标题：OpenResty® - Official Site，URL：https://openresty.org/
- lua-resty-string 项目仓库，页面标题：openresty/lua-resty-string，URL：https://github.com/openresty/lua-resty-string
原文链接：https://www.zjcp.cc/ask/11355.html