ldap_exop_passwd — Funktion · PHP-Referenz

Signatur

ldap_exop_passwd(LDAP\Connection $ldap, string $user = "", string $oldpw = "", string $newpw = "", array &$controls = null): string|bool

Beschreibung

ldap_exop_passwd ist eine Hilfsfunktion für die erweiterte LDAP-Operation PASSWD (RFC 3062). Sie ermöglicht es, das Passwort eines Verzeichnisbenutzers serverseitig zu ändern, ohne dafür manuelle BER-Kodierung oder ldap_exop direkt verwenden zu müssen. Wenn newpw leer gelassen wird, kann der LDAP-Server ein neues Passwort generieren und zurückgeben.

Die Funktion wird typischerweise eingesetzt, wenn Anwendungen Passwortänderungen über LDAP-Verzeichnisse wie OpenLDAP oder Active Directory (mit entsprechender Konfiguration) durchführen müssen, ohne direkten Schreibzugriff auf das userPassword-Attribut zu haben. Der Server erzwingt dabei Passwortrichtlinien auf Verzeichnisebene.

Über den optionalen controls-Parameter lassen sich LDAP-Steuerelemente (z. B. LDAP_CONTROL_PASSWORDPOLICYREQUEST) übergeben und Antwort-Steuerelemente des Servers abrufen, was detaillierte Passwortrichtlinien-Rückmeldungen ermöglicht.

Für den Aufruf ist in der Regel eine privilegierte Verbindung (als Administrator oder als der betroffene Nutzer selbst) erforderlich. Die Verbindung sollte über TLS/StartTLS abgesichert sein, da sonst Passwörter im Klartext übertragen werden könnten.

Parameter

Name	Typ	Default	Beschreibung
$ldap Pflicht	LDAP\Connection		Eine gültige LDAP-Verbindungsressource, wie sie von `ldap_connect` zurückgegeben wird.
$user	string	""	Der Distinguished Name (DN) des Benutzers, dessen Passwort geändert werden soll. Ein leerer String verwendet den aktuell gebundenen Benutzer.
$oldpw	string	""	Das bisherige (aktuelle) Passwort des Benutzers. Wird benötigt, wenn der Benutzer sein eigenes Passwort ändert. Administratoren können dieses Feld leer lassen.
$newpw	string	""	Das neue gewünschte Passwort. Wird ein leerer String übergeben, generiert der LDAP-Server automatisch ein neues Passwort und gibt es als Rückgabewert zurück.
$controls	array	null	Wird als Referenz übergeben. Enthält nach dem Aufruf die vom Server zurückgegebenen LDAP-Steuerelemente (z. B. Passwortrichtlinien-Informationen).

Rückgabewert

Typ

string|bool

Beschreibung

Gibt true zurück, wenn das Passwort erfolgreich auf den angegebenen Wert gesetzt wurde. Wurde kein neues Passwort übergeben (newpw leer), gibt die Funktion das vom Server generierte Passwort als string zurück. Im Fehlerfall wird false zurückgegeben.

Beispiele

Passwort eines LDAP-Benutzers als Administrator ändern

<?php
$ldap = ldap_connect('ldap://localhost');
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);

// Als Administrator binden
ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesAdminPasswort');

$userDN  = 'uid=mustermann,ou=users,dc=example,dc=com';
$newPass = 'NeuesPasswort!2024';

$result = ldap_exop_passwd($ldap, $userDN, '', $newPass);

if ($result === true) {
    echo 'Passwort erfolgreich geändert.';
} else {
    echo 'Fehler beim Ändern des Passworts: ' . ldap_error($ldap);
}

ldap_unbind($ldap);
?>

Passwort erfolgreich geändert.

Vom Server generiertes Passwort abrufen

<?php
$ldap = ldap_connect('ldap://localhost');
ldap_set_option($ldap, LDAP_OPT_PROTOCOL_VERSION, 3);

// StartTLS für sichere Übertragung
ldap_start_tls($ldap);

ldap_bind($ldap, 'cn=admin,dc=example,dc=com', 'geheimesAdminPasswort');

$userDN   = 'uid=neuernutzer,ou=users,dc=example,dc=com';
$controls = [];

// Neues Passwort automatisch vom Server generieren lassen
$generatedPassword = ldap_exop_passwd($ldap, $userDN, '', '', $controls);

if ($generatedPassword !== false) {
    echo 'Generiertes Passwort: ' . $generatedPassword . PHP_EOL;
    // Passwort sicher an den Nutzer übermitteln
} else {
    echo 'Fehler: ' . ldap_error($ldap);
}

ldap_unbind($ldap);
?>

Generiertes Passwort: xK9#mPqR2z

// Wichtig · Fallstricke

Sicherheitshinweis: Da Passwörter im Klartext übertragen werden, sollte die LDAP-Verbindung immer über ldap_start_tls() oder eine native LDAPS-Verbindung (ldaps://) abgesichert sein, bevor diese Funktion aufgerufen wird.

Serverkonfiguration: Nicht alle LDAP-Server unterstützen die erweiterte PASSWD-Operation (RFC 3062). OpenLDAP benötigt dafür das ppolicy- oder passwd-Overlay. Active Directory verwendet stattdessen i. d. R. die direkte Änderung des unicodePwd-Attributs.

Fehlermeldungen: Schlägt die Operation fehl (z. B. wegen unzureichender Berechtigungen oder Passwortrichtlinien), liefert ldap_error($ldap) und ldap_errno($ldap) detaillierte Fehlerinformationen. Die Auswertung des controls-Parameters kann zusätzliche Richtliniendetails enthalten.

Siehe auch

ldap_exop ldap_bind ldap_start_tls ldap_connect ldap_error ldap_modify