nginx官方标准版默认已编译启用auth_request模块，无需额外加载；关键在于正确配置子请求路由、认证服务对接和用户信息透传，需严格遵循internal保护、头信息透传及状态码契约。
Nginx 本身不内置 auth_request 模块的开关管理，它是一个编译时启用的官方模块（ngx_http_auth_request_module），只要 Nginx 是标准发行版（如 nginx.org 官方包、主流 Linux 发行版仓库安装的版本），该模块默认已编译启用，无需额外安装或加载 load_module 指令。
真正需要配置的是 如何正确使用 auth_request 实现统一认证——这属于功能级配置，不是模块启停管理。关键在三点：子请求路由设计、认证服务对接、用户信息透传。
auth_request 统一认证的核心配置结构
必须包含两个部分：
- 外部受保护的
location（启用鉴权） - 内部专用的
location（处理子请求，不可被直连）
# 示例：保护 /app/ 下所有路径
location /app/ {
# 启用鉴权，指向内部认证入口
auth_request /_auth;
# 可选：捕获认证服务返回的用户标识
auth_request_set $auth_user $upstream_http_x_user;
auth_request_set $auth_role $upstream_http_x_role;
# 透传给后端应用
proxy_set_header X-Auth-User $auth_user;
proxy_set_header X-Auth-Role $auth_role;
proxy_pass http://backend-app;
}
# 内部认证子请求入口（禁止外部访问）
location = /_auth {
internal; # ⚠️ 关键！防止绕过认证直接调用
# 转发到你的统一认证中心
proxy_pass https://sso.example.com/auth/check;
# 清空请求体，减少开销（认证接口通常只需头信息）
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 Authorization $http_authorization;
proxy_set_header Cookie $http_cookie;
proxy_set_header X-Forwarded-For $remote_addr;
}
认证服务需满足的最小契约
Nginx 不关心你怎么验，只认三类 HTTP 状态码：
-
200 OK→ 放行，可附带响应头（如X-User: alice）供auth_request_set提取 -
401 Unauthorized→ 未登录，常配合error_page 401 = @login跳转统一登录页 -
403 Forbidden→ 已登录但无权限，可返回自定义错误页或 JSON
建议认证接口 /auth/check 至少支持：
- 从
Authorization头解析 Bearer Token（JWT） - 或从
Cookie提取 session ID 并查会话库 - 返回简洁头信息，不依赖响应体
常见加固与避坑点
- ✅
internal;必须加在/_authlocation 中，否则攻击者可直接请求绕过主逻辑 - ✅
proxy_pass_request_body off;避免重复发送 body 导致超时或认证服务报错 - ✅ 所有
proxy_set_header应显式写出，Nginx 不自动继承上级proxy_set_header - ❌ 不要用
auth_request处理登录页本身（如/login），应将其排除在鉴权范围外 - ❌ 不要省略
X-Original-*类头，否则认证服务无法做路径/方法级细粒度鉴权
错误跳转示例（提升用户体验）
# 当 auth_request 返回 401 时，重定向到 SSO 登录页，并带回原地址
error_page 401 =302 https://sso.example.com/login?rd=$scheme://$host$request_uri;
# 可选：为登录页单独配置，禁用鉴权
location = /login {
proxy_pass https://sso.example.com/login;
}
不复杂但容易忽略
