OpenLDAP 集成

本指南提供了为 Open WebUI 设置 OpenLDAP 身份认证的完整演练。内容涵盖使用 Docker 创建测试 OpenLDAP 服务器、用示例用户进行初始化、配置 Open WebUI 连接，以及常见问题排查。

1. 使用 Docker 设置 OpenLDAP

运行测试 OpenLDAP 服务器最简单的方式是使用 Docker。以下 docker-compose.yml 文件将创建一个 OpenLDAP 容器和一个可选的 phpLDAPadmin 容器（提供基于 Web 的管理界面）。

services:
  ldap:
    image: osixia/openldap:1.5.0
    container_name: openldap
    environment:
      LDAP_ORGANISATION: "Example Inc"
      LDAP_DOMAIN: "example.org"
      LDAP_ADMIN_PASSWORD: admin
      LDAP_TLS: "false"
    volumes:
      - ./ldap/var:/var/lib/ldap
      - ./ldap/etc:/etc/ldap/slapd.d
    ports:
      - "389:389"
    networks: [ldapnet]

  phpldapadmin:
    image: osixia/phpldapadmin:0.9.0
    environment:
      PHPLDAPADMIN_LDAP_HOSTS: "ldap"
    ports:
      - "6443:443"
    networks: [ldapnet]

networks:
  ldapnet:
    driver: bridge

• osixia/openldap 镜像仅通过 LDAP_DOMAIN 和 LDAP_ADMIN_PASSWORD 就能自动创建基础组织结构。
• osixia/phpldapadmin 镜像提供管理 LDAP 目录的 Web 界面，可在 https://localhost:6443 访问。

运行 docker-compose up -d 启动容器。通过检查日志验证 LDAP 服务器已启动：docker logs openldap。您应该能看到"started slapd"消息。

2. 添加示例用户（LDIF）

要测试登录，您需要向 LDAP 目录添加一个示例用户。创建名为 seed.ldif 的文件，内容如下：

seed.ldif

dn: ou=users,dc=example,dc=org
objectClass: organizationalUnit
ou: users

dn: uid=jdoe,ou=users,dc=example,dc=org
objectClass: inetOrgPerson
cn: John Doe
sn: Doe
uid: jdoe
mail: jdoe@example.org
userPassword: {PLAIN}password123

关于密码： userPassword 字段在此测试环境中设置为明文值，方便操作。在生产环境中，应始终使用哈希密码。可以使用 slappasswd 或 openssl passwd 生成哈希密码，例如：

# 使用 slappasswd（在容器内部）
docker exec openldap slappasswd -s your_password

# 使用 openssl
openssl passwd -6 your_password

将 LDIF 文件复制到容器并使用 ldapadd 添加条目：

docker cp seed.ldif openldap:/seed.ldif
docker exec openldap ldapadd -x -D "cn=admin,dc=example,dc=org" -w admin -f /seed.ldif

操作成功会显示"adding new entry"消息。

3. 验证 LDAP 连接

在配置 Open WebUI 之前，验证 LDAP 服务器可访问且用户存在。

ldapsearch -x -H ldap://localhost:389 \
  -D "cn=admin,dc=example,dc=org" -w admin \
  -b "dc=example,dc=org" "(uid=jdoe)"

如果命令返回 jdoe 用户条目，则 LDAP 服务器已就绪。

4. 配置 Open WebUI

现在，配置您的 Open WebUI 实例以使用 LDAP 服务器进行身份认证。

环境变量

为您的 Open WebUI 实例设置以下环境变量。

信息

Open WebUI 仅在首次启动时读取这些环境变量。后续更改必须在 UI 的管理设置面板中进行，除非您设置了 ENABLE_PERSISTENT_CONFIG=false。

# 启用 LDAP
ENABLE_LDAP="true"

# --- 服务器设置 ---
LDAP_SERVER_LABEL="OpenLDAP"
LDAP_SERVER_HOST="localhost"  # 或您的 LDAP 服务器 IP/主机名
LDAP_SERVER_PORT="389"        # 明文/StartTLS 使用 389，LDAPS 使用 636
LDAP_USE_TLS="false"          # LDAPS 或 StartTLS 设置为 "true"
LDAP_VALIDATE_CERT="false"    # 生产环境使用有效证书时设置为 "true"

# --- 绑定凭据 ---
LDAP_APP_DN="cn=admin,dc=example,dc=org"
LDAP_APP_PASSWORD="admin"

# --- 用户 Schema ---
LDAP_SEARCH_BASE="dc=example,dc=org"
LDAP_ATTRIBUTE_FOR_USERNAME="uid"
LDAP_ATTRIBUTE_FOR_MAIL="mail"
# LDAP_SEARCH_FILTER 是可选项，用于附加过滤条件。
# Open WebUI 会自动添加用户名过滤器，因此请勿包含
# %(user)s 或 %s 等用户占位符语法——这些不受支持。
# 简单设置可留空，或添加组成员过滤器，例如：
# LDAP_SEARCH_FILTER="(memberOf=cn=allowed-users,ou=groups,dc=example,dc=org)"

UI 配置

也可以直接在 UI 中配置这些设置：

1. 以管理员身份登录。
2. 导航到 设置 > 通用。
3. 启用 LDAP 身份认证。
4. 填写与上述环境变量对应的字段。
5. 保存设置并重启 Open WebUI。

5. 登录

打开一个新的隐身浏览器窗口并导航到您的 Open WebUI 实例。

• 登录 ID： jdoe
• 密码： password123（或您设置的密码）

登录成功后，Open WebUI 会自动创建一个具有"用户"角色的新用户账户。管理员可以稍后根据需要提升用户角色。

6. 常见错误排查

以下是 LDAP 集成过程中常见错误的解决方案。

port must be an integer

ERROR | open_webui.routers.auths:ldap_auth:447 - LDAP authentication error: port must be an integer - {}

原因： LDAP_SERVER_PORT 环境变量以带引号的字符串传递（例如 "389"）。

解决方案：

• 确保 .env 文件或 export 命令中的 LDAP_SERVER_PORT 值没有引号：LDAP_SERVER_PORT=389。
• 从 LDAP_SERVER_HOST 中删除协议（http://、ldap://）。它应该只是主机名或 IP（例如 localhost）。

[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred

ERROR | LDAP authentication error: ("('socket ssl wrapping error: [SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1016)',)",) - {}

原因： TLS 握手失败。客户端（Open WebUI）正在尝试启动 TLS 连接，但服务器（OpenLDAP）未为其配置或期望不同的协议。

解决方案：

• 如果不打算使用 TLS： 设置 LDAP_USE_TLS="false" 并连接到标准明文端口 389。
• 如果打算使用 LDAPS： 确保您的 LDAP 服务器已配置 TLS 并监听端口 636。设置 LDAP_SERVER_PORT="636" 和 LDAP_USE_TLS="true"。
• 如果打算使用 StartTLS： 您的 LDAP 服务器必须支持 StartTLS 扩展。在端口 389 上连接并设置 LDAP_USE_TLS="true"。

err=49 text=（凭据无效）

openldap | ... conn=1001 op=0 RESULT tag=97 err=49 text=

原因： LDAP 服务器拒绝了绑定尝试，因为识别名（DN）或密码不正确。这发生在第二次绑定尝试时，Open WebUI 尝试使用用户提供的凭据进行身份认证。

解决方案：

1. 验证密码： 确保使用的是正确的明文密码。LDIF 文件中的 userPassword 值就是服务器期望的。如果是哈希值，必须提供原始明文密码。

2. 检查用户 DN： 用于绑定的 DN（uid=jdoe,ou=users,dc=example,dc=org）必须正确。

3. 使用 ldapwhoami 测试： 直接对 LDAP 服务器验证凭据，将问题与 Open WebUI 隔离。

   ldapwhoami -x -H ldap://localhost:389 \
     -D "uid=jdoe,ou=users,dc=example,dc=org" -w "password123"

   如果该命令以 ldap_bind: Invalid credentials (49) 失败，那么问题出在凭据本身或 LDAP 服务器的密码配置上，而不是 Open WebUI。

4. 重置密码： 如果不知道密码，可使用 ldapmodify 或 ldappasswd 重置。在初次测试时，通常最简单的做法是先使用 {PLAIN} 密码，然后再切换到 {SSHA} 这样的安全哈希。

   修改密码的 LDIF 示例：

   change_password.ldif

   dn: uid=jdoe,ou=users,dc=example,dc=org
   changetype: modify
   replace: userPassword
   userPassword: {PLAIN}newpassword

   应用方法：

   docker exec openldap ldapmodify -x -D "cn=admin,dc=example,dc=org" -w admin -f /path/to/change_password.ldif