nginx 本身不内置 ldap 或 oauth 认证能力，必须通过 auth_request 模块对接外部认证服务（如 nginx-ldap-auth-daemon、authelia、keycloak 或 oauth2 introspect 接口），由其完成凭证校验并返回 200/401/403，nginx 仅负责请求拦截、子请求转发、结果透传及统一访问控制。
Nginx 本身不内置 LDAP 或 OAuth 认证能力，必须通过扩展模块或外部服务实现。核心思路是：把鉴权逻辑移出 Nginx，由专用组件处理凭证校验，Nginx 只负责拦截、转发和透传结果。这种方式既保持业务系统零改造，又统一了企业级访问控制入口。
用 auth_request 模块对接外部认证服务
这是目前最推荐、最灵活的集成方式，适用于保护 Kibana、Dify、Open-Falcon 等无登录界面的服务。
- 在 location 中配置 auth_request /auth，让每次请求先触发一个子请求到你的认证接口（如 /auth）
- 该接口返回 200 表示放行，并可在响应头中写入 X-Forwarded-User、X-Forwarded-Groups 等信息，Nginx 会自动透传给后端
- 返回 401 时，配合 error_page 401 = @login 跳转到统一登录页；返回 403 则直接拒绝
- 注意将 /auth 设为 internal，防止外部直接访问；同时禁用缓存、限制请求体大小，避免被滥用
对接 LDAP 的两种主流路径
LDAP 协议本身不是 HTTP 服务，所以必须有一层封装。
- 轻量方案：nginx-ldap-auth-daemon —— Python 编写的守护进程，监听 HTTP 请求，接收 Base64 编码的用户名密码，调用 python-ldap 连接 OpenLDAP 或 Active Directory 执行 bind 验证。配置简单，适合中小环境
- 生产推荐：Authelia 或 Keycloak —— 部署独立认证服务，配置其连接 LDAP/AD，再让 Nginx 的 auth_request 指向它的 /api/authz 或 token introspection 接口。支持 MFA、审计日志、会话管理等企业功能
- 若坚持用原生模块，需编译安装 nginx-auth-ldap（非官方，不支持动态加载），但存在密码明文配置、TLS 配置复杂、组权限判断弱等运维风险
对接 OAuth/OIDC 的关键要点
OAuth 流程涉及重定向和令牌交换，auth_request 不参与登录跳转，只做“已登录状态”的校验。
- 前端完成 SSO 登录后，应将 ID Token 或 Session Cookie 附在请求头（如 Authorization: Bearer xxx 或 Cookie）传给 Nginx
- Nginx 用 proxy_set_header 把该凭证转发给你的 /auth 接口
- /auth 服务解析 JWT（验证签名、过期时间、issuer）、或调用 OIDC Provider 的 introspect 端点，确认有效性并提取用户标识（如 sub、email）
- 成功则返回 200 + X-Forwarded-User，失败返回 401/403。整个流程与前端登录解耦，Nginx 始终只做网关层守门人
安全与运维注意事项
无论选哪种方式，几个细节直接影响上线后的稳定性和安全性。
- 所有 LDAP 连接必须启用 TLS（ldaps:// 或 StartTLS），禁用匿名绑定，避免凭据泄露
- 认证服务与 Nginx 之间建议走内网通信，必要时加 IP 白名单或 mTLS
- 对 /auth 接口做限流（如 limit_req），防止暴力探测；响应头中清除敏感信息（如 Server、X-Powered-By）
- 用户标识建议使用邮箱（user@company.com）而非纯 username，便于跨系统映射和审计溯源
