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 | |
- 弹出的对话框由
auth_basic的提示语决定; - 账号密码存在
auth_basic_user_file,格式为user:encrypted-password; - 密码用
htpasswd生成(Apache 工具包),支持-B(bcrypt)等;没有htpasswd时可用openssl passwd -apr1生成 APR1 哈希。
1 | |
安全提醒:basic auth 的凭证是 Base64,必须配合 HTTPS,否则等于明文传输;口令文件权限设为仅 Nginx 可读。
二、satisfy:多种条件的组合
当同一 location 同时有 IP 白名单和口令(或 auth_request)时,satisfy 决定是"都满足"还是"任一满足":
1 | |
all(默认):所有启用的访问控制都要通过;any:任一通过即可,常用于"内网免口令、外网要口令";- 与
auth_request组合时,satisfy同样生效。
三、auth_jwt:商业版的 JWT 校验
商业版(NGINX Plus)内置 ngx_http_auth_jwt_module,可直接校验 JWT:
1 | |
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 | |
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 | 可被外部直接访问,绕过校验 |
参考链接
- Nginx 官方文档:ngx_http_auth_basic_module —— 本地口令;
- Nginx 官方文档:ngx_http_core_module(satisfy) —— 组合条件;
- Nginx 官方文档:ngx_http_auth_jwt_module —— 商业版 JWT 指令;
- Nginx 官方文档:ngx_http_js_module —— njs 扩展;
- 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
