Zum Hauptinhalt springen

OpenLDAP Integration

Diese Anleitung bietet eine umfassende Schritt-für-Schritt-Anleitung zur Einrichtung der OpenLDAP-Authentifizierung mit Open WebUI. Sie umfasst die Erstellung eines Test-OpenLDAP-Servers mit Docker, das Befüllen mit Beispieldaten, die Konfiguration von Open WebUI zur Verbindung damit und die Fehlerbehebung bei gängigen Problemen.

1. OpenLDAP mit Docker einrichten​

Der einfachste Weg, einen Test-OpenLDAP-Server zu betreiben, ist die Verwendung von Docker. Diese docker-compose.yml-Datei erstellt einen OpenLDAP-Container und einen optionalen phpLDAPadmin-Container für eine webbasierte 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
  • Das osixia/openldap-Image erstellt automatisch eine grundlegende Organisationsstruktur mit nur LDAP_DOMAIN und LDAP_ADMIN_PASSWORD.
  • Das osixia/phpldapadmin-Image bietet eine Weboberfläche zur Verwaltung Ihres LDAP-Verzeichnisses, erreichbar unter https://:6443.

Führen Sie docker-compose up -d aus, um die Container zu starten. Bestätigen Sie, dass der LDAP-Server gestartet ist, indem Sie die Protokolle überprüfen: docker logs openldap. Sie sollten eine Meldung "started slapd" sehen.

2. Beispieldaten für einen Benutzer (LDIF) hinzufügen​

Um den Login zu testen, müssen Sie einen Beispieldaten-Benutzer zum LDAP-Verzeichnis hinzufügen. Erstellen Sie eine Datei namens seed.ldif mit folgendem Inhalt

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

Hinweis zu Passwörtern: Das Feld userPassword ist in dieser Testumgebung der Einfachheit halber auf einen Klartextwert gesetzt. In einer Produktionsumgebung sollten Sie immer ein gehashtes Passwort verwenden. Sie können ein gehashtes Passwort mit slappasswd oder openssl passwd generieren. Zum Beispiel

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

# Using openssl
openssl passwd -6 your_password

Kopieren Sie die LDIF-Datei in den Container und verwenden Sie ldapadd, um den Eintrag hinzuzufügen

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

Eine erfolgreiche Operation zeigt eine Meldung "adding new entry" an.

3. LDAP-Verbindung überprüfen​

Bevor Sie Open WebUI konfigurieren, überprüfen Sie, ob der LDAP-Server erreichbar ist und der Benutzer existiert.

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

Wenn der Befehl den Eintrag für den Benutzer jdoe zurückgibt, ist Ihr LDAP-Server bereit.

4. Open WebUI konfigurieren​

Konfigurieren Sie nun Ihre Open WebUI-Instanz, um den LDAP-Server für die Authentifizierung zu verwenden.

Umgebungsvariablen​

Setzen Sie die folgenden Umgebungsvariablen für Ihre Open WebUI-Instanz.

Info

Open WebUI liest diese Umgebungsvariablen nur beim ersten Start. Nachfolgende Änderungen müssen im Admin-Einstellungen-Panel der Benutzeroberfläche vorgenommen werden, es sei denn, Sie haben ENABLE_PERSISTENT_CONFIG=false gesetzt.

# 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-Konfiguration​

Alternativ können Sie diese Einstellungen direkt in der Benutzeroberfläche konfigurieren

  1. Melden Sie sich als Administrator an.
  2. Navigieren Sie zu Einstellungen > Allgemein.
  3. Aktivieren Sie LDAP-Authentifizierung.
  4. Füllen Sie die Felder aus, die den obigen Umgebungsvariablen entsprechen.
  5. Speichern Sie die Einstellungen und starten Sie Open WebUI neu.

5. Anmelden​

Öffnen Sie ein neues Inkognito-Browserfenster und navigieren Sie zu Ihrer Open WebUI-Instanz.

  • Login-ID: jdoe
  • Passwort: password123 (oder das von Ihnen festgelegte Passwort)

Nach erfolgreicher Anmeldung wird automatisch ein neues Benutzerkonto mit der Rolle "Benutzer" in Open WebUI erstellt. Ein Administrator kann die Rolle des Benutzers später bei Bedarf erweitern.

6. Fehlerbehebung bei gängigen Fehlern​

Hier sind Lösungen für häufige Fehler bei der LDAP-Integration.

port must be an integer

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

Ursache: Die Umgebungsvariable LDAP_SERVER_PORT wird als Zeichenkette mit Anführungszeichen übergeben (z. B. "389").

Lösung

  • Stellen Sie sicher, dass der Wert von LDAP_SERVER_PORT in Ihrer .env-Datei oder Ihrem Export-Befehl keine Anführungszeichen enthält: LDAP_SERVER_PORT=389.
  • Entfernen Sie das Protokoll (http://, ldap://) von LDAP_SERVER_HOST. Es sollte nur der Hostname oder die IP (z. B. localhost) sein.

[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)',)",) - {}

Ursache: Dies ist ein TLS-Handshake-Fehler. Der Client (Open WebUI) versucht, eine TLS-Verbindung zu initiieren, aber der Server (OpenLDAP) ist dafür nicht konfiguriert oder erwartet ein anderes Protokoll.

Lösung

  • Wenn Sie TLS nicht verwenden möchten: Setzen Sie LDAP_USE_TLS="false" und verbinden Sie sich mit dem Standard-Klartextport 389.
  • Wenn Sie LDAPS verwenden möchten: Stellen Sie sicher, dass Ihr LDAP-Server für TLS konfiguriert ist und auf Port 636 lauscht. Setzen Sie LDAP_SERVER_PORT="636" und LDAP_USE_TLS="true".
  • Wenn Sie StartTLS verwenden möchten: Ihr LDAP-Server muss die StartTLS-Erweiterung unterstützen. Verbinden Sie sich mit Port 389 und setzen Sie LDAP_USE_TLS="true".

err=49 text= (Ungültige Anmeldedaten)

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

Ursache: Der LDAP-Server hat den Bind-Versuch abgelehnt, da der Distinguished Name (DN) oder das Passwort falsch war. Dies geschieht während des zweiten Bind-Versuchs, bei dem Open WebUI versucht, sich mit den vom Benutzer bereitgestellten Anmeldedaten zu authentifizieren.

Lösung

  1. Überprüfen Sie das Passwort: Stellen Sie sicher, dass Sie das richtige Klartextpasswort verwenden. Der Wert von userPassword in der LDIF-Datei ist das, was der Server erwartet. Wenn es sich um einen Hash handelt, müssen Sie das ursprüngliche Klartextpasswort angeben.

  2. Überprüfen Sie den Benutzer-DN: Der für den Bind verwendete DN (uid=jdoe,ou=users,dc=example,dc=org) muss korrekt sein.

  3. Testen Sie mit ldapwhoami: Überprüfen Sie die Anmeldedaten direkt gegen den LDAP-Server, um das Problem von Open WebUI zu isolieren.

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

    Wenn dieser Befehl mit ldap_bind: Invalid credentials (49) fehlschlägt, liegt das Problem bei den Anmeldedaten oder der Passwortkonfiguration des LDAP-Servers, nicht bei Open WebUI.

  4. Setzen Sie das Passwort zurück: Wenn Sie das Passwort nicht kennen, setzen Sie es mit ldapmodify oder ldappasswd zurück. Oft ist es am einfachsten, ein {PLAIN}-Passwort für erste Tests zu verwenden und dann zu einem sicheren Hash wie {SSHA} zu wechseln.

    Beispiel LDIF zum Ändern des Passworts

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

    Wenden Sie es mit an

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