Skip to main content

OpenLDAP 集成指南

本指南将为您提供在 Open WebUI 中设置 OpenLDAP 身份验证的详细步骤。内容涵盖：使用 Docker 创建测试 OpenLDAP 服务器、导入示例用户、配置 Open WebUI 进行连接，以及解决常见问题。

1. 使用 Docker 部署 OpenLDAP​

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

docker-compose.yml
version: "3.9"
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 镜像提供了一个 Web 界面用于管理 LDAP 目录，访问地址为 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
62: 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 仅在首次启动时读取这些环境变量。除非您设置了 ENABLE_PERSISTENT_CONFIG=false，否则后续更改必须在 UI 的管理员设置面板中进行。

# 启用 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"

# --- 用户架构 ---
LDAP_SEARCH_BASE="dc=example,dc=org"
LDAP_ATTRIBUTE_FOR_USERNAME="uid"
LDAP_ATTRIBUTE_FOR_MAIL="mail"
LDAP_SEARCH_FILTER="(uid=%(user)s)" # 更安全且性能更好

UI 界面配置​

或者，您也可以直接在 UI 界面中进行配置：

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

5. 登录测试​

打开一个新的浏览器无痕窗口，访问您的 Open WebUI 实例。

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

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

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 文件或导出命令中的 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 或预期使用不同的协议。

解决方案：

  • 如果您不打算使用 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"