Zend_Auth_Adapter_Ldap unterstützt Webanwendungen bei der Authentifizierung mit LDAP Services. Die Features beinhalten Kanonisierung von Benutzernamen und Domainnamen, Mehrfach-Domain Authentifizierung, und Fehlerbehandlungs Features. Es wurde getestet mit » Microsoft Active Directory und » OpenLDAP, sollte auch auch mit anderen LDAP Service Provider zusammenarbeiten.

Diese Dokumentation enthält eine Anleitung der Verwendung von Zend_Auth_Adapter_Ldap, eine Beschreibung der API, eine Ausgabe der verschiedenen Optionen, Diagnostische Informationen für die Fehlerbehandlung bei Authentifizierungs Problemen, und Beispiel Optionen für beide, Active Directory und OpenLDAP Server.

Um Zend_Auth_Adapter_Ldap Authentifizierung in eigene Anwendungen schnell einzubauen, selbst wenn Zend_Controller nicht verwendet wird, sollte das Fleisch des eigenen Codes in etwa wie folgt aussehen:

$username = $this->_request->getParam('username');
$password = $this->_request->getParam('password');

$auth = Zend_Auth::getInstance();

$config = new Zend_Config_Ini('../application/config/config.ini',
                              'production');
$log_path = $config->ldap->log_path;
$options = $config->ldap->toArray();
unset($options['log_path']);

$adapter = new Zend_Auth_Adapter_Ldap($options, $username,
                                      $password);

$result = $auth->authenticate($adapter);

if ($log_path) {
    $messages = $result->getMessages();

    $logger = new Zend_Log();
    $logger->addWriter(new Zend_Log_Writer_Stream($log_path));
    $filter = new Zend_Log_Filter_Priority(Zend_Log::DEBUG);
    $logger->addFilter($filter);

    foreach ($messages as $i => $message) {
        if ($i-- > 1) { // $messages[2] und höher sind Log Nachrichten
            $message = str_replace("\n", "\n  ", $message);
            $logger->log("Ldap: $i: $message", Zend_Log::DEBUG);
        }
    }
}

Der Zend_Config_Ini wird oben verwendet um die Optionen des Adapters zu laden. Er ist also auch optional. Ein reguläres Array würde genauso gut arbeiten. Das folgende ist eine Beispiel application/config/config.ini Datei die Optionen für zwei separate Server hat. Mit mehreren Sets von Server Optionen versucht der Adapter jede in Reihenfolge bis die Zugangsdaten erfolgreich authentifiziert wurden. Die Namen der Server (z.B., server1 und server2) sind sehr verallgemeinert. Für Details betreffend dem Array für Optionen, siehe das Kapitel über Server Optionen weiter unten. Es ist zu beachten das Zend_Config_Ini jeden Wert der mit Gleichheitszeichen (=) geschrieben wird auch unter Anführungszeichen gesetzt wird (wie unten bei DNs gezeigt).

[production]

ldap.log_path = /tmp/ldap.log

; Typische Optionen für OpenLDAP
ldap.server1.host = s0.foo.net
ldap.server1.accountDomainName = foo.net
ldap.server1.accountDomainNameShort = FOO
ldap.server1.accountCanonicalForm = 3
ldap.server1.username = "CN=user1,DC=foo,DC=net"
ldap.server1.password = pass1
ldap.server1.baseDn = "OU=Sales,DC=foo,DC=net"
ldap.server1.bindRequiresDn = true

; Typische Optionen für Active Directory
ldap.server2.host = dc1.w.net
ldap.server2.useStartTls = true
ldap.server2.accountDomainName = w.net
ldap.server2.accountDomainNameShort = W
ldap.server2.accountCanonicalForm = 3
ldap.server2.baseDn = "CN=Users,DC=w,DC=net"

Mit Servern in verschiedenen Domains, zeigt diese Konfiguration Multi-Domain Authentifizierung. Es können auch mehrere Server in der gleichen Domain sein um Redundanz anzubieten.

In diesem Fall ist zu beachten das, selbst wenn OpenLDAP keine Notwendigkeit für kurze NetBIOS Stil Domainnamen hat die von Windows verwendet werden bieten wir Sie hier an wegen der Kanonifizierung der Namen (beschrieben im Kanonifizierung von Benutzernamen Kapitel anbei).

Der Zend_Auth_Adapter_Ldap Konstruktor akzeptiert drei Parameter.

Der $options Parameter wird benötigt und muß ein Array sein das ein oder mehrere Sets von Optionen enthält. Es ist zu beachten das es sich um Array von Arrays von Zend_Ldap Optionen handelt. Selbst wenn nur ein einzelner LDAP Server verwendet wird, müssen die Optionen trotzdem in einem anderen Array sein.

Anbei ist eine » print_r() Ausgabe von beispielhaften Optionsparameters die twei Sets von Serveroptionen für LDAP Server enthalten, s0.foo.net und dc1.w.net (die gleichen Optionen wie in der oberen INI Repräsentation):

Array
(
    [server2] => Array
        (
            [host] => dc1.w.net
            [useStartTls] => 1
            [accountDomainName] => w.net
            [accountDomainNameShort] => W
            [accountCanonicalForm] => 3
            [baseDn] => CN=Users,DC=w,DC=net
        )

    [server1] => Array
        (
            [host] => s0.foo.net
            [accountDomainName] => foo.net
            [accountDomainNameShort] => FOO
            [accountCanonicalForm] => 3
            [username] => CN=user1,DC=foo,DC=net
            [password] => pass1
            [baseDn] => OU=Sales,DC=foo,DC=net
            [bindRequiresDn] => 1
        )

)

Hinweis: Was ist ein ausgezeichneter Name?
Ein DN oder "distinguished name" ist ein String der den Pfad zu einem Objekt im LDAP Verzeichnis repräsentiert. Jede komma-seperierte Komponente ist ein Attribut und Wert der einen Node repräsentiert. Die Komponenten werden rückwirkend evaluiert. Zum Beispiel ist der Benutzeraccount CN=Bob Carter,CN=Users,DC=w,DC=net direkt in CN=Users,DC=w,DC=net container enthalten. Diese Struktur wird am besten mit einem LDAP Browser wie das ADSI Edit MMC snap-in für Active Directory oder phpLDAPadmin erkundet.

Die Namen von Servern (z.B. 'server1' und 'server2' wie unten gezeigt) sind großteils beliebig, aber aus Gründen der Verwendung von Zend_Config sollten die Identifikatoren (im Gegensatz dazu das Sie nummerische Indezes sind) vorhanden sein, und sollten keine spezielle Zeichen enthalten die vom assoziierten Dateiformat verwendet werden (z.B. der '.' INI Eigenschafts Separator, '&' für XML Entity Referenzen, usw.).

Mit mehreren Sets von Serveroptionen, kann der Adapter Benutzer in mehreren Domains authentifizieren und bietet ein Failover damit, wenn ein Server nicht erreichbar ist, ein anderer abgefragt wird.

Hinweis: Die glorreichen Details: Was passiert bei der Authentifizierungs Methode?
Wenn die authenticate() Methode aufgerufen wird, iteriert der Adapter über jedes Set von Serveroptione, setzt diese auf der internen Zend_Ldap Instanz und ruft die Zend_Ldap::bind() Methode, mit dem Benutzernamen und Passwort das authentifiziert werden soll, auf. Die Zend_Ldap Klasse prüft um zu sehen ob der Benutzer mit einer Domain qualifiziert ist (hat z.B. eine Domainkomponente wie alice@foo.net oder FOO\alice). Wenn eine Domain vorhanden ist, aber mit keiner der Domainnamen der Server (foo.net oder FOO) übereinstimmt, wird eine spezielle Ausnahme geworfen und durch Zend_Auth_Adapter_Ldap gefangen, was bewirkt das der Server ignoriert wird und der nächste, in den Serveroptionen gesetzte Server, ausgewählt wird. Wenn eine Domain doch passt, oder der Benutzer keinen qualifizierten Benutzernamen angegeben hat, fährt Zend_Ldap weiter fort und versucht mit den angegebenen Zugangsdaten zu binden. Wenn das Binden nicht erfolgreich war wirft Zend_Ldap eine Zend_Ldap_Exception welche durch Zend_Auth_Adapter_Ldap gefangen wird, und das nächste Ser von Serveroptionen wird versucht. Wenn das Binden erfolgreich war, wird die Iteration gestoppt, und die authenticate() Methode des Adapters gibt ein erfolgreiches Ergebnis zurück. Wenn alle Serveroptionen ohne erfolg durchprobiert wurden, schlägt die Authentifizierung fehl, und authenticate() gibt ein Fehlerergebnis zurück mit der Fehlermeldung der letzten Iteration.

Die username und password Parameter des Zend_Auth_Adapter_Ldap Konstruktors repräsentieren die Zugangsdaten die authentifiziert werden sollen (z.B. die Zugangsdaten die durch den Benutzer über eine HTML Login Form angegeben werden). Alternativ können Sie auch mit den setUsername() und setPassword() Methoden gesetzt werden.

Jedes Set von Serveroptionen im Kontext von Zend_Auth_Adapter_Ldap besteht aus den folgenden Optionen welche, großteils ungeändert, an Zend_Ldap::setOptions() übergeben werden:

Hinweis: Wenn useStartTls = true oder useSsl = true aktiviert ist, erzeugt der LDAP Client einen Fehler der aussagt das er das Zertifikat des Servers nicht überprüfen kann. Angenommen die PHP LDAP Erweiterung ist ultimativ verlinkt mit der OpenLDAP Client Bibliothek, muß man um dieses Problem zu lösen "TLS_REQCERT niemals" im OpenLDAP Client ldap.conf setzen (und den Web Server restarten) um der OpenLDAP Client Bibliothek anzuzeigen das man dem Server vertraut. Alternativ, wenn man annimmt das der Server gehackt werden könnte kann das Basiszertifikat des LDAP Servers exportiert und auf den Webserver gegeben werdensodas der OpenLDAP Client die Identität des Servers prüfen kann.

Zend_Auth_Adapter_Ldap sammelt Debug Informationen in seiner authenticate() Methode. Diese Information wird im Zend_Auth_Result Objekt als Nachrichten gespeichert. Das von Zend_Auth_Result::getMessages() zurückgegebene Array kann wie folgt beschrieben werden: