跳到主要内容

OpenLDAP 集成

本指南提供了使用 Open WebUI 设置 OpenLDAP 身份验证的全面演练。它涵盖了使用 Docker 创建测试 OpenLDAP 服务器、为其注入示例用户、配置 Open WebUI 连接到它以及常见问题的故障排除。

1. 使用 Docker 设置 OpenLDAP​

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

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 镜像提供了一个用于管理 LDAP 目录的 Web 界面，可通过 https://: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 生成哈希密码。例如

# Using slappasswd (inside the container)
docker exec openldap slappasswd -s your_password

# Using 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://: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 的管理设置面板中进行。

# Enable LDAP
ENABLE_LDAP="true"

# --- Server Settings ---
LDAP_SERVER_LABEL="OpenLDAP"
LDAP_SERVER_HOST="localhost"  # Or the IP/hostname of your LDAP server
LDAP_SERVER_PORT="389"        # Use 389 for plaintext/StartTLS, 636 for LDAPS
LDAP_USE_TLS="false"          # Set to "true" for LDAPS or StartTLS
LDAP_VALIDATE_CERT="false"    # Set to "true" in production with valid certs

# --- Bind Credentials ---
LDAP_APP_DN="cn=admin,dc=example,dc=org"
LDAP_APP_PASSWORD="admin"

# --- User Schema ---
LDAP_SEARCH_BASE="dc=example,dc=org"
LDAP_ATTRIBUTE_FOR_USERNAME="uid"
LDAP_ATTRIBUTE_FOR_MAIL="mail"
LDAP_SEARCH_FILTER="(uid=%(user)s)" # More secure and performant

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` 文件或导出命令中的 `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= (Invalid Credentials)​

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://: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