Verzeichnisdienst (LDAP) #

Die Anbindung an LDAP oder Active Directory ist keine Kernfunktion, sondern die App user_ldap (Herkunft: ownCloud GmbH, für owncloud.online auf PHP 8.4 fortgeführt unter https://github.com/BWTECH-github/user_ldap). Sie meldet beim Server ein Benutzer- und ein Gruppen-Backend an (Application::registerBackends()), holt Konten und Gruppen aus dem Verzeichnis und prüft Anmeldungen direkt gegen den Verzeichnisserver — Passwörter werden nicht in owncloud.online gespeichert. Ein Konto entsteht in der Kontentabelle erst, wenn es sich anmeldet oder wenn ein Abgleich läuft.

App aktivieren #

sudo -u www-data php8.4 occ app:enable user_ldap

Die App verlangt in appinfo/info.xml das PHP-Modul ldap (<lib>ldap</lib>). Fehlt es, zeigt die Einstellungsseite den Hinweis „Da das PHP-Modul für LDAP nicht installiert ist, wird das Backend nicht funktionieren" (templates/settings.php prüft function_exists('ldap_connect')). Prüfen lässt sich das mit:

php8.4 -m | grep ldap

Die Oberfläche liegt unter Einstellungen → Administration → Nutzer-Authentifizierung (AdminPanel::getSectionID() liefert authentication).

Die Seite hat vier Assistenten-Reiter — Server, Benutzer, Loginattribute, Gruppen (AdminPanel::getPanel()) — sowie die beiden Bereiche Fortgeschritten und Experte.

Mehrere Verzeichnisse: Konfigurations-IDs #

Jede Verbindung liegt unter einem eigenen Präfix in oc_appconfig für die App user_ldap. Neue Präfixe werden fortlaufend als s01, s02, … vergeben (Helper::nextPossibleConfigurationPrefix()). Diese ID ist das Argument configID der Konfigurationsbefehle ldap:show-config, ldap:set-config, ldap:test-config, ldap:create-empty-config und ldap:delete-config; ldap:search, ldap:check-user und ldap:invalidate-cache kennen es nicht.

# neue, leere Konfiguration anlegen (ID wird vergeben oder vorgegeben)
sudo -u www-data php8.4 occ ldap:create-empty-config
sudo -u www-data php8.4 occ ldap:create-empty-config s02

# vorhandene Konfigurationen anzeigen
sudo -u www-data php8.4 occ ldap:show-config

Nur Konfigurationen mit ldap_configuration_active = 1 werden beim Anmelden und Suchen benutzt; alle anderen überspringt Connection::establishConnection() stillschweigend.

Verbindung und Zugangsdaten #

Reiter Server. Die Schlüsselnamen in der Tabelle sind die Namen, die ldap:set-config und ldap:show-config verwenden (Configuration::getConfigTranslationArray()).

Drei Punkte, die Connection selbst korrigiert oder bemängelt (doSoftValidation() und doCriticalValidation()):

• Beginnt ldap_host mit ldaps:// und ist zugleich ldap_tls gesetzt, wird StartTLS automatisch abgeschaltet und ein Protokolleintrag geschrieben. Beides zusammen funktioniert nicht.
• Ein gesetzter Benutzer-DN ohne Passwort — oder umgekehrt — gilt als Konfigurationsfehler. Für anonymen Zugriff müssen beide Felder leer sein.
• Sind ldap_base_users beziehungsweise ldap_base_groups leer, wird ldap_base übernommen.

Setzen und prüfen von der Kommandozeile:

sudo -u www-data php8.4 occ ldap:set-config s01 ldap_host ldaps://dc01.example.org
sudo -u www-data php8.4 occ ldap:set-config s01 ldap_port 636
sudo -u www-data php8.4 occ ldap:set-config s01 ldap_dn "uid=agent,dc=example,dc=org"
sudo -u www-data php8.4 occ ldap:set-config s01 ldap_agent_password "geheim"
sudo -u www-data php8.4 occ ldap:set-config s01 ldap_base "dc=example,dc=org"
sudo -u www-data php8.4 occ ldap:set-config s01 ldap_configuration_active 1

sudo -u www-data php8.4 occ ldap:test-config s01

ldap:set-config nimmt sowohl die Datenbankschreibweise (ldap_host) als auch die interne Schreibweise (ldapHost) an; Configuration::setConfiguration() prüft beide Namensräume. Unbekannte Schlüssel werden ohne Fehlermeldung verworfen — deshalb nach jeder Änderung mit ldap:show-config gegenprüfen.

ldap:show-config ersetzt das Bind-Passwort durch ***. Mit --show-password steht es im Klartext in der Ausgabe, mit --output=json_pretty kommt die Konfiguration als JSON.

Benutzer- und Gruppenfilter #

Reiter Benutzer und Gruppen. Beide Reiter bieten dieselbe Mechanik: eine Auswahl von Objektklassen, eine Auswahl von Gruppen und darunter das Feld LDAP-Abfrage bearbeiten für den Rohfilter.

Der Assistent baut aus den Auswahlfeldern einen Filter zusammen (Wizard::composeLdapFilter()): Die Objektklassen werden mit | oder-verknüpft, die Gruppenzugehörigkeiten ebenfalls, und beide Blöcke werden mit & und-verknüpft. Bleibt beim Benutzerfilter alles leer, entsteht (objectclass=*); beim Gruppenfilter gibt es diesen Ersatz nicht, dort bleibt der Filter dann leer. Für die Gruppenauswahl auf der Benutzerseite muss der Server das Attribut memberOf unterstützen.

Bei großen Verzeichnissen ist der Assistent der falsche Weg: Er fragt beim Öffnen jedes Reiters den Server nach Objektklassen und Gruppen ab. Dafür gibt es im Reiter Server das Kästchen LDAP-Filter manuell eingeben (empfohlen für große Verzeichnisse) (ldap_experienced_admin), das diese Abfragen unterbindet.

Prüfen lässt sich das Ergebnis mit den Schaltflächen Einstellungen überprüfen und Benutzer zählen beziehungsweise … und Gruppen zählen sowie auf der Kommandozeile:

sudo -u www-data php8.4 occ ldap:search "mustermann"
sudo -u www-data php8.4 occ ldap:search "" --limit=50
sudo -u www-data php8.4 occ ldap:search "vertrieb" --group

ldap:search durchsucht alle aktiven Konfigurationen. Bei Benutzern gibt der Befehl „Anzeigename (interne Kennung)" aus, bei Gruppen nur den Namen. Die Vorgabe für --limit ist 15; --offset muss ein Vielfaches von --limit sein, sonst bricht der Befehl mit einer Meldung ab.

Anmeldefilter #

Reiter Loginattribute. Er bestimmt, womit sich ein Benutzer anmelden darf.

Der Assistent setzt den Benutzerfilter und den Anmeldeteil zusammen zu (&<Benutzerfilter><Anmeldeteil>). Für den Benutzernamen wählt er das erste vorhandene Attribut aus uid, samaccountname, cn; für die E-Mail-Adresse entsteht (|(mailPrimaryAddress=%uid)(mail=%uid)) (Wizard::composeLdapFilter(), Zweig LFILTER_LOGIN).

Der Platzhalter %uid wird beim Anmelden durch den eingegebenen Namen ersetzt (Access::fetchUsersByLoginName()). Ein Anmeldefilter ohne %uid macht die gesamte Konfiguration ungültig — Connection::doCriticalValidation() lehnt sie ab und schreibt „login filter does not contain %uid place holder" ins Protokoll.

Der Hinweistext am Kästchen LDAP-/AD-E-Mail-Adresse warnt vor einem Trugschluss: Die Anmeldung per E-Mail-Adresse hier abzuschalten wirkt erst zusammen mit der strengen Anmeldeprüfung, weil der Server andernfalls zusätzlich über die E-Mail-Adresse in der Kontentabelle sucht. Diese Einstellung steht in config/config.php:

'strict_login_enforced' => true,

Damit wird beim Prüfen des Passworts ausschließlich der eingetippte Anmeldename gegen das Backend geprüft; die zusätzliche Prüfung über die E-Mail-Adresse in der Kontentabelle entfällt (config/config.sample.php, lib/private/User/Session.php).

Zum Testen dient im selben Reiter das Feld Loginnamen testen mit der Schaltfläche Einstellungen überprüfen: Es versucht, für den eingegebenen Namen mit dem aktuellen Anmeldefilter einen DN zu ermitteln.

Attributzuordnung #

Bereich Fortgeschritten, Abschnitte Ordnereinstellungen und Spezielle Eigenschaften.

Zum Anzeigenamen: Liefert das Attribut keinen Wert, fällt UserEntry::getDisplayName() auf UserEntry::getUserId() zurück — also auf den Wert von ldap_expert_username_attr, ersatzweise auf die UUID.

Zum Kontingent prüft UserEntry::getQuota() den gelesenen Wert. Gültig sind none, default, eine Byte-Zahl wie 1234 und Angaben mit Einheit wie 1234 MB. Die Reihenfolge ist:

1. Wert aus ldap_quota_attr. Ist er unbrauchbar, landet „Invalid quota …" im Protokoll.
2. sonst ldap_quota_def; ist auch der unbrauchbar, wieder ein Protokolleintrag.
3. sonst das Kontingent aus owncloud.online selbst.

Zum Heimatverzeichnis: Der Wert von home_folder_naming_rule wird intern mit attr: vorangestellt gespeichert. Ein absoluter Pfad wird übernommen, ein relativer unter das Datenverzeichnis gehängt. Fehlt das Attribut am Eintrag, bricht die Anmeldung mit einer Ausnahme ab — es sei denn, das wird abgeschaltet:

sudo -u www-data php8.4 occ config:app:set user_ldap enforce_home_folder_naming_rule --value=false

Unter dem Feld Benutzersucheigenschaften steht der Hinweis „Jeder Attributwert wird auf 191 Zeichen gekürzt". Er bezieht sich auf die Suchbegriffe, die aus diesen Attributen in die Kontentabelle geschrieben werden — User::setSearchTerms() schneidet jeden davon nach 191 Zeichen ab.

UUID #

Die UUID identifiziert einen Eintrag dauerhaft, auch wenn sich sein DN ändert. Ohne Vorgabe probiert die App der Reihe nach entryuuid, nsuniqueid, objectguid, guid, ipauniqueid (Connection::$uuidAttributes) und merkt sich das erste Attribut, das einen Wert liefert. Überschreiben lässt sich das im Bereich Experte, Abschnitt UUID-Erkennung überschreiben:

Ein selbst gewähltes Attribut muss für Benutzer und Gruppen abrufbar und eindeutig sein. Findet die App keine UUID, schreibt sie „Cannot determine UUID for … Skipping." ins Protokoll und überspringt den Eintrag — der Benutzer existiert für owncloud.online dann nicht.

Interner Benutzername #

Bereich Experte, Abschnitt Interner Benutzername. Dieser Name ist die Kennung, unter der ein Konto intern geführt wird.

Ohne Vorgabe wird er aus der UUID gebildet (UserEntry::getUserId(), Access::dn2ocname()). Ist ldap_expert_username_attr gesetzt, stammt er aus diesem Attribut. In beiden Fällen läuft der Wert durch Access::sanitizeUsername():

• Umschrift nach ASCII (iconv mit TRANSLIT),
• Leerzeichen werden zu _,
• alles außerhalb von [a-zA-Z0-9+_.@-] fällt weg.

Die Zuordnung interner Name ↔ UUID ↔ DN steht in den Tabellen oc_ldap_user_mapping und oc_ldap_group_mapping (Mapping\UserMapping, Mapping\GroupMapping). Der DN wird nur zwischengespeichert; identifiziert wird über die UUID. Zieht ein Eintrag im Verzeichnisbaum um, findet ihn die App über die UUID wieder und schreibt den neuen DN in die Zuordnung — das Konto bleibt dasselbe.

Warum man den internen Benutzernamen nicht nachträglich ändert: Der Erklärungstext im Bereich Experte nennt die Gründe selbst — der interne Name ist der Vorgabename des Heimatverzeichnisses, er ist Bestandteil aller entfernten Adressen einschließlich der DAV-Dienste, und über ihn werden alle Metadaten gespeichert und zugeordnet. Deshalb gilt: Ist die Zuordnung einmal angelegt, bleibt sie. Änderungen an ldap_expert_username_attr oder an den UUID-Attributen wirken ausschließlich auf neu zugeordnete Konten — bestehende Zuordnungen rührt die App nicht an.

Aus demselben Grund sind die beiden Schaltflächen LDAP-Benutzernamenzuordnung löschen und LDAP-Gruppennamenzuordnung löschen im Bereich Experte keine Wartungswerkzeuge. Sie leeren die Zuordnungstabellen für alle LDAP-Konfigurationen gleichzeitig und lassen überall Reste zurück. In einer Produktivinstanz haben sie nichts zu suchen.

Wird für einen neuen Eintrag ein interner Name errechnet, den bereits ein Konto aus einem anderen Backend trägt, verweigert Access::shouldMapToUsername() die Zuordnung, und Access::dn2ocname() schreibt „Mapping collision for DN … Couldn't map to identifer" ins Protokoll. Handelt es sich um ein bestehendes LDAP-Konto, das wiederverwendet werden soll, lässt sich das freigeben:

sudo -u www-data php8.4 occ config:app:set user_ldap reuse_accounts --value=yes

Zusätzlich gibt es die Systemeinstellung ldapIgnoreNamingRules in config/config.php, die die Bereinigung oben vollständig abschaltet. Sie wird bei der Installation der App auf false gesetzt (appinfo/install.php). Wer sie einschaltet, lässt beliebige Zeichen in internen Namen zu — mit allen Folgen für Pfade und Adressen.

Abgleich per Cron #

Die App bringt keinen eigenen Hintergrund-Job mit; in appinfo/info.xml ist keiner registriert. Ohne Abgleich entsteht ein Konto erst bei der ersten Anmeldung, und ein im Verzeichnis gelöschtes Konto bleibt in owncloud.online bestehen. Der Abgleich ist der Kernbefehl user:sync (core/Command/User/SyncBackend.php):

# welche Backends sind aktiv?
sudo -u www-data php8.4 occ user:sync --list

# vollständiger Abgleich
sudo -u www-data php8.4 occ user:sync ldap --missing-account-action=disable

# nur ein Konto
sudo -u www-data php8.4 occ user:sync ldap --uid=mmustermann --missing-account-action=disable

ldap ist die Kurzform für OCA\User_LDAP\User_Proxy. Weitere Optionen:

Für den Cron-Betrieb ist --missing-account-action Pflicht: Ohne diese Option stellt der Befehl eine interaktive Rückfrage und wartet auf eine Eingabe.

Eintrag in der Cron-Tabelle des Webserver-Benutzers, hier stündlich:

sudo crontab -u www-data -e

0  *  *  *  * /usr/bin/php8.4 /var/www/owncloud.online/occ user:sync ldap --missing-account-action=disable

Der Aufruf steht hier bewusst ohne -f: Mit -f müssten die Optionen des Befehls durch -- von den Optionen von PHP getrennt werden.

Das ist unabhängig vom allgemeinen cron.php, siehe Hintergrund-Jobs (Cron). Bei großen Verzeichnissen läuft ein voller Abgleich lange; dann bietet sich an, stündlich mit --seenOnly und einmal täglich vollständig zu laufen.

Wenn ein Konto im Verzeichnis verschwindet #

Das Konto verschwindet nicht von selbst. Was tatsächlich passiert:

1. Sofort: Die Anmeldung schlägt fehl. User_LDAP::checkPassword() sucht den Eintrag über den Anmeldefilter, bekommt keinen Treffer, fängt die DoesNotExistOnLDAPException und gibt false zurück.
2. Weiterhin vorhanden: Kontozeile, Zuordnung in oc_ldap_user_mapping, Heimatverzeichnis, Dateien und Freigaben. Für andere Benutzer sieht das Konto unverändert aus, seine Freigaben funktionieren weiter.
3. Beim nächsten user:sync: analyzeExistingUsers() vergleicht die Kontentabelle gegen das Backend und behandelt den Fehlenden gemäß --missing-account-action.

Im Regelbetrieb gehört dort disable hin. remove erst, wenn geklärt ist, wer die Dateien des Kontos noch braucht; occ files:transfer-ownership überträgt sie vorher an ein anderes Konto.

Einen Einzelfall klärt der Befehl der App:

sudo -u www-data php8.4 occ ldap:check-user mmustermann

Er antwortet entweder „The user is still available on LDAP." oder „The user does not exist on LDAP anymore." und schlägt dann occ user:delete vor. Zwei Einschränkungen: Der Name muss ein zugeordneter LDAP-Benutzer sein, sonst kommt „The given user is not a recognized LDAP user."; und solange es abgeschaltete LDAP-Konfigurationen gibt, verweigert der Befehl die Auskunft („Cannot check user existence, because disabled LDAP configurations are present."), weil er den Eintrag dann nicht zuverlässig ausschließen kann. --force übergeht das.

Ein umgezogener Eintrag ist kein verschwundener Eintrag: Ändert sich nur der DN, findet ihn User_LDAP::userExists() über resolveMissingDN() anhand der UUID wieder und schreibt den neuen DN in die Zuordnung.

occ-Befehle der App #

Alle acht Befehle stehen in appinfo/info.xml unter <commands>.

ldap:test-config kennt vier Antworten:

Die Pflichtangaben, die doCriticalValidation() erzwingt, sind ldap_host, ldap_port, ldap_display_name, ldap_group_display_name, ldap_login_filter sowie mindestens ein Basis-DN.

Weitere Schlüssel #

App-Einstellungen werden über die Kernbefehle gelesen und gesetzt:

sudo -u www-data php8.4 occ config:app:get user_ldap reuse_accounts
sudo -u www-data php8.4 occ config:app:set user_ldap reuse_accounts --value=yes

Fehlersuche #

Meldungen der App stehen im Serverprotokoll unter der App-Kennung user_ldap, siehe Serverprotokoll und Fehlermeldungen.