跳到主要内容

OpenLDAP 集成

本指南提供了有关如何在 Open WebUI 中设置 OpenLDAP 身份验证的全面演练。它涵盖了使用 Docker 创建测试 OpenLDAP 服务器、导入测试用户、配置 Open WebUI 进行连接以及排除常见故障。

1. 使用 Docker 设置 OpenLDAP​

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

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
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 仅在首次启动时读取这些环境变量。除非您设置了 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"

# --- 用户 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. 导航至 Settings > General。
  3. 启用 LDAP Authentication。
  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 文件或 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，或者预期使用不同的协议。

解决方案：

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

原因： 由于可分辨名称 (DN) 或密码不正确，LDAP 服务器拒绝了绑定尝试。这发生在第二次绑定尝试期间，在此期间 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
This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.