tpimenta/nginx-ldap-auth

Nginx LDAP Auth

镜像概述

Nginx LDAP Auth 是一个专为 Kubernetes 环境设计的轻量级身份验证后端镜像。它通过 LDAP（轻量级目录访问协议）为 Nginx Ingress 控制器提供外部身份验证支持，帮助集群管理员实现集中式的用户访问控制。

核心功能和特性

• LDAP 集成：无缝对接企业现有的 LDAP 或 Active Directory 目录服务。
• Kubernetes 原生支持：专为 K8s Ingress 外部认证（External Authentication）机制设计。
• 轻量高效：作为独立的认证微服务运行，资源占用低，响应速度快。
• 安全隔离：通过 Kubernetes Secret 安全管理 LDAP 凭据和配置文件。

使用场景和适用范围

• 需要为 Kubernetes 集群内部署的 Web 应用添加统一 LDAP 登录认证的场景。
• 企业内网环境中，希望复用现有 AD/LDAP 账号体系进行 Ingress 网关鉴权。
• 替代传统的 Basic Auth，提供更安全、更易于集中管理的身份验证方案。

详细使用方法和配置说明

1. 准备 LDAP 配置文件

获取项目中的 config.sample.yaml 文件，并根据您的实际 LDAP 服务器信息修改其中的配置参数（如 LDAP URL、Base DN、Bind DN 及密码等），将其重命名为 config.yaml。

2. 在 Kubernetes 中部署

创建配置 Secret

将修改后的配置文件作为 Kubernetes Secret 导入，以确保敏感信息的安全：

bash
kubectl create secret generic nginx-ldap-auth --from-file=config.yaml=config.sample.yaml

部署应用

应用提供的 Kubernetes 部署清单：

bash
kubectl apply -f k8s.yaml

3. 配置 Ingress 路由

在需要保护的 Ingress 资源中添加外部认证注解，将认证请求转发至 nginx-ldap-auth 服务。默认服务监听端口为 5555。

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-protected-app
  annotations:
    # 配置外部认证 URL，指向 nginx-ldap-auth 服务
    nginx.ingress.kubernetes.io/auth-url: "http://nginx-ldap-auth.default.svc.cluster.local:5555"
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-app-service
            port:
              number: 80

注：更多关于 Nginx Ingress 外部认证的详细说明，请参考 https://kubernetes.github.io/ingress-nginx/examples/auth/external-auth/%E3%80%82

Docker 独立部署示例

如果您需要在非 Kubernetes 环境中直接使用 Docker 运行该镜像进行调试或测试，可以参考以下 docker-compose.yml 配置：

yaml
version: '3.8'
services:
  nginx-ldap-auth:
    image: tiagoapimenta/nginx-ldap-auth:latest # 请根据实际使用的镜像标签进行替换
    container_name: nginx-ldap-auth
    ports:
      - "5555:5555"
    volumes:
      - ./config.yaml:/etc/nginx-ldap-auth/config.yaml:ro
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

配置参数说明

配置文件 config.yaml 主要用于定义 LDAP 连接与查询参数，核心字段通常包括：

• ldap_url: LDAP 服务器地址（例如 ldap://ldap.example.com:389 或 ldaps://...）。
• base_dn: 搜索用户的基准 DN（例如 dc=example,dc=com）。
• bind_dn: 用于绑定 LDAP 服务器的管理员或服务账号 DN。
• bind_password: 绑定账号的密码。
• user_filter: 用户搜索过滤器（例如 (uid=%s) 或 (sAMAccountName=%s)）。