Nginx auth_request 是官方 http_auth_request 模块提供的子请求鉴权机制:每个进入受保护 location 的请求,Nginx 会先向一个内部地址发起一次子请求,由鉴权服务决定放行还是拒绝,鉴权通过后还能把用户身份透传给后端。它把「谁能访问」从每个业务应用里抽出来,收敛到网关一层,适合有多个异构后端、又不想逐个改代码的场景。
适用场景
- 同一域名下挂了 Java、PHP、静态站点、内部工具等多个后端,登录逻辑各写一套,账号体系无法统一;
- 老系统没有鉴权能力且短期内无法改代码,需要在不侵入业务的前提下加一道门;
- 管理后台、监控面板、内部 API 只允许特定人群访问,但不想暴露在公网靠密码硬扛;
- 需要按 URI 粒度做权限控制,例如
/admin/要求管理员角色,/api/只要求登录态; - 希望把鉴权日志与访问日志分开统计,便于发现越权探测行为。
前置条件
- Nginx 编译时包含
http_auth_request_module,官方软件包默认内置,源码编译需显式加--with-http_auth_request_module; - 有一个可用的鉴权服务,本文示例用 Python 标准库实现的极简服务,生产可换成 Go、Java 或现成的 oauth2-proxy;
- 后端应用能够读取自定义请求头,用于接收鉴权结果中的用户标识;
- 具备修改 Nginx 配置的 sudo 权限,改动前备份:
cp -a /etc/nginx /etc/nginx.bak.$(date +%F); - 明确鉴权服务故障时的策略:默认拒绝(fail-close)还是放行(fail-open),这个决定必须在上线前定下来。
原理说明
auth_request 的工作方式很直接:受保护的 location 里写一行 auth_request /_auth;,Nginx 就把当前请求的方法、URI、请求头复制一份,作为子请求发给 /_auth 这个内部 location,然后只看子请求返回的状态码——2xx 放行,401 或 403 拒绝并把该状态码返回给客户端,其他状态码一律当作 500 处理。
有三个行为特征必须理解,否则很容易踩坑。第一,子请求不携带请求体,这是设计使然:上传接口的鉴权只能基于请求头、Cookie 与 URI,不能基于表单内容。第二,子请求的响应头可以被提取——通过 auth_request_set 可以把 X-User 这类头写入变量,再 proxy_set_header 传给后端,这样后端不必自己解析 JWT 就能拿到已认证的用户名。第三,Nginx 对 auth_request 结果没有内置缓存,每个请求都会触发一次子请求,在高并发下鉴权服务就是新的瓶颈,必须靠 proxy_cache 或鉴权服务自身缓存来兜。
另一个容易被忽略的点是鉴权失败与鉴权异常的区别。401 应该引导登录,403 应该直接拒绝并记录,而鉴权服务 5xx 意味着「无法判断」,此时按默认策略会全部变成 500,站点整体不可用。这也是 fail-open 与 fail-close 之争的由来:安全优先就接受不可用,可用性优先就接受风险窗口,没有两全方案。
操作步骤
第一步:确认模块可用
# 确认编译参数中含 auth_request 模块
nginx -V 2>&1 | tr ' ' '\n' | grep auth_request
# 无输出说明模块缺失:Debian/Ubuntu 安装 nginx-extras 或官方源
# apt install -y nginx-extras
# 源码编译时需显式添加:--with-http_auth_request_module
# 备份配置
cp -a /etc/nginx /etc/nginx.bak.$(date +%F)
模块缺失时配置里的 auth_request 会直接报 unknown directive,属于启动即失败,不会静默降级,这一点比很多第三方模块友好。确认可用后继续。
第二步:编写鉴权服务
下面是一个只依赖标准库的极简实现,逻辑是校验 Cookie 中的会话令牌,命中则返回 204 并带上用户标识,未命中返回 401。生产环境应把会话存储换成 Redis,并加上过期与吊销逻辑:
# /opt/authsvc/auth.py — 最小可用鉴权服务
from http.server import BaseHTTPRequestHandler, HTTPServer
SESSIONS = {"sess-abc123": "alice", "sess-def456": "bob"}
class Handler(BaseHTTPRequestHandler):
def do_GET(self):
cookie = self.headers.get("Cookie", "")
token = ""
for part in cookie.split(";"):
k, _, v = part.strip().partition("=")
if k == "sid":
token = v
user = SESSIONS.get(token)
if not user:
self.send_response(401)
self.send_header("WWW-Authenticate", 'Cookie realm="site"')
self.end_headers()
return
self.send_response(204)
self.send_header("X-User", user)
self.end_headers()
def log_message(self, fmt, *args):
print("%s %s" % (self.address_string(), fmt % args))
HTTPServer(("127.0.0.1", 9000), Handler).serve_forever()
服务只监听 127.0.0.1,绝不监听 0.0.0.0——鉴权服务本身一旦暴露,等于把门钥匙挂在门外。启动方式建议交给 systemd 托管,配置 Restart=always 与内存上限,避免被突发流量拖垮整机。
第三步:配置 Nginx 子请求与身份透传
# /etc/nginx/conf.d/auth-gateway.conf
server {
listen 443 ssl;
server_name app.example.com;
# 内部鉴权端点,internal 保证外部无法直接访问
location = /_auth {
internal;
proxy_pass http://127.0.0.1:9000/verify;
# 子请求不带 body,显式关闭并清空长度头
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Original-Method $request_method;
proxy_set_header X-Real-IP $remote_addr;
# 超时必须短,避免鉴权服务拖死整个站点
proxy_connect_timeout 1s;
proxy_read_timeout 2s;
# 缓存鉴权结果:key 用会话 Cookie,10 秒内不重复请求
proxy_cache auth_cache;
proxy_cache_key "$cookie_sid$uri";
proxy_cache_valid 200 204 10s;
proxy_cache_valid 401 403 5s;
proxy_ignore_headers Set-Cookie;
}
# 受保护的业务入口
location / {
auth_request /_auth;
auth_request_set $auth_user $upstream_http_x_user;
proxy_set_header X-Auth-User $auth_user;
proxy_set_header X-Real-IP $remote_addr;
# 鉴权失败分流:401 去登录页,403 留在原地
error_page 401 = @to_login;
proxy_pass http://127.0.0.1:8080;
}
location @to_login {
return 302 /login?next=$request_uri;
}
}
# 放在 http 上下文,与 proxy_cache_path 一起定义
proxy_cache_path /var/cache/nginx/auth levels=1:2 keys_zone=auth_cache:10m
max_size=64m inactive=60s use_temp_path=off;
这里有两处需要重点确认。第一,proxy_cache_key 必须包含会话凭据,否则缓存会把 A 用户的放行结果套用到 B 用户身上,形成越权——这是 auth_request 上线事故里最常见的一类。第二,proxy_cache_valid 401 403 5s 让拒绝结果也短时缓存,可以挡住针对鉴权接口的暴力探测,但取值不宜过大,否则用户登录成功后仍会被旧缓存挡住。
第四步:按 URI 做分级权限
不同路径要求不同角色时,不要复制多份鉴权配置,用鉴权服务读 X-Original-URI 判断更清晰。也可以按前缀拆 location,各自指向不同鉴权端点,互不干扰:
# 只允许管理员访问的后台路径
location /admin/ {
auth_request /_auth_admin;
auth_request_set $auth_user $upstream_http_x_user;
proxy_set_header X-Auth-User $auth_user;
proxy_pass http://127.0.0.1:8080;
}
location = /_auth_admin {
internal;
proxy_pass http://127.0.0.1:9000/verify_admin;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
# 静态资源不鉴权,减少子请求次数
location ~* \.(css|js|png|jpg|woff2)$ {
root /var/www/static;
expires 7d;
}
把静态资源排除在外是必要优化。一个页面通常带十几个静态文件,如果每个都触发子请求,鉴权服务的 QPS 会被放大十几倍,而这些资源本身并不敏感。
第五步:验证鉴权链路
配置写完先测语法,再用四组请求逐一验证放行、拒绝、身份透传与登录跳转:
# 1. 语法检查与重载
nginx -t && nginx -s reload
# 2. 无凭证:应返回 401 并被 302 到登录页
curl -sI https://app.example.com/ | head -3
# 3. 无效凭证:应为 401
curl -sI -H 'Cookie: sid=bad-token' https://app.example.com/ | head -1
# 4. 有效凭证:应为 200
curl -sI -H 'Cookie: sid=sess-abc123' https://app.example.com/ | head -1
# 5. 确认身份已透传到后端(后端需回显 X-Auth-User)
curl -s -H 'Cookie: sid=sess-abc123' https://app.example.com/whoami
第 5 步是很多人漏掉的一步:401 与 200 都对,但后端拿到的 X-Auth-User 是空的,原因是 auth_request_set 里的变量名写错,或鉴权服务返回的是 200 而非 204 且未带该响应头。必须实际打到后端验证,不能只看前端状态码。
第六步:压测确认缓存生效
auth_request 的性能风险必须量化后再上线。用 hey 或 ab 打一轮,对比开关缓存前后的差异,同时观察鉴权服务的连接数:
# 200 并发,持续 20 秒,带固定 Cookie
hey -z 20s -c 200 -H 'Cookie: sid=sess-abc123' https://app.example.com/ > /tmp/hey.log
grep -E 'Requests/sec|Status code distribution' -A 3 /tmp/hey.log
# 观察鉴权服务实际收到的请求量(缓存生效时应远小于总请求数)
ss -tn state established '( dport = :9000 )' | wc -l
# 命中率:Nginx 侧看 upstream_cache_status 是否被记录
grep -c 'HIT' /var/log/nginx/access.log
如果 Requests/sec 上不去而鉴权服务 CPU 打满,说明缓存没命中,优先检查 proxy_cache_key 是否包含了一个每次都变的变量(例如把 $request_id 写进了 key)。缓存命中后,鉴权服务的实际请求量应稳定在总请求量的百分之几。
第七步:确定故障降级策略
鉴权服务挂掉时,默认行为是整个站点 500。若业务无法接受,可以用 map 结合上游状态做有限放行,但要清楚这会打开一个风险窗口:
# http 上下文:鉴权服务异常时是否放行,默认 0 表示不放行
map $upstream_status $auth_fail_open {
default 0;
"502" 1;
"504" 1;
}
# 受保护 location 中改为:异常时内部重定向到「仅记录不拦截」的旁路
error_page 500 502 504 = @auth_degraded;
location @auth_degraded {
# 记录异常并放行只读请求,写操作仍然拒绝
access_log /var/log/nginx/auth_degraded.log json_access;
limit_except GET HEAD { deny all; }
proxy_pass http://127.0.0.1:8080;
}
这段配置的取舍必须写进变更记录:它让「鉴权服务故障期间,只读请求仍可访问」,代价是这段时间内权限校验失效。对内部工具可以接受,对涉及资金或个人信息的系统不应启用。无论选哪种,都要给鉴权服务加存活告警,把故障窗口压到分钟级。
配置验证
nginx -t通过,reload 后 worker 全部更换;- 无 Cookie 请求返回 401 并按
error_page跳转登录页;无效令牌同为 401,不泄露「用户是否存在」; - 有效令牌返回 200,且后端实际收到
X-Auth-User非空; /_auth从公网直接访问返回 404(internal生效);- 压测中鉴权服务接收请求量明显低于总请求量,说明缓存命中;
- 不同 Cookie 之间缓存不串号:用两个账号交叉请求,返回的用户名各自正确;
- 把鉴权服务停掉,站点按既定策略表现(整体 500 或只读放行),与变更记录一致。
常见问题
Q1:上传接口加了 auth_request 后,后端收不到文件了?
不是配置错误,而是机制限制:auth_request 的子请求不携带请求体,Nginx 也不会因为鉴权而改变主请求的 body 转发。真正的问题通常出在两处。一是鉴权服务读取了 Content-Length 或等待 body 导致超时,被判定为 5xx,请求被拦。解决办法是鉴权端点只依据 Cookie、URI 与方法判断,并在 Nginx 侧对 /_auth 设置 proxy_pass_request_body off。二是 client_max_body_size 未放开,大文件在主请求阶段就被 413 拒绝,与鉴权无关。
Q2:为什么两个用户用同一个 URL 访问,返回的用户身份却串了?
几乎必然是缓存键设计错误。proxy_cache_key 里如果没有包含会话凭据($cookie_sid、Authorization 头的哈希等),Nginx 就会把「同一 URI」的鉴权结果复用给所有人。修复方式是把凭据纳入 key,并对凭据做归一化处理,例如 proxy_cache_key "$cookie_sid$uri$request_method";同时检查是否有 proxy_ignore_headers Set-Cookie 之外的配置覆盖了 key。上线前务必做双账号交叉验证,这类越权一旦发生就是数据事故。
Q3:auth_request 与 WAF 谁在前面?会不会重复拦截?
顺序应是 WAF 在前、auth_request 在后。WAF 负责拦恶意 payload 与 CC,鉴权负责判断身份,两者职责不重叠,也不存在重复拦截的问题。若鉴权放在 WAF 之前,未认证的扫描流量会先打到鉴权服务,白白消耗连接与 CPU。另外要注意:如果 WAF 会改写或丢弃 Cookie,鉴权会大面积失败,上线前需在 WAF 侧对会话 Cookie 做放行验证。
总结
auth_request 的价值在于把鉴权从业务代码里剥离出来,用一层 Nginx 配置覆盖多个异构后端,改造成本远低于逐个应用接入登录。落地时把握四点:模块要确认存在、子请求不带 body 所以要按 header 鉴权、缓存键必须含凭据否则越权、鉴权服务故障策略必须提前定死并写进变更记录。对只有一个应用的站点,直接在框架里做登录更简单;当后端数量超过三个、或者出现无法改代码的老系统时,这套网关式鉴权的性价比才真正体现出来。