Nginx 中如何使用 proxy_set_header 进行网关鉴权-Nginx-PHP中文网

nginx 通过 auth_request 模块调用认证服务，提取其响应头中的用户身份信息（如 x-user-id），再用 proxy_set_header 将其作为可信请求头透传至后端，实现安全、高效的统一鉴权。

nginx 中如何使用 proxy_set_header 进行网关鉴权

Nginx 本身不直接做鉴权逻辑，而是通过 proxy_set_header 配合 auth_request 模块，把鉴权结果“安全透传”给后端服务。关键不是让 Nginx 自己验证 token，而是让它信任并转发认证服务的结果。

proxy_set_header 在鉴权场景中的真实作用

它不参与判断“有没有权限”，而是把已通过鉴权的用户身份、角色等元数据，作为可信请求头注入到转发给后端的请求中。后端据此直接执行业务逻辑，避免重复解析 JWT 或查数据库。

必须确保 proxy_set_header 出现在 proxy_pass 之前，否则变量为空或未生效
所有用于鉴权透传的 header，建议加 X- 前缀（如 X-User-ID），明确标识为网关注入字段
不要直接转发客户端原始 Authorization 头给后端——这会绕过网关鉴权，造成安全隐患

如何配合 auth_request 提取并透传身份信息

先由 /auth 子请求完成校验，认证服务在成功响应（HTTP 200）中返回自定义头，例如：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

X-User-ID: 10086  
X-User-Role: admin  
X-Auth-Scope: read:order,write:user

然后在受保护的 location 中配置：

location /api/ {
    auth_request /auth;

    # ✅ 提取认证服务返回的响应头（注意命名转换规则）
    auth_request_set $user_id $upstream_http_x_user_id;
    auth_request_set $role    $upstream_http_x_user_role;
    auth_request_set $scope   $upstream_http_x_auth_scope;

    # ✅ 将提取的变量作为新请求头透传
    proxy_set_header X-User-ID $user_id;
    proxy_set_header X-User-Role $role;
    proxy_set_header X-Auth-Scope $scope;

    # ✅ 同时保留基础可信头（防伪造、便于日志和限流）
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Request-ID $request_id;

    proxy_pass http://backend;
}

安全与可靠性要点

认证 location（如 /auth）必须加 internal;，禁止外部直接访问
auth_request_set 的变量名要语义清晰，且只能在 auth_request 执行后、proxy_pass 前使用
若认证服务返回空值（如 $upstream_http_x_user_id 为空），proxy_set_header 仍会发送一个空值 header；如需兜底，可用 map 或 Lua 做非空校验
后端应完全信任这些 X- 头，不再自行解析 token——Nginx 是可信边界，这是统一鉴权的前提