upstream模块仅负责定义后端服务器组并分发请求，不支持auth_basic、allow/deny等认证与访问控制指令；所有身份验证（如HTTP Basic、JWT、IP白名单）必须在server或location块中完成，再将校验后的请求代理至upstream。
Nginx 的 upstream 模块本身不处理身份验证与访问控制，它只负责定义后端服务器组和分发请求。真正的认证与鉴权需在 Nginx 的 server 或 location 层实现，再将已通过校验的请求代理到 upstream。不能把 auth_basic、JWT 验证或 IP 限制逻辑放在 upstream 块里——那会直接报错。
在 proxy_pass 前完成认证拦截
所有验证动作必须发生在请求进入 upstream 分发流程之前，也就是在 location 块中配置：
- 用 auth_basic 启用 HTTP Basic 认证（适合管理后台或内部接口）：
auth_basic "Restricted Area";
auth_basic_user_file /www/wwwroot/auth/.htpasswd; - 用 auth_request 转发到独立认证服务（如 Keycloak、自建 OAuth2 网关）：
auth_request /auth;
location = /auth {
proxy_pass https://auth-server/oauth/validate;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
} - 用 geo + map + deny/allow 实现 IP 白名单：
geo $allowed_ip {
default 0;
192.168.10.0/24 1;
203.0.113.42 1;
}
map $allowed_ip $denied {
0 1;
1 "";
}
location / {
if ($denied) { return 403; }
proxy_pass http://backend_cluster;
}
让后端服务也能获取原始认证信息
上游应用需要知道“谁来了”，Nginx 要透传可信凭证，而不是仅做转发：
- 传递用户标识：
proxy_set_header X-User $remote_user;
proxy_set_header X-Auth-Type "basic";（配合 auth_basic 使用） - 透传 JWT Token（若前端已在 Authorization 头携带）：
proxy_set_header Authorization $http_authorization;（注意：需在 server 块启用underscores_in_headers on;才能读取含下划线的 header） - 添加可信来源标记，防止伪造：
proxy_set_header X-Forwarded-By "nginx-gw";
proxy_hide_header X-Internal-Secret;（隐藏敏感响应头）
避免常见误配陷阱
以下操作无法生效或存在安全隐患，应避开：
- 在 upstream 块中写
auth_basic或allow/deny—— 语法错误，Nginx 启动失败 - 只对 location / 做认证，但未限制
/health、/metrics等路径 —— 攻击面暴露 - 启用
auth_request却未配置error_page 401 = @error401，导致 401 被直接返回给客户端而非重定向或统一响应 - 使用
if ($remote_user = "") { return 401; }替代标准 auth 指令 —— if 在 location 中行为不可靠，易绕过
结合后端实际做分级控制
建议按业务层级拆分策略，例如：
- 接入层（Nginx）：IP 白名单 + TLS 客户端证书校验（ssl_verify_client on） + 接口级 Basic 认证
- 网关层（可选 Kong/Nginx Plus）：OAuth2 token 解析、scope 校验、速率限制
- 应用层（upstream 后端）：基于 X-User / X-Groups 做 RBAC，不信任未经签名的请求头
