Nginx auth_request 统一鉴权网关配置实战

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 鉴权、缓存键必须含凭据否则越权、鉴权服务故障策略必须提前定死并写进变更记录。对只有一个应用的站点,直接在框架里做登录更简单;当后端数量超过三个、或者出现无法改代码的老系统时,这套网关式鉴权的性价比才真正体现出来。