nginx auth_request模块实现前置鉴权的核心是：先拦截请求并发起子请求至/internal鉴权接口，仅当其返回2xx才放行；鉴权服务须校验凭证并严格返回200/401/403，nginx据此统一控制访问。
用 Nginx 的 auth_request 模块做前置鉴权，核心就两件事：让 Nginx 把请求先“拦一下”，发给你的鉴权服务查一查；查完按状态码决定放行还是拦截。整个过程不改后端代码，也不依赖应用自身权限逻辑，真正实现统一入口、集中管控。
鉴权服务要怎么写
它本质就是一个独立的 HTTP 接口（比如 /auth），只做一件事：校验并返回标准状态码。
- 接收 Nginx 转发来的子请求，自动携带原始请求的
Authorization头、Cookie、查询参数等 - 解析 Token（如 JWT）、验证签名、检查过期时间、比对白名单或角色权限
- 校验通过必须返回
200 OK；失败则返回401 Unauthorized或403 Forbidden - 可选：在响应头中添加自定义信息，例如
X-User-ID: 123或X-Role: admin，供后续透传
Nginx 配置的关键三步
配置本身不复杂，但顺序和细节容易出错。
- 定义
location /auth：指向你的鉴权服务地址，加上internal指令防止外部直接访问 - 在受保护的
location（如/api/）里加auth_request /auth; - 用
auth_request_set提取鉴权服务返回的头信息，再通过proxy_set_header转发给后端，例如：
auth_request_set $user_id $upstream_http_x_user_id;
proxy_set_header X-User-ID $user_id;
常见问题与处理方式
实际部署时几个典型情况需要提前考虑。
- 未登录跳转：Nginx 默认返回 401，如果希望重定向到登录页，需配合
error_page 401 =302 /login?from=$request_uri; - 健康检查绕过：像
/health这类探针接口，不要加auth_request，单独配一个无鉴权的location - 超时与容错：为
/auth设置合理超时（proxy_read_timeout 5s），避免鉴权服务卡住整个请求链 - 日志隔离：可在
/auth的 location 中关闭 access log，避免鉴权子请求刷爆日志
为什么推荐这个方案
相比在每个应用里重复写鉴权逻辑，auth_request 把安全边界前移到网关层。
- 后端服务专注业务，不用处理 Token 解析、权限树、会话管理等通用能力
- 所有 API 统一走一套规则，新增服务只需改 Nginx 配置，无需动代码
- 鉴权服务可独立伸缩、灰度发布、打点监控，不影响主业务稳定性
- 支持和企业已有 SSO、OAuth2、LDAP 等体系对接，只需改鉴权服务实现
