auth_request模块通过子请求将鉴权逻辑外移至第三方认证服务，Nginx仅依据其返回的2xx/401/403状态码放行或拒绝请求，透传X-Original-URI、Authorization等上下文，并配合internal限制和body优化实现安全高效的统一身份认证。
用 Nginx 的 auth_request 模块对接外部统一身份认证系统，核心是把鉴权逻辑“移出”Nginx，交由一个独立的认证服务处理。Nginx 只负责转发校验请求、拦截未授权访问，并透传用户身份信息。这种方式不修改业务代码，也不暴露认证细节，适合保护 Kibana、Open-Falcon、Dify、ChatGLM 等无内置登录能力的服务。
auth_request 的工作逻辑
它不是直接做 LDAP 或 SSO 认证，而是发起一次子请求（subrequest）到你指定的认证接口（比如 /auth）。Nginx 根据这个接口返回的状态码决定放行（200）还是拒绝（401/403）：
- 状态码为 200：Nginx 允许原请求继续，并可提取响应头（如
X-Forwarded-User）传递给后端 - 状态码为 401：触发
error_page 401 = @login，跳转到登录页或返回认证挑战 - 状态码为 403：直接拒绝，可返回 403 页面
对接 LDAP 的典型实现方式
LDAP 本身不提供 HTTP 接口，所以需要一个中间服务把 LDAP 查询封装成 Web API。常见方案有：
-
nginx-auth-ldap：Python 编写的轻量 daemon（
nginx-ldap-auth-daemon.py），监听 HTTP 请求，接收 Base64 编码的用户名密码，连接 LDAP 服务器执行 bind 操作，成功则返回 200 + 用户属性头 -
自建 auth 服务：用 Flask/FastAPI 写一个
/auth接口，读取请求头中的Authorization或 cookie，调用 python-ldap 或 ldap3 库完成验证，支持 DN 模板、组权限检查、属性映射等 - 复用现有平台：比如将 auth_request 指向 Keycloak 的 token introspection 端点，或 IDaaS 的 OAuth2 校验接口，间接实现 LDAP 背后的统一认证
对接 SSO（如 OIDC/SAML）的关键配置
SSO 流程更复杂，涉及重定向和令牌交换，auth_request 不能直接处理登录跳转，但可以校验已有的会话凭证：
- 前端完成 SSO 登录后，将 ID Token 或 Session Cookie 传给 Nginx
- Nginx 把该 token 通过
proxy_set_header转发给你的/auth接口 - auth 服务解析 JWT（OIDC）或验证 SAML 断言签名，确认有效性并提取用户标识（如
sub或uid） - 返回 200 并在响应头中写入
X-Forwarded-User: zhangsan@company.com，Nginx 再透传给后端应用
实际配置要点与注意事项
一份稳定可用的配置需注意几个关键细节：
- location /auth 必须加 internal：防止外部直接访问该认证接口，只允许内部子请求调用
-
关闭 auth 接口的请求体转发：用
proxy_pass_request_body off; proxy_set_header Content-Length ""，避免 auth_request 子请求携带原始 body 导致服务异常 -
合理设置超时：在
location /auth中配置proxy_read_timeout 5;，避免 LDAP 延迟拖慢整个请求 -
错误跳转要带原始 URI：用
add_header Set-Cookie "NSREDIRECT=$scheme://$http_host$request_uri"或重定向参数，使用户登录后能回到原页面 - HTTPS 和证书验证不可省略：尤其对接 ldaps:// 或 OIDC 提供方时，确保 Nginx 或后端 auth 服务校验对方 TLS 证书
