Nginx 工程实践 -- 19. 本地口令与 JWT 鉴权

第 2 篇用 auth_request 把鉴权交给后端。但很多场景只需要网关自己判断:后台面板用一个简单口令、Open API 用 JWT。Nginx 原生提供 auth_basic 本地口令,商业版提供 auth_jwt,开源版则可用 njs 自己校验 JWT。这篇覆盖这三条路,以及它们如何与 allow/deny 组合。

flowchart TD
    A["请求"] --> B{"satisfy"}
    B -->|"auth_basic"| C{"校验 htpasswd"}
    B -->|"auth_request / JWT"| D{"校验通过?"}
    C -->|"通过"| E["放行"]
    D -->|"通过"| E
    C -->|"失败"| F["401 + WWW-Authenticate"]
    D -->|"失败"| F

一、auth_basic:本地口令

1
2
3
4
location /admin/ {
auth_basic "Admin Area";
auth_basic_user_file /etc/nginx/.htpasswd;
}
  • 弹出的对话框由 auth_basic 的提示语决定;
  • 账号密码存在 auth_basic_user_file,格式为 user:encrypted-password;
  • 密码用 htpasswd 生成(Apache 工具包),支持 -B(bcrypt)等;没有 htpasswd 时可用 openssl passwd -apr1 生成 APR1 哈希。
1
htpasswd -c -B /etc/nginx/.htpasswd alice

安全提醒:basic auth 的凭证是 Base64,必须配合 HTTPS,否则等于明文传输;口令文件权限设为仅 Nginx 可读。

二、satisfy:多种条件的组合

当同一 location 同时有 IP 白名单和口令(或 auth_request)时,satisfy 决定是"都满足"还是"任一满足":

1
2
3
4
5
6
7
8
9
10
location /admin/ {
allow 10.0.0.0/8;
deny all;

auth_basic "Admin Area";
auth_basic_user_file /etc/nginx/.htpasswd;

satisfy all; # IP 与口令都要过
# satisfy any; # 任一过即可
}
  • all(默认):所有启用的访问控制都要通过;
  • any:任一通过即可,常用于"内网免口令、外网要口令";
  • 与 auth_request 组合时,satisfy 同样生效。

三、auth_jwt:商业版的 JWT 校验

商业版(NGINX Plus)内置 ngx_http_auth_jwt_module,可直接校验 JWT:

1
2
3
4
5
6
7
location /api/ {
auth_jwt "API Gateway";
auth_jwt_key /etc/nginx/jwt_key.pem;
auth_jwt_algorithm RS256;
# 从 Authorization: Bearer 取 token
auth_jwt_token $http_authorization;
}
  • auth_jwt_key 支持 PEM 密钥或 JWK 集(auth_jwt_key_request 可指向 JWKS 地址);
  • auth_jwt_require 可校验 exp、nbf、iss、sub、aud 等声明;
  • 开源版没有这些指令。

四、开源版用 njs 校验 JWT

开源版可以用 njs(ngx_http_js_module)在校验阶段解析并验证 JWT。核心是拆分 header.payload.signature,用 crypto 验签,再检查 exp:

1
2
3
4
5
6
7
8
9
10
11
js_import /etc/nginx/jwt.js;

location /api/ {
auth_request /_jwt;
error_page 401 = @fallback;
}

location = /_jwt {
internal;
js_content jwt.verify;
}

jwt.js 里用 crypto.createVerify(RS256)或 crypto.createHmac(HS256)验签,失败就返回 401。注意:

  • njs 是受限 JS 运行时,只能用官方提供的 API,不能 npm install 任意库;
  • HS256 的密钥不要放在配置文件里,用 js_var 或环境注入;
  • 验签通过后,把用户信息写入 X-User 等头传给后端(auth_request_set)。

五、常见坑

坑说明
basic auth 走 HTTP凭证明文,必须 HTTPS
用 openssl passwd 生成格式不对确认 Nginx 支持的哈希类型(APR1/bcrypt 等)
satisfy any 与 deny all 同用逻辑容易绕晕,先画清"谁免检"
JWT 只验签不验 exp过期 token 仍可用,必须检查时效
开源版找 auth_jwt该指令是商业版功能,开源版用 njs
JWT 密钥硬编码用 js_var 或密钥服务注入
auth_request 子请求未 internal可被外部直接访问,绕过校验

参考链接

  1. Nginx 官方文档:ngx_http_auth_basic_module —— 本地口令;
  2. Nginx 官方文档:ngx_http_core_module(satisfy) —— 组合条件;
  3. Nginx 官方文档:ngx_http_auth_jwt_module —— 商业版 JWT 指令;
  4. Nginx 官方文档:ngx_http_js_module —— njs 扩展;
  5. Nginx 官方文档:ngx_http_auth_request_module —— 子请求鉴权(见第 2 篇)。

小结

  • auth_basic + htpasswd 适合简单口令,必须配 HTTPS;
  • satisfy all/any 决定多种访问控制的组合逻辑;
  • JWT:商业版用 auth_jwt,开源版用 njs 自验签;
  • JWT 必须验签 + 验 exp,密钥不要硬编码;
  • auth_request 子请求记得 internal。

系列导航


Nginx 工程实践 -- 19. 本地口令与 JWT 鉴权
https://bubao.github.io/posts/d9e0f1a2.html
作者
一念
发布于
2026年11月21日
许可协议