repo_zf1/documentation/manual/de/module_specs/Zend_Auth_Adapter_Ldap.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.auth.adapter.ldap">
    <title>LDAP Authentifizierung</title>

    <sect2 id="zend.auth.adapter.ldap.introduction">
        <title>Einführung</title>

        <para>
            <classname>Zend_Auth_Adapter_Ldap</classname> unterstützt Webanwendungen bei der
            Authentifizierung mit <acronym>LDAP</acronym> Services. Die Features beinhalten
            Kanonisierung von Benutzernamen und Domainnamen, Mehrfach-Domain Authentifizierung, und
            Fehlerbehandlungs Features. Es wurde getestet mit <ulink
                url="http://www.microsoft.com/windowsserver2003/technologies/directory/activedirectory/">Microsoft
                Active Directory</ulink> und <ulink url="http://www.openldap.org/">OpenLDAP</ulink>,
            sollte auch mit anderen <acronym>LDAP</acronym> Service Provider zusammenarbeiten.
        </para>

        <para>
            Diese Dokumentation enthält eine Anleitung der Verwendung von
            <classname>Zend_Auth_Adapter_Ldap</classname>, eine Beschreibung der
            <acronym>API</acronym>, 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.
        </para>
    </sect2>

    <sect2 id="zend.auth.adapter.ldap.usage">
        <title>Verwendung</title>

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

        <programlisting language="php"><![CDATA[
$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);
        }
    }
}
]]></programlisting>

        <para>
            Natürlich ist der Logging Code optional, aber es wird dringend empfohlen einen Logger
            zu verwenden. <classname>Zend_Auth_Adapter_Ldap</classname> zeichnet fast jedes
            Bisschen an Information in <varname>$messages</varname> auf das irgendwer benötigen
            können (mehr anbei), was allerdings selbst ein nettes Feature für jemanden als History
            ist, kann überaus schwierig zu debuggen sein.
        </para>

        <para>
            Der <classname>Zend_Config_Ini</classname> 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
            <filename>application/config/config.ini</filename> 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 <emphasis>Server
                Optionen</emphasis> weiter unten. Es ist zu beachten das
            <classname>Zend_Config_Ini</classname> jeden Wert der mit Gleichheitszeichen
            (<emphasis>=</emphasis>) geschrieben wird auch unter Anführungszeichen gesetzt wird
            (wie unten bei DNs gezeigt).
        </para>

        <programlisting language="ini"><![CDATA[
[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"
]]></programlisting>

        <para>
            Die obige Konfiguration instruiert <classname>Zend_Auth_Adapter_Ldap</classname> das es
            versuchen soll Benutzer zuerst mit dem OpenLDAP Server <filename>s0.foo.net</filename>
            authentifizieren soll. Wenn die Authentifizierung auf irgendeinem Grund fehlschlägt,
            wird der AD Server <filename>dc1.w.net</filename> versucht.
        </para>

        <para>
            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.
        </para>

        <para>
            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
            <emphasis>Kanonifizierung von Benutzernamen</emphasis> Kapitel anbei).
        </para>
    </sect2>

    <sect2 id="zend.auth.adapter.ldap.api">
        <title>Die API</title>

        <para>
            Der <classname>Zend_Auth_Adapter_Ldap</classname> Konstruktor akzeptiert drei Parameter.
        </para>

        <para>
            Der <varname>$options</varname> 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
            <emphasis>Array von Arrays</emphasis> von <link
                linkend="zend.ldap"><classname>Zend_Ldap</classname></link> Optionen handelt. Selbst
            wenn nur ein einzelner <acronym>LDAP</acronym> Server verwendet wird, müssen die
            Optionen trotzdem in einem anderen Array sein.
        </para>

        <para>
            Anbei ist eine <ulink
                url="http://php.net/print_r"><methodname>print_r()</methodname></ulink>
            Ausgabe von beispielhaften Optionsparameters die zwei Sets von Serveroptionen für
            <acronym>LDAP</acronym> Server enthalten, <filename>s0.foo.net</filename> und
            <filename>dc1.w.net</filename> (die gleichen Optionen wie in der oberen
            <acronym>INI</acronym> Repräsentation):
        </para>

        <programlisting language="output"><![CDATA[
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
        )

)
]]></programlisting>

        <para>
            Die oben angebotene Information in jedem Set von Optionen ist hauptsächlich deswegen
            unterschiedlich weil AD keinen Benutzernamen während des Bindesn in der DN Form benötigt
            (siehe die <property>bindRequiresDn</property> Option des
            <emphasis>Server Optionen</emphasis> Kapitels weiter unten), was bedeutet das die
            Anzahl der, mit dem Empfangen der DN, für einen Benutzernamen der Authentifiziert
            werden soll, assoziierten Optionen, unterdrückt werden kann.
        </para>

        <note>
            <title>Was ist ein ausgezeichneter Name?</title>

            <para>
                Ein DN oder "distinguished name" ist ein String der den Pfad zu einem Objekt im
                <acronym>LDAP</acronym> 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
                <emphasis>CN=Bob Carter,CN=Users,DC=w,DC=net</emphasis> direkt in
                <emphasis>CN=Users,DC=w,DC=net container</emphasis> enthalten. Diese Struktur wird
                am besten mit einem <acronym>LDAP</acronym> Browser wie das <acronym>ADSI</acronym>
                Edit <acronym>MMC</acronym> snap-in für Active Directory oder phpLDAPadmin erkundet.
            </para>
        </note>

        <para>
            Die Namen von Servern (z.B. 'server1' und 'server2' wie unten gezeigt) sind großteils
            beliebig, aber aus Gründen der Verwendung von <classname>Zend_Config</classname>
            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 '<emphasis>.</emphasis>' <acronym>INI</acronym>
            Eigenschafts Separator, '<emphasis>&amp;</emphasis>' für <acronym>XML</acronym> Entity
            Referenzen, usw.).
        </para>

        <para>
            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.
        </para>

        <note>
            <title>Die glorreichen Details: Was passiert bei der Authentifizierungs Methode?</title>

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

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

    <sect2 id="zend.auth.adapter.ldap.server-options">
        <title>Server Optionen</title>

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

        <table id="zend.auth.adapter.ldap.server-options.table">
            <title>Server Optionen</title>

            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Name</entry>
                        <entry>Beschreibung</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><emphasis><property>host</property></emphasis></entry>

                        <entry>
                            Der Hostname des <acronym>LDAP</acronym> Servers der diese Optionen
                            repräsentiert. Diese Option wird benötigt.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>port</property></emphasis></entry>

                        <entry>
                            Der Port auf den der <acronym>LDAP</acronym> Server schaut. Wenn
                            <emphasis>useSsl</emphasis> <constant>TRUE</constant> ist, ist der
                            Standardwert von <property>port</property> 636. Wenn
                            <property>useSsl</property> <constant>FALSE</constant> ist, ist der
                            Standardwert von <property>port</property> 389.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>useStartTls</property></emphasis></entry>

                        <entry>
                            Ob der <acronym>LDAP</acronym> Client einen <acronym>TSL</acronym> (aka
                            <acronym>SSL</acronym>v2) verschlüsselten Transport verwenden soll oder
                            nicht. Der Wert <constant>TRUE</constant> wird in einer
                            Produktionsumgebung strengstens empfohlen um zu verhindern das
                            Passwörter im Klartext übertragen werden. Der Standardwert ist
                            <constant>FALSE</constant>, da Server typischerweise nach deren
                            Installation erwarten das ein Zertifikat installiert wird. Die
                            <property>useSsl</property> und <property>useStartTls</property>
                            Optionen schließen sich gegenseitig aus. Die
                            <property>useStartTls</property> Option sollte über
                            <property>useSsl</property> favorisiert werden, aber nicht alle Server
                            unterstützen diesen neueren Mechanismus.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>useSsl</property></emphasis></entry>

                        <entry>
                            Ob der <acronym>LDAP</acronym> Client einen <acronym>SSL</acronym>
                            verschlüsselten Transport verwenden soll. Die
                            <property>useSsl</property> und <property>useStartTls</property>
                            Optionen schließen sich gegenseitig aus, aber
                            <property>useStartTls</property> sollte favorisiert werden wenn der
                            Server und die <acronym>LDAP</acronym> Bibliothek des Clients diese
                            unterstützen. Dieser Wert ändert auch den Standardwert von
                            <property>port</property> (siehe die <property>port</property>
                            Beschreibung weiter oben).
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>username</property></emphasis></entry>

                        <entry>
                            Der DN des Accounts der verwendet wird um DN Account Loopups
                            durchzuführen. <acronym>LDAP</acronym> Server die den Benutzernamen
                            in DN Form benötigen wenn "bind" durchgeführt wird, benötigen diese
                            Option. Wenn <property>bindRequiresDn</property>
                            <constant>TRUE</constant> ist, wird diese Option benötigt. Dieser
                            Account muß kein privilegierter Account sein - ein Account mit nur-lese
                            Zugriff zu Objekten unter <property>baseDn</property> ist alles was
                            notwendig ist (und bevorzugt unter dem <emphasis>Prinzip des geringsten
                            Privilegs</emphasis>).
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>password</property></emphasis></entry>

                        <entry>
                            Das Passwort des Accounts der verwendet wird um DN Lookups
                            durchzuführen. Wenn diese Option nicht unterstützt wird, versucht der
                            <acronym>LDAP</acronym> Client einen "anonymen bind" wenn DN Lookups
                            durchgeführt werden.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>bindRequiresDn</property></emphasis></entry>

                        <entry>
                            Einige <acronym>LDAP</acronym> Server benötigen den zum Binden
                            verwendeten Benutzernamen in der DN Form wie
                            <emphasis>CN=Alice Baker,OU=Sales,DC=foo,DC=net</emphasis>
                            (grundsätzlich alle Server <emphasis>außer</emphasis> AD). Wenn diese
                            Option <constant>TRUE</constant> ist, instuiert dies
                            <classname>Zend_Ldap</classname> das der DN automatisch empfangen wird,
                            abhängig vom Benutzernamen der authentifiziert wird, wenn er nicht
                            bereits in DN Form ist, und diesen dann wieder mit der richtigen DN zu
                            binden. Der Standardwert ist <constant>FALSE</constant>. Aktuell ist nur
                            von Microsoft Active Directory Server (<acronym>ADS</acronym>) bekannt
                            das es den Benutzernamen <emphasis>nicht</emphasis> in der DN Form
                            benötigt wenn gebunden wird, und deswegen kann diese Option mit AD auch
                            <constant>FALSE</constant> sein (und sollte das auch, da das Empfangen
                            des DN eine extra Anfrage zum Server benötigt). Andernfalls muß diese
                            Option auf <constant>TRUE</constant> gesetzt werden (z.B. für OpenLDAP).
                            Diese Option kontrolliert das Standard
                            <property>acountFilterFormat</property> das verwendet wird wenn nach
                            Accounts gesucht wird. Siehe auch die
                            <property>accountFilterFormat</property> Option.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>baseDn</property></emphasis></entry>

                        <entry>
                            Der Ort vom DN unter dem alle Accounts die authentifiziert werden. Diese
                            Option wird benötigt. Wenn man sich unsicher über den richtigen
                            <property>baseDn</property> ist, sollte es genug sein Ihn von
                            der <acronym>DNS</acronym> Domain des Benutzers der die
                            <emphasis>DC=</emphasis> Komponenten verwedet abzuleiten. Wenn der
                            Hauptname eines Benutzers <filename>alice@foo.net</filename> ist, sollte
                            ein <property>baseDn</property> von <emphasis>DC=foo,DC=net</emphasis>
                            funktionieren. Eine präzisere Ortsangabe
                            (z.B. <emphasis>OU=Sales,DC=foo,DC=net</emphasis>) ist trotzdem
                            effizienter.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>accountCanonicalForm</property></emphasis></entry>

                        <entry>
                            Ein Wert von 2, 3 oder 4 zeigt die Form zu der Account Namen
                            authorisiert werden sollten nachdem die Authentifizierung erfolgreich
                            war. Die Werte sind wie folgt: 2 für traditionelle Benutzernamen-Stil
                            Namen (z.B., <emphasis>alice</emphasis>), 3 für Schrägstrich-Stil Namen
                            (z.B., <filename>FOO\alice</filename>) oder 4 für Authentifiziert-Sil
                            Namen (z.B., <filename>alice@foo.net</filename>). Der Standardwert ist 4
                            (z.B., <filename>alice@foo.net</filename>). Mit einem Wert von 3, z.B.,
                            wird die Identität die von
                            <methodname>Zend_Auth_Result::getIdentity()</methodname> zurückgegeben
                            wird (und <methodname>Zend_Auth::getIdentity()</methodname>, wenn
                            <classname>Zend_Auth</classname> verwendet wird), immer
                            <filename>FOO\alice</filename> sein, unabhängig von der Form in der
                            Alice angegeben wurde, egal ob es <emphasis>alice</emphasis>,
                            <filename>alice@foo.net</filename>, <filename>FOO\alice</filename>,
                            <filename>FoO\aLicE</filename>, <filename>foo.net\alice</filename>, etc.
                            Siehe das Kapitel <emphasis>Kanonisierung von Account Namen</emphasis>
                            in der <classname>Zend_Ldap</classname> Dokumentation für Details. Bei
                            der Verwendung von mehreren Sets von Serveroptionen ist es
                            empfehlenswert, aber nicht notwendig, das die selbe
                            <property>accountCanonicalForm</property> in allen
                            Serveroptionen verwendet wird, sodas die sich ergebenden Benutzernamen
                            immer auf die selbe Art und Weise kanonisiert werden (z.b. wenn man auf
                            <filename>EXAMPLE\username</filename> mit einem AD Server kanonisiert,
                            aber zu <filename>username@example.com</filename> mit einem OpenLDAP
                            Server, kann das quirks für die High-Level Logik einer Anwendung sein).
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>accountDomainName</property></emphasis></entry>

                        <entry>
                            Der <acronym>FQDN</acronym> Domainname für welchen der Ziel
                            <acronym>LDAP</acronym> Server eine Authorität ist (z.B.,
                            <filename>example.com</filename>). Diese Option wird verwendet um Namen
                            zu kanonisieren sodas der Benutzername der vom Benutzer angeboten wird,
                            wie es für das Binden notwendig ist, konvertiert werden kann. Er wird
                            auch verwendet um festzustellen ob der Server eine Authorität für den
                            angegebenen Benutzernamen ist (z.B., wenn
                            <property>accountDomainName</property> <filename>foo.net</filename> ist
                            und der angegebene Benutzer <filename>bob@bar.net</filename>, wird der
                            Server nicht abgefragt, und das Ergebnis wird ein Fehler sein). Diese
                            Option wird nicht benötigt, aber wenn Sie nicht angegeben wird, dann
                            werden Benutzernamen in prinzipieller Namensform (z.B.,
                            <filename>alice@foo.net</filename>) nicht unterstützt. Es wird stark
                            empfohlen das diese Option angegeben wird, da es viele Anwendungsfälle
                            gibt welche die Erstellung von prinzipieller Namensform benötigen.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>accountDomainNameShort</property></emphasis></entry>

                        <entry>
                            Die 'short' Domain für die der Ziel <acronym>LDAP</acronym> Server eine
                            Authorität ist (z.B., <acronym>FOO</acronym>). Es ist z ubeachten das
                            es ein 1:1 Mapping zwischen <property>accountDomainName</property> und
                            <property>accountDomainNameShort</property> existiert. Diese
                            Option sollte verwendet werden um den NetBIOS Domainnamen für Windows
                            Netzwerke zu spezifizieren, kann aber auch von nicht-AD Servern
                            verwendet werden (z.B., für Konsistenz bei mehreren Sets von
                            Serveroptionen bei dem Schrägstrich Stil
                            <property>accountCanonicalForm</property>). Diese Option wird nicht
                            benötigt, aber wenn Sie nicht angegeben wird, werden Benutzernamen im
                            Schrägstrich Stil (z.B. <filename>FOO\alice</filename>) nicht
                            unterstützt.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>accountFilterFormat</property></emphasis></entry>

                        <entry>
                            Der <acronym>LDAP</acronym> Suchfilter der für die Suche nach Accounts
                            verwendet wird. Dieser String ist ein <ulink
                                url="http://php.net/printf"><methodname>printf()</methodname></ulink>-Stil
                            Ausdruck der ein '<emphasis>%s</emphasis>' enthalten muß um den
                            Benutzernamen unterzubringen. Der Standardwert ist
                            '<emphasis>(&amp;(objectClass=user)(sAMAccountName=%s))</emphasis>',
                            ausgenommen <property>bindRequiresDn</property> wird auf
                            <constant>TRUE</constant> gesetzt. In diesem Fall ist der Standardwert
                            '<emphasis>(&amp;(objectClass=posixAccount)(uid=%s))</emphasis>'. Wenn,
                            zum Beispiel, aus irgendeinem Grund
                            <emphasis>bindRequiresDn = true</emphasis> mit AD verwendet werden soll,
                            muß <emphasis>accountFilterFormat =
                                '(&amp;(objectClass=user)(sAMAccountName=%s))</emphasis>' gesetzt
                            werden.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>optReferrals</property></emphasis></entry>

                        <entry>
                            Wenn sie auf <constant>TRUE</constant> gesetzt wird, zeigt diese Option
                            dem <acronym>LDAP</acronym> Client an, das Referenzen gefolgt werden
                            soll. Der Standardwert ist <constant>FALSE</constant>.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <para>
                Wenn <emphasis>useStartTls = <constant>TRUE</constant></emphasis> oder
                <emphasis>useSsl = <constant>TRUE</constant></emphasis> aktiviert ist, erzeugt der
                <acronym>LDAP</acronym> Client einen Fehler der aussagt das er das Zertifikat des
                Servers nicht überprüfen kann. Angenommen die <acronym>PHP</acronym>
                <acronym>LDAP</acronym> Erweiterung ist ultimativ verlinkt mit der OpenLDAP Client
                Bibliothek, muß man um dieses Problem zu lösen
                "<command>TLS_REQCERT never</command>" im OpenLDAP Client
                <filename>ldap.conf</filename> 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
                <acronym>LDAP</acronym> Servers exportiert und auf den Webserver gegeben werden so
                dass der OpenLDAP Client die Identität des Servers prüfen kann.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.auth.adapter.ldap.debugging">
        <title>Debug Nachrichten sammeln</title>

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

        <table id="zend.auth.adapter.ldap.debugging.table">
            <title>Debug Nachrichten</title>

            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Array Index der Nachricht</entry>
                        <entry>Beschreibung</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>Index 0</entry>

                        <entry>
                            Eine generelle, Benutzerfreundliche Meldung die für die Anzeige für
                            Benutzer passt (z.B. "Ungültige Anmeldedaten"). Wenn die
                            Authentifizierung erfolgreich ist, dann ist dieser String leer.
                        </entry>
                    </row>

                    <row>
                        <entry>Index 1</entry>

                        <entry>
                            Eine detailiertere Fehlermeldung die nicht für die Anzeige für Benutzer
                            hergenommen werden kann, die aber mitgeloggt werden sollte zum Vorteil
                            des Server Operators. Wenn die Authentifizierung erfolgreich war, ist
                            dieser String leer.
                        </entry>
                    </row>

                    <row>
                        <entry>Indezes 2 und höher</entry>
                        <entry>Alle Logmeldungen in Reihenfolge starten bei Index 2.</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Aus der Praxis heraus sollte der Index 0 dem Benutzer angezeigt werden (z.B. bei
            Verwendung des FlashMessenger Helfers), Index 1 sollte geloggt werden und, wenn die
            Debugging Information gesammelt wird, sollten die Indezes 2 und höher auch geloggt
            werden (auch wenn die letzte Nachricht immer den String vom Index 1 enthält).
        </para>
    </sect2>

    <sect2 id="zend.auth.adapter.ldap.options-common-server-specific">
        <title>Übliche Optionen für spezielle Server</title>

        <sect3 id="zend.auth.adapter.ldap.options-common-server-specific.active-directory">
            <title>Optionen für Active Directory</title>

            <para>
                Für <acronym>ADS</acronym> sind die folgenden Optionen beachtenswert:
            </para>

            <table
                id="zend.auth.adapter.ldap.options-common-server-specific.active-directory.table">
                <title>Optionen für Active Directory</title>

                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Name</entry>
                            <entry>Zusätzliche Notizen</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><emphasis><property>host</property></emphasis></entry>
                            <entry>Wie bei allen Servern, wird diese Option benötigt.</entry>
                        </row>

                        <row>
                            <entry><emphasis><property>useStartTls</property></emphasis></entry>

                            <entry>
                                Zum Zwecke der Sicherheit, sollte das <constant>TRUE</constant> sein
                                wenn der Server das notwendige Zertifikat installiert hat.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>useSsl</property></emphasis></entry>

                            <entry>
                                Möglicherweise als Alternative zu <emphasis>useStartTls</emphasis>
                                zu verwenden (siehe davor).
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>baseDn</property></emphasis></entry>

                            <entry>
                                Wie bei allen Servern, wird diese Option benötigt. Standardmäßig
                                platziert AD alle Benutzer Accounts unter dem
                                <emphasis>Users</emphasis> Container (z.B.,
                                <emphasis>CN=Users,DC=foo,DC=net</emphasis>), aber der Standard ist
                                in größeren Organisationen nicht üblich. Der AD Administrator sollte
                                nach der besten DN für Accounts für die eigene Anwendung gefragt
                                werden.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>accountCanonicalForm</property></emphasis></entry>

                            <entry>
                                Das wird man normalerweise für Schrägstrich-Stil Namen auf 3 stellen
                                (z.B., <filename>FOO\alice</filename>), was für Windows Benutzer am
                                bekanntesten ist. Man sollte <emphasis>nicht</emphasis> die
                                unqualifizierte Form 2 verwenden (z.B., <emphasis>alice</emphasis>),
                                da das anderen Benutzern Zugriff auf die Anwendung geben würde, wenn
                                Sie den gleichen Benutzernamen in anderen vertrauten Domains haben
                                (z.B., <filename>BAR\alice</filename> und
                                <filename>FOO\alice</filename> würden als der gleiche Benutzer
                                behandelt). (siehe auch die Notiz anbei.)
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>accountDomainName</property></emphasis></entry>

                            <entry>
                                Das wird mit AD benötigt, ausser
                                <property>accountCanonicalForm</property> 2 wird
                                verwendet, was wiederum nicht eingesetzt werden sollte.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>accountDomainNameShort</property></emphasis></entry>

                            <entry>
                                Der NetBIOS Name der Domain in der die Benutzer sind und für den der
                                AD Server die Authorität ist. Das wird benötigt wenn der
                                Schrägstrich-Stil <property>accountCanonicalForm</property>
                                verwendet wird.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <note>
                <para>
                    Technisch sollte es keine Probleme mit irrtümlichen Domain-übergreifenden
                    Authentifizierungen mit der aktuellen
                    <classname>Zend_Auth_Adapter_Ldap</classname> Implementation geben, da
                    Serverdomains explizit geprüft werden, aber das muss für zukünftige
                    Implementationen, welche die Domain während der Laufzeit ermitteln, nicht wahr
                    sein, oder auch wenn ein alternativer Adapter verwendet wird (z.B., Kerberos).
                    Generell ist bekannt das die Mehrdeutigkeit von Accountnamen ein
                    Sicherheitsproblem ist. Man sollte deswegen immer versuchen qualifizierte
                    Accountnamen zu verwenden.
                </para>
            </note>
        </sect3>

        <sect3 id="zend.auth.adapter.ldap.options-common-server-specific.openldap">
            <title>Optionen für OpenLDAP</title>

            <para>
                Für OpenLDAP oder einen generellen <acronym>LDAP</acronym> Server der ein typisches
                posixAccount Stil Schema verwendet sind die folgenden Optionen beachtenswert:
            </para>

            <table id="zend.auth.adapter.ldap.options-common-server-specific.openldap.table">
                <title>Optionen für OpenLDAP</title>

                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Name</entry>
                            <entry>Zusätzliche Notizen</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><emphasis><property>host</property></emphasis></entry>
                            <entry>Wie bei allen Servern, wird diese Option benötigt.</entry>
                        </row>

                        <row>
                            <entry><emphasis><property>useStartTls</property></emphasis></entry>

                            <entry>
                                Zum Zwecke der Sicherheit, sollte das <constant>TRUE</constant> sein
                                wenn der Server das notwendige Zertifikat installiert hat.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>useSsl</property></emphasis></entry>

                            <entry>
                                Möglicherweise als Alternative zu <property>useStartTls</property>
                                zu verwenden (siehe davor).
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>username</property></emphasis></entry>

                            <entry>
                                Benötigt und muß ein DN sein, da OpenLDAP den Benutzernamen in DN
                                Form benötigt wenn ein Binden durchgeführt wird. Es sollte versucht
                                werden einen nicht privilegierten Account zu verwenden.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>password</property></emphasis></entry>

                            <entry>
                                Das Passwort das zum Benutzernamen von oben gehört. Es kann aber
                                unterdrückt werden wenn der <acronym>LDAP</acronym> Server anonymes
                                Binden bei Abfragen zu Benutzer Accounts erlaubt.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>bindRequiresDn</property></emphasis></entry>

                            <entry>
                                Benötigt und muß <constant>TRUE</constant> sein, da OpenLDAP den
                                Benutzernamen in DN Form benötigt wenn ein Binden durchgeführt wird.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>baseDn</property></emphasis></entry>

                            <entry>
                                Wie bei allen Servern, wird diese Option benötigt und zeigt den DN
                                in dem alle Accounts die authentifiziert werden enthalten sind.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>accountCanonicalForm</property></emphasis></entry>

                            <entry>
                                Optional, aber der Standardwert ist 4 (prinzipielle-Stil Namen wie
                                <filename>alice@foo.net</filename>) und könnte für die Benutzer
                                nicht ideal sein wenn diese Schrägstrich-Stil Namen verwendetn
                                (z.B., <filename>FOO\alice</filename>). Für Schrägstrich-Stil Namen
                                sollte der Wert 3 verwendet werden.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>accountDomainName</property></emphasis></entry>

                            <entry>
                                Benötigt es sei denn man verwendet
                                <property>accountCanonicalForm</property> 2, was nicht
                                zu empfehlen ist.
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis><property>accountDomainNameShort</property></emphasis></entry>

                            <entry>
                                Wenn AD auch nicht verwendet wird, wird dieser Wert nicht benötigt.
                                Andernfalls, wenn
                                <property>accountCanonicalForm</property> 3 verwendet
                                wird, wird diese Option benötigt und sollte ein Kurzname sein der
                                adäquat zu <property>accountDomainName</property>
                                korrespondiert (z.B., wenn
                                <property>accountDomainName</property>
                                <filename>foo.net</filename> ist, wäre ein guter
                                <property>accountDomainNameShort</property> Wert
                                <acronym>FOO</acronym>).
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>
    </sect2>
</sect1>