ldap_bind_ext — Funktion · PHP-Referenz

Signatur

ldap_bind_ext(LDAP\Connection $ldap, ?string $dn = null, ?SensitiveParameterValue|string $password = null, ?array $controls = null): LDAP\Result|false

Beschreibung

ldap_bind_ext() ist die erweiterte Variante von ldap_bind() und sendet eine LDAP-Bind-Anfrage, ohne auf die Antwort des Servers zu warten. Statt eines booleschen Ergebnisses liefert die Funktion ein LDAP\Result-Objekt zurück, das mit ldap_parse_result() oder ldap_get_option() weiterverarbeitet werden kann. Dies ist besonders nützlich, wenn LDAP-Steuerelemente (Controls) mit der Anfrage oder der Antwort ausgetauscht werden sollen.

Der Parameter controls erlaubt es, serverseitige LDAP-Steuerelemente (Server Controls) an die Bind-Anfrage anzuhängen. Dies ermöglicht erweiterte Szenarien wie das Lesen von Passwortrichtlinien-Informationen oder das Verwenden von SASL-Mechanismen in Verbindung mit der Antwort.

Wird kein dn angegeben (oder null übergeben), erfolgt ein anonymer Bind. Ein anonymer Bind erlaubt in vielen LDAP-Verzeichnissen nur lesenden Zugriff auf öffentliche Einträge. Für administrative Operationen ist stets ein authentifizierter Bind mit einem gültigen DN und Passwort notwendig.

Das zurückgegebene LDAP\Result-Objekt muss mit ldap_parse_result() ausgewertet werden, um den tatsächlichen Ergebniscode des Servers zu erhalten. Dies unterscheidet ldap_bind_ext() fundamental von ldap_bind(), das intern auf die Serverantwort wartet und direkt true oder false zurückgibt.

Parameter

Name	Typ	Default	Beschreibung
$ldap Pflicht	LDAP\Connection		Eine gültige `LDAP\Connection`-Instanz, die zuvor mit `ldap_connect()` erzeugt wurde.
$dn	?string	null	Der Distinguished Name (DN) des Benutzers, mit dem der Bind durchgeführt werden soll. `null` oder leer für einen anonymen Bind.
$password	?string	null	Das Passwort des Benutzers. `null` oder leer führt zu einem anonymen Bind, auch wenn ein DN angegeben wurde.
$controls	?array	null	Ein Array von LDAP-Steuerelementen (Server Controls), die mit der Bind-Anfrage gesendet werden sollen. Jedes Element ist ein assoziatives Array mit den Schlüsseln `oid`, `iscritical` und `value`.

Rückgabewert

Typ

LDAP\Result|false

Beschreibung

Gibt ein LDAP\Result-Objekt zurück, das mit ldap_parse_result() ausgewertet werden muss, um Erfolg oder Fehler des Binds zu bestimmen. Bei einem Fehler beim Senden der Anfrage (z. B. Verbindungsfehler) wird false zurückgegeben.

Beispiele

Authentifizierter Bind mit Ergebnisauswertung

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

$dn = 'uid=jdoe,ou=users,dc=example,dc=com';
$password = 's3cr3t';

$result = ldap_bind_ext($ldap, $dn, $password);

if ($result === false) {
    echo 'Fehler beim Senden der Bind-Anfrage.' . PHP_EOL;
} else {
    ldap_parse_result($ldap, $result, $errcode, $matcheddn, $errmsg);
    if ($errcode === LDAP_SUCCESS) {
        echo 'Bind erfolgreich.' . PHP_EOL;
    } else {
        echo 'Bind fehlgeschlagen. Fehlercode: ' . $errcode . ' – ' . $errmsg . PHP_EOL;
    }
}

ldap_unbind($ldap);
?>

Bind erfolgreich.

Bind mit Passwortrichtlinien-Steuerelement (Password Policy Control)

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

$dn = 'uid=jdoe,ou=users,dc=example,dc=com';
$password = 's3cr3t';

// OID für das Password Policy Request Control (RFC 3112 / Draft)
$controls = [
    [
        'oid'        => '1.3.6.1.4.1.42.2.27.8.5.1',
        'iscritical' => false,
        'value'      => '',
    ]
];

$result = ldap_bind_ext($ldap, $dn, $password, $controls);

if ($result === false) {
    echo 'Fehler beim Senden der Bind-Anfrage.' . PHP_EOL;
} else {
    ldap_parse_result($ldap, $result, $errcode, $matcheddn, $errmsg, $referrals, $response_controls);
    if ($errcode === LDAP_SUCCESS) {
        echo 'Bind erfolgreich.' . PHP_EOL;
        // $response_controls enthält ggf. Passwortrichtlinien-Informationen
        print_r($response_controls);
    } else {
        echo 'Bind fehlgeschlagen. Fehlercode: ' . $errcode . ' – ' . $errmsg . PHP_EOL;
    }
}

ldap_unbind($ldap);
?>

Bind erfolgreich. Array ( )

// Wichtig · Fallstricke

Sicherheitshinweis: Das Passwort wird im Klartext über die Verbindung übertragen, sofern keine TLS/SSL-Verbindung verwendet wird. Verwende stets ldaps:// oder rufe ldap_start_tls() vor dem Bind auf, um die Übertragung zu verschlüsseln.

Unterschied zu ldap_bind(): ldap_bind_ext() wartet nicht intern auf die Serverantwort und gibt stattdessen sofort ein LDAP\Result-Objekt zurück. Das Ergebnis muss zwingend mit ldap_parse_result() ausgewertet werden, da sonst kein Fehler erkannt wird.

PHP-Version: Diese Funktion setzt PHP 8.0 voraus, da erst ab dieser Version das LDAP\Connection- und das LDAP\Result-Objekt eingeführt wurden (zuvor wurden Ressourcen verwendet).

Siehe auch

ldap_bind ldap_connect ldap_unbind ldap_parse_result ldap_start_tls ldap_set_option