cityofcapetown/nginx-ldap-proxy

cityofcapetown/nginx-auth-ldap

镜像概述

cityofcapetown/nginx-auth-ldap 是一个基于 Alpine Linux 和 Nginx 构建的 Docker 镜像，旨在与官方 Nginx 镜像保持兼容。该镜像集成了 https://github.com/kvspb/nginx-auth-ldap 模块，主要设计用作一个简单、模块化的 LDAP 认证代理，部署在其他 Web 应用程序的前端，为后端服务提供统一的身份验证保护。

核心功能与特性

• 轻量级基础：基于 Alpine Linux 构建，镜像体积小，资源占用低。
• 官方兼容性：设计兼容官方 Nginx 镜像的使用方式和配置习惯。
• LDAP 认证集成：内置 nginx-auth-ldap 模块，支持标准的 LDAP 绑定、搜索和身份验证。
• 灵活的访问控制：支持通过 LDAP URL 过滤条件限制特定用户或用户组的访问权限。
• 环境变量配置：支持通过环境变量快速注入配置，无需修改底层 Nginx 配置文件即可实现基础代理功能。

使用场景与适用范围

• 内部系统保护：为缺乏内置 LDAP/AD 认证功能的内部 Web 应用（如监控面板、内部工具）添加统一的企业级身份验证。
• 反向代理网关：作为反向代理网关，拦截未授权请求，仅允许通过 LDAP 验证的合法用户访问后端服务。
• 细粒度权限控制：结合 LDAP 组属性，限制特定部门或用户组对敏感后端服务的访问。

环境变量配置

该镜像默认使用内置的 Nginx 配置模板，并通过以下环境变量替换模板中的占位符来实现快速配置：

关于 LDAP_URL 的组权限限制： 若要限制仅特定用户组可以访问，可以在 LDAP_URL 的过滤条件中添加 memberOf 属性。例如： ldap://ldap.example.com:3268/dc=example,dc=com?sAMAccountName?sub?(&(memberOf:1.2.840.113556.1.4.1941:=CN=My%20Group,OU=Groups,DC=example,DC=com)(objectClass=person))

使用方法

1. 使用 Docker Run 快速启动

以下示例展示了如何通过命令行传递环境变量来启动 LDAP 代理，并将请求转发到指定的后端服务器：

bash
docker run -d \
  --name nginx-ldap-proxy \
  -p 8080:80 \
  -e BACKEND_SERVER="192.168.1.100:8000" \
  -e BIND_DN="CN=svc_ldap,OU=ServiceAccounts,DC=example,DC=com" \
  -e BIND_DN_PASSWORD="YourServiceAccountPassword" \
  -e LDAP_WELCOME_MSG="Welcome! Please use your domain credentials." \
  -e LDAP_URL="ldap://ldap.example.com:389/dc=example,dc=com?sAMAccountName?sub?(objectClass=person)" \
  docker.xuanyuan.run/cityofcapetown/nginx-auth-ldap

2. 使用 Docker Compose 部署

对于生产环境或需要与其他服务编排的场景，推荐使用 docker-compose.yml：

yaml
version: '3.8'

services:
  nginx-ldap-proxy:
    image: docker.xuanyuan.run/cityofcapetown/nginx-auth-ldap
    container_name: nginx-ldap-proxy
    ports:
      - "8080:80"
    environment:
      - BACKEND_SERVER=backend-app:8000
      - BIND_DN=CN=svc_ldap,OU=ServiceAccounts,DC=example,DC=com
      - BIND_DN_PASSWORD=YourServiceAccountPassword
      - LDAP_WELCOME_MSG=Restricted Area - Please authenticate.
      - LDAP_URL=ldap://ldap.example.com:389/dc=example,dc=com?sAMAccountName?sub?(objectClass=person)
    restart: unless-stopped
    networks:
      - app-network

  backend-app:
    image: docker.xuanyuan.run/your-backend-image:latest
    # 后端服务无需暴露端口到宿主机，仅通过内部网络与代理通信
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

3. 高级配置

如果环境变量无法满足复杂的 Nginx 配置需求（例如配置多个 location、自定义 SSL 证书、复杂的请求头重写等），您可以挂载自定义的 Nginx 配置文件来覆盖默认配置。

创建自定义配置文件 secured.conf，并将其挂载到容器的 /etc/nginx/conf.d/ 目录下：

bash
docker run -d \
  --name nginx-ldap-proxy-advanced \
  -p 443:443 \
  -v /path/to/your/secured.conf:/etc/nginx/conf.d/default.conf:ro \
  -v /path/to/your/certs:/etc/nginx/certs:ro \
  docker.xuanyuan.run/cityofcapetown/nginx-auth-ldap

注：编写自定义配置时，请参考 nginx-auth-ldap 模块的官方文档以获取完整的指令支持。

许可证

本项目基于 https://opensource.org/licenses/MIT 开源。 Copyright © 2017 Jacob Blain Christen and City of Cape Town.