在 nginx 中配置第三方鉴权，核心是利用 auth_request 模块发起一个内部子请求，将当前请求的完整上下文（如 url、header、cookie）转发给指定的鉴权服务。如果鉴权服务返回 http 200，则允许访问；若返回 401 或 403，则拦截请求并展示错误页。具体做法是在 location 块中使用 auth_request /internal-auth; 指向一个内部位置，该位置通过 proxy_pass 将请求代理到第三方鉴权接口。
如何配置主站点的鉴权拦截与内部转发
要实现这一流程，需要在 Nginx 配置文件中定义两个关键部分：一个是受保护的主业务路径，另一个是用于处理鉴权逻辑的内部路径。在主路径中，通过 auth_request 指令指定子请求的 URI；在内部路径中，使用 proxy_pass 将请求转发至第三方鉴权服务的地址。这种配置确保了鉴权逻辑与业务逻辑解耦，且对客户端透明。
server {
listen 80;
server_name example.com;
# 主业务路径：启用鉴权
location /protected/ {
# 发起内部子请求进行鉴权
auth_request /internal-auth;
# 鉴权通过后，代理到后端应用
proxy_pass http://backend_app;
}
# 内部鉴权路径：不对外暴露
location = /internal-auth {
# 禁止外部直接访问
internal;
# 转发到第三方鉴权服务
proxy_pass http://auth-service/check;
# 传递原始请求头，如 Authorization Token
proxy_pass_request_headers on;
# 仅传递原始请求体（如果需要校验 Body）
proxy_pass_request_body on;
}
}
上述配置中，当用户访问 /protected/ 时，Nginx 会先在后台发起一个 /internal-auth 请求。该请求被标记为 internal，意味着外部客户端无法直接访问此 URI，只能通过子请求触发。第三方鉴权服务收到请求后，若验证 Token 有效，应返回 200 OK；若无效，返回 401 Unauthorized。Nginx 根据子请求的状态码决定最终响应。
如何处理鉴权失败时的自定义错误页面
当第三方鉴权服务返回非 200 状态码时，默认情况下 Nginx 会返回标准的 401 或 403 错误页。为了提升用户体验，可以通过 error_page 指令捕获这些状态码，并重定向到自定义的错误页面或登录页。此外，还可以利用 auth_request_set 指令从鉴权响应的 Header 中提取用户信息（如 User-ID），并将其设置为变量，供后续日志记录或业务逻辑使用。
server {
listen 80;
server_name example.com;
# 捕获鉴权失败的错误
error_page 401 = @login;
error_page 403 = @forbidden;
location /protected/ {
# 从鉴权响应中提取用户 ID
auth_request_set $auth_user $upstream_http_x_user_id;
# 发起鉴权子请求
auth_request /internal-auth;
# 将用户 ID 添加到请求头，传给后端
proxy_set_header X-User-ID $auth_user;
proxy_pass http://backend_app;
}
location = /internal-auth {
internal;
proxy_pass http://auth-service/check;
proxy_pass_request_headers on;
}
# 自定义登录页
location @login {
return 302 /login?redirect=$request_uri;
}
# 自定义禁止访问页
location @forbidden {
return 403 "Access Denied";
}
}
在此配置中，auth_request_set 指令用于从鉴权服务的响应头 X-User-ID 中获取值，并存储到 Nginx 变量 $auth_user 中。随后，该变量通过 proxy_set_header 传递给后端应用，实现单点登录（SSO）场景下的用户身份透传。若鉴权失败，Nginx 不会直接返回错误，而是跳转到 @login 或 @forbidden 内部重定向，从而提供友好的错误提示或登录引导。
鉴权服务返回空响应体时 Nginx 如何处理
当第三方鉴权服务成功验证但返回空响应体（Empty Body）时，Nginx 的 auth_request 模块仍能正确识别 HTTP 200 状态码并放行请求。这是因为 auth_request 仅依赖状态码判断权限，不要求响应体必须包含特定内容。然而，若鉴权服务因异常返回非标准状态码（如 500），或未设置正确的 Content-Type，可能导致 Nginx 误判。建议鉴权服务始终返回明确的 200 或 4xx/5xx 状态码，并在成功时保持响应体为空或仅含少量元数据，以避免解析开销。
