利用 auth_request 模块实现微服务架构下基于 OAuth2/JWT 的统一准入控制网关-Nginx-PHP中文网

auth_request模块不能直接校验jwt，因其仅转发请求并依据上游返回的2xx/401/403状态码放行或拦截，jwt签名、iss、aud、exp等校验必须由后端认证服务完成。

利用 auth_request 模块实现微服务架构下基于 oauth2/jwt 的统一准入控制网关

auth_request 模块为什么不能直接校验 JWT？

因为 auth_request 本身不解析 Token，它只做 HTTP 请求转发和状态码判断——只要上游返回 200 就放行，401/403 就拦截。JWT 校验必须由你写的认证服务（比如用 Python Flask 或 Go Gin 实现的 /oauth2/token/introspect 接口）完成，Nginx 只负责把 $http_authorization 或 $arg_access_token 转发过去。

常见错误是以为加了 auth_request /auth 就万事大吉，结果认证服务没校验签名、没检查 exp、甚至硬编码返回 200，导致鉴权形同虚设。

务必让认证服务验证 JWT 签名（HS256/RSA256）、iss、aud、exp 和 nbf
不要在 Nginx 层用 map 或正则提取 Bearer 后的 token——交给后端做更可靠；若必须提取，用 set $token $http_authorization; 配合 rewrite ^(.*)$ $1 break; 和 proxy_set_header Authorization $token;
注意：Nginx 默认不透传 Authorization 头给 auth_request 子请求，需显式配置 proxy_pass_request_headers on; 在 auth location 块里

如何让 auth_request 正确传递 OAuth2 introspection 所需参数？

OAuth2 RFC 7662 的 /introspect 接口要求 POST body 包含 token 字段，且通常需要 client_id 和 client_secret 认证。Nginx 原生不支持构造 POST body，得靠 auth_request_set + proxy_pass_request_body off + proxy_set_body 组合实现。

典型陷阱是直接 proxy_pass https://auth-svc/oauth2/introspect，结果发过去的是空 body 或原始请求 body，认证服务收不到 token。

用 auth_request_set $auth_token $http_authorization; 提前捕获 header
在 location = /auth 里关闭 body 透传：proxy_pass_request_body off;
手动构造 body：proxy_set_body '{"token":"$auth_token","client_id":"gateway","client_secret":"s3cr3t"}';
必须设置 proxy_content_type application/json;，否则某些认证服务（如 Hydra）会拒收

微服务路由与 auth_request 的 scope 权限联动怎么做？

auth_request 的子请求返回的响应头（如 X-User-ID、X-Scopes）可通过 auth_request_set 提取，并在主请求中注入到下游服务——这是实现 RBAC 的关键链路。

但很多人卡在：认证服务明明写了 X-Scopes: read:orders write:users，下游却收不到，或收到的是空值。

确保认证服务响应头未被 Nginx 过滤：默认 underscores_in_headers off，若用下划线命名（如 X_Scopes）需开启；推荐用短横线（X-Scopes）避免问题
在 location /auth 中用 auth_request_set $user_scopes $upstream_http_x_scopes; 提取
在主 server 或 location 块中，用 proxy_set_header X-Scopes $user_scopes; 透传——注意变量必须在 auth_request 执行后才可用，不能写在 location /auth 外层
如果下游服务需根据 scope 做细粒度路由（如 write:* 走写集群），得配合 map 指令预处理：map $user_scopes $upstream_backend { "~*write" "write-svc"; default "read-svc"; }

超时、重试和错误响应怎么避免拖垮网关？

auth_request 是同步阻塞的：主请求必须等子请求完成才能继续。一旦认证服务延迟高或宕机，所有流量都会卡住，表现就是大量 500 或连接超时。

这不是配置少的问题，而是架构上必须接受「认证链路不可绕过」——所以容错只能靠降级策略和严格超时控制。

必须设 auth_request_timeout 3s; 和 auth_request_buffering off;（后者禁用缓冲，减少内存占用）
不要配 auth_request_tries 3：重试会放大雪崩风险；真要重试，应在认证服务内部做
对 5xx 响应，默认返回 500，但可配 error_page 500 =401 /error_401; 统一返回 401，避免暴露后端细节
生产环境建议把认证服务部署在本地环回（127.0.0.1），用 Unix socket 或 fastcgi 提速，而非走网络调用

真正难的不是写通这段配置，而是让每个微服务信任并正确消费 X-User-ID 和 X-Scopes ——它们不会自动变成 Spring Security 的 Authentication 对象，也不会自动注入到 Gin 的 c.Get("user") 里。这层适配，得每个服务自己写，而且必须和网关的 header 名称、格式、编码方式完全对齐。