linuxserver/ldap-auth

linuxserver/ldap-auth

镜像概述和主要用途

linuxserver/ldap-auth是由LinuxServer.io团队开发的Docker镜像，基于https://github.com/nginxinc/nginx-ldap-auth项目。该镜像用于对Nginx代理的受保护资源进行用户认证，包含两个核心组件：与LDAP认证服务器通信的守护进程（ldap-auth），以及基于用户凭据生成认证Cookie的Web服务器守护进程。支持轻量级目录访问协议（LDAP）认证服务器，包括OpenLDAP和Microsoft Windows Active Directory 2003/2012。

核心功能和特性

LinuxServer.io镜像通用特性

• 定期及时的应用更新
• 简易用户映射（PGID、PUID）
• 基于s6 overlay的自定义基础镜像
• 每周基础操作系统更新，跨生态系统共享公共层以减少空间占用、 downtime和带宽消耗
• 定期安全更新

本镜像特有功能

• 使用fernet算法对Cookie信息进行编码，支持容器创建时随机生成密钥或用户自定义密钥
• 登录页面同时支持/ldaplogin和/login路径，避免与反向代理应用的/login路径冲突
• 支持只读容器文件系统运行
• 支持非root用户运行
• 可选启用HTTPS加密（需提供证书和密钥文件）

支持的架构

该镜像通过Docker manifest支持多平台，拉取lscr.io/linuxserver/ldap-auth:latest即可自动获取对应架构的镜像，也可通过标签指定特定架构：

应用设置

• 容器本身无内置配置，依赖传入的HTTP请求头信息，需确保Web服务器（如Nginx）配置正确
• 示例Nginx配置参考：https://github.com/nginxinc/nginx-ldap-auth/blob/master/nginx-ldap-auth.conf
• 与上游项目不同，本镜像使用fernet编码Cookie信息（随机生成或用户定义密钥）
• 登录页面路径为/ldaplogin和/login，避免与反向代理应用的内部认证路径冲突

使用方法

docker-compose（推荐）

yaml
---
services:
  ldap-auth:
    image: docker.xuanyuan.run/linuxserver/ldap-auth:latest
    container_name: ldap-auth
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - FERNETKEY= #可选
      - CERTFILE= #可选
      - KEYFILE= #可选
    ports:
      - 8888:8888
      - 9000:9000
    restart: unless-stopped

docker cli

bash
docker run -d \
  --name=ldap-auth \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e FERNETKEY= `#可选` \
  -e CERTFILE= `#可选` \
  -e KEYFILE= `#可选` \
  -p 8888:8888 \
  -p 9000:9000 \
  --restart unless-stopped \
  lscr.io/linuxserver/ldap-auth:latest

参数说明

环境变量文件（Docker secrets）

可通过FILE__前缀从文件加载环境变量，例如：

bash
-e FILE__MYVAR=/run/secrets/mysecretvariable

Umask设置

可通过-e UMASK=022覆盖默认umask设置，详见umask说明。

用户/组ID说明

使用卷（-v参数）时，可通过指定PUID（用户ID）和PGID（组ID）避免主机与容器间的权限问题。确保主机卷目录所有者与指定的PUID/PGID一致。可通过id your_user命令获取当前用户的ID：

bash
id your_user

示例输出：

text
uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)

支持信息

• 容器运行时Shell访问：

  bash
  docker exec -it ldap-auth /bin/bash
  

• 实时监控容器日志：

  bash
  docker logs -f ldap-auth
  

• 容器版本查询：

  bash
  docker inspect -f '{{ index .Config.Labels "build_version" }}' ldap-auth
  

• 镜像版本查询：

  bash
  docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/ldap-auth:latest
  

更新说明

通过docker-compose更新

• 更新镜像：

  bash
  docker-compose pull ldap-auth
  

• 更新容器：

  bash
  docker-compose up -d ldap-auth
  

• 清理旧镜像：

  bash
  docker image prune
  

通过docker run更新

• 更新镜像：

  bash
  docker pull docker.xuanyuan.run/linuxserver/ldap-auth:latest
  

• 停止并删除容器：

  bash
  docker stop ldap-auth && docker rm ldap-auth
  

• 使用原参数重新创建容器（配置将通过卷保留）

本地构建

bash
git clone https://github.com/linuxserver/docker-ldap-auth.git
cd docker-ldap-auth
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/ldap-auth:latest .

ARM架构构建需先注册qemu-static：

bash
docker run --rm --privileged docker.xuanyuan.run/linuxserver/qemu-static --reset

然后使用对应架构的Dockerfile（如-f Dockerfile.aarch64）。

版本历史

• 25.12.24: 添加legacy-cgi，修复fernet密钥存储
• 22.12.24: 基于Alpine 3.21重建，支持只读和非root运行
• 30.06.24: 基于Alpine 3.20重建
• 23.12.23: 基于Alpine 3.19重建
• 20.06.23: 同步上游变更，支持通过X-Ldap-DisableReferrals禁用引用
• 25.05.23: 基于Alpine 3.18重建，弃用armhf架构
• 30.12.22: 基于Alpine 3.17重建
• 19.09.22: 基于Alpine 3.15重建
• 14.05.21: 添加linuxserver wheel索引
• 12.02.21: 清理cargo/rust缓存
• 10.02.21: 基于Alpine 3.13重建
• 08.09.20: 修复表单动作设置
• 30.07.20: 修复可选CERTFILE和KEYFILE变量未设置时的bug
• 27.07.20: 支持HTTPS
• 21.07.20: 支持用户自定义fernet密钥
• 02.06.20: 基于Alpine 3.12重建，登录页面路径添加/ldaplogin
• 17.05.20: 支持自签名CA证书
• 20.02.20: 切换到Python 3
• 19.12.19: 基于Alpine 3.11重建
• 01.07.19: 基础HTTP认证时回退到base64编码
• 28.06.19: 基于Alpine 3.10重建
• 23.03.19: 切换到新基础镜像，使用arm32v7标签
• 22.02.19: 基于Alpine 3.9重建
• 18.09.18: 更新pip
• 14.09.18: 添加TZ参数，移除不必要的PUID/PGID参数
• 11.08.18: 初始发布