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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15346 -->
<!-- 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 LDAP 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 auch mit anderen LDAP Service Provider zusammenarbeiten.
        </para>

        <para>
            Diese Dokumentation enthält eine Anleitung der Verwendung von
            <classname>Zend_Auth_Adapter_Ldap</classname>, 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.
        </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:
            <programlisting role="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>
            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 <code>$messages</code> 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 <code>application/config/config.ini</code>
            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., <code>server1</code> und
            <code>server2</code>) 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 (<code>=</code>) geschrieben wird auch unter Anführungszeichen
            gesetzt wird (wie unten bei DNs gezeigt).
            <programlisting role="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>
            Die obige Konfiguration instruiert <classname>Zend_Auth_Adapter_Ldap</classname> das es
            versuchen soll Benutzer zuerst mit dem OpenLDAP Server <code>s0.foo.net</code>
            authentifizieren soll. Wenn die Authentifizierung auf irgendeinem Grund fehlschlägt,
            wird der AD Server <code>dc1.w.net</code> 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 <code>$options</code> 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 LDAP 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"><code>print_r()</code></ulink>
            Ausgabe von beispielhaften Optionsparameters die twei Sets von Serveroptionen für LDAP
            Server enthalten, <code>s0.foo.net</code> und <code>dc1.w.net</code> (die gleichen
            Optionen wie in der oberen INI Repräsentation):
            <programlisting role="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>
            Die oben angebotene Information in jedem Set von Optionen ist hauptsächlich deswegen
            unterschiedlich weil AD keinen Benutzernamen wärend des Bindesn in der DN Form benötigt
            (siehe die <code>bindRequiresDn</code> 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
                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
                <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 LDAP Browser wie das ADSI Edit MMC snap-in für Active Directory
                oder phpLDAPadmin erkundet.
            </para>
        </note>

        <para>
            Die Namen von Servern (z.B. '<code>server1</code>' und '<code>server2</code>' 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 '<code>.</code>'
            INI Eigenschafts Separator, '<code>&amp;</code>' für XML 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 <code>authenticate()</code> Methode aufgerufen wird, iteriert der Adapter
                über jedes Set von Serveroptione, setzt diese auf der internen
                <classname>Zend_Ldap</classname> Instanz und ruft die
                <classname>Zend_Ldap::bind()</classname> 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 <emphasis>alice@foo.net</emphasis> oder
                <emphasis>FOO\alice</emphasis>). Wenn eine Domain vorhanden ist, aber mit keiner der
                Domainnamen der Server (<emphasis>foo.net</emphasis> oder <emphasis>FOO</emphasis>)
                ü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 Ser von
                Serveroptionen wird versucht. Wenn das Binden erfolgreich war, wird die Iteration
                gestoppt, und die <code>authenticate()</code> Methode des Adapters gibt ein
                erfolgreiches Ergebnis zurück. Wenn alle Serveroptionen ohne erfolg durchprobiert
                wurden, schlägt die Authentifizierung fehl, und <code>authenticate()</code> 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 HTML Login Form angegeben werden).
            Alternativ können Sie auch mit den <code>setUsername()</code> und
            <code>setPassword()</code> 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 <classname>Zend_Ldap::setOptions()</classname>
            übergeben werden:

            <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>host</emphasis></entry>
                    <entry>
                        Der Hostname des LDAP Servers der diese Optionen repräsentiert. Diese
                        Option wird benötigt.
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>port</emphasis></entry>
                    <entry>
                        Der Port auf den der LDAP Server schaut. Wenn
                        <emphasis>useSsl</emphasis> <code>true</code> ist, ist der
                        Standardwert von <emphasis>port</emphasis> 636. Wenn
                        <emphasis>useSsl</emphasis> <code>false</code> ist, ist der
                        Standardwert von <emphasis>port</emphasis> 389.
                    </entry>
                  </row>
                  <row>
                    <entry>useStartTls</entry>
                    <entry>
                        Ob der LDAP Client einen TSL (aka SSLv2) verschlüsselten Transport verwenden
                        soll oder nicht. Der Wert <code>true</code> wird in einer
                        Produktionsumgebung strengstens empfohlen um zu verhindern das Passwörter im
                        Klartext übertragen werden. Der Standardwert ist <code>false</code>, da
                        Server typischerweise nach deren Installation erwarten das ein Zertifikat
                        installiert wird. Die <code>useSsl</code> und <code>useStartTls</code>
                        Optionen schließen sich gegenseitig aus. Die <code>useStartTls</code> Option
                        sollte über <code>useSsl</code> favorisiert werden, aber nicht alle Server
                        unterstützen diesen neueren Mechanismus.
                    </entry>
                  </row>
                  <row>
                    <entry>useSsl</entry>
                    <entry>
                        Ob der LDAP Client einen SSL verschlüsselten Transport verwenden soll. Die
                        <code>useSsl</code> und <code>useStartTls</code> Optionen schließen sich
                        gegenseitig aus, aber <code>useStartTls</code> sollte favorisiert werden
                        wenn der Server und die LDAP Bibliothek des Clients diese unterstützen.
                        Dieser Wert ändert auch den Standardwert von <emphasis>port</emphasis>
                        (siehe die <emphasis>port</emphasis> Beschreibung weiter oben).
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>username</emphasis></entry>
                    <entry>
                        Der DN des Accounts der verwendet wird um DN Account Loopups durchzuführen.
                        LDAP Server die den Benutzernamen in in DN Form benötigenwenn "bind"
                        durchgeführt wird, benötigen diese Option. Wenn
                        <emphasis>bindRequiresDn</emphasis> <code>true</code> ist,
                        wird diese Option benötigt. Dieser Account muß kein privilegierter Account
                        sein - ein Account mit nur-lese Zugriff zu Objekten unter
                        <emphasis>baseDn</emphasis> ist alles was notwendig ist
                        (und bevorzugt unter dem <emphasis>Prinzip des geringsten
                        Privilegs</emphasis>).
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>password</emphasis></entry>
                    <entry>
                        Das Passwort des Accounts der verwendet wird um DN Lookups durchzuführen.
                        Wenn diese Option nicht unterstützt wird, versucht der LDAP Client einen
                        "anonymen bind" wenn DN Lookups durchgeführt werden.
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>bindRequiresDn</emphasis></entry>
                    <entry>
                        Einige LDAP 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 <code>true</code> 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 <code>false</code>. Aktuell ist nur von Microsoft Active
                        Directory Server (ADS) 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 <code>false</code> sein (und sollte
                        das auch, da das Empfangen des DN eine extra Anfrage zum Server benötigt).
                        Andernfalls muß diese Option auf <code>true</code> gesetzt werden (z.B. für
                        OpenLDAP). Diese Option kontrolliert das Standard
                        <emphasis>acountFilterFormat</emphasis> das verwendet wird
                        wenn nach Accounts gesucht wird. Siehe auch die
                        <emphasis>accountFilterFormat</emphasis> Option.
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>baseDn</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
                        <emphasis>baseDn</emphasis> ist, sollte es genug sein Ihn von
                        der DNS Domain des Benutzers der die <emphasis>DC=</emphasis> Komponenten
                        verwedet abzuleiten. Wenn der Hauptname eines Benutzers
                        <emphasis>alice@foo.net</emphasis> ist, sollte ein
                        <emphasis>baseDn</emphasis> 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>accountCanonicalForm</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.,
                        <emphasis>FOO\alice</emphasis>) oder 4 für Authentifiziert-Sil Namen (z.B.,
                        <emphasis>alice@foo.net</emphasis>). Der Standardwert ist 4 (z.B.,
                        <emphasis>alice@foo.net</emphasis>). Mit einem Wert von 3, z.B., wird die
                        Identität die von <classname>Zend_Auth_Result::getIdentity()</classname>
                        zurückgegeben wird (und <classname>Zend_Auth::getIdentity()</classname>,
                        wenn <classname>Zend_Auth</classname> verwendet wird), immer
                        <emphasis>FOO\alice</emphasis> sein, unabhängig von der Form in der Alice
                        angegeben wurde, egal ob es <emphasis>alice</emphasis>,
                        <emphasis>alice@foo.net</emphasis>, <emphasis>FOO\alice</emphasis>,
                        <emphasis>FoO\aLicE</emphasis>, <emphasis>foo.net\alice</emphasis>, 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
                        <emphasis>accountCanonicalForm</emphasis> in allen
                        Serveroptionen verwendet wird, sodas die sich ergebenden Benutzernamen
                        immer auf die selbe Art und Weise kanonisiert werden (z.b. wenn man auf
                        <emphasis>EXAMPLE\username</emphasis> mit einem AD Server kanonisiert, aber
                        zu <emphasis>username@example.com</emphasis> mit einem OpenLDAP Server,
                        kann das quirks für die High-Level Logik einer Anwendung sein).
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>accountDomainName</emphasis></entry>
                    <entry>
                        Der FDQN Domainname für welchen der Ziel LDAP Server eine Authorität ist
                        (z.B., <code>example.com</code>). 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. Ere wird auch
                        verwendet um festzustellen ob der Server eine Authorität für den
                        angegebenen Benutzernamen ist (z.B., wenn
                        <emphasis>accountDomainName</emphasis>
                        <emphasis>foo.net</emphasis> ist und der angegebene Benutzer
                        <emphasis>bob@bar.net</emphasis>, 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., <emphasis>alice@foo.net</emphasis>) nicht unterstützt. Es
                        wird stark empfohlen das diese Option angegeben wird, da es viele
                        Anwendungsfälle gibt die die Erstellung von prinzipieller Namensform
                        benötigen.
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>accountDomainNameShort</emphasis></entry>
                    <entry>
                        Die 'short' Domain für die der Ziel LDAP Server eine Authorität ist (z.B.,
                        <emphasis>FOO</emphasis>). Es ist z ubeachten das es ein 1:1 Mapping
                        zwischen <emphasis>accountDomainName</emphasis> und
                        <emphasis>accountDomainNameShort</emphasis> 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 <emphasis>accountCanonicalForm</emphasis>).
                        Diese Option wird nicht benötigt, aber wenn Sie nicht angegeben wird,
                        werden Benutzernamen im Schrägstrich Stil (z.B.
                        <emphasis>FOO\alice</emphasis>) nicht unterstützt.
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>accountFilterFormat</emphasis></entry>
                    <entry>
                        Der LDAP Suchfilter der für die Suche nach Accounts verwendet wird. Dieser
                        String ist ein
                        <ulink url="http://php.net/printf"><code>printf()</code></ulink>-Stil
                        Ausdruck der ein '<code>%s</code>' enthalten muß um den Benutzernamen
                        unterzubringen. Der Standardwert ist
                        '<code>(&amp;(objectClass=user)(sAMAccountName=%s))</code>', ausgenommen
                        <emphasis>bindRequiresDn</emphasis> wird auf
                        <code>true</code> gesetzt. In diesem Fall ist der Standardwert
                        '<code>(&amp;(objectClass=posixAccount)(uid=%s))</code>'. Wenn, zum
                        Beispiel, aus irgendeinem Grund <code>bindRequiresDn = true</code> mti AD
                        verwendet werden soll, muß <code>accountFilterFormat =
                        '(&amp;(objectClass=user)(sAMAccountName=%s))</code>' gesetzt werden.
                    </entry>
                  </row>
                  <row>
                    <entry><emphasis>optReferrals</emphasis></entry>
                    <entry>
                        Wenn sie auf <code>true</code> gesetzt wird, zeigt diese Option dem LDAP
                        Client an, das Referenzen gefolgt werden soll. Der Standardwert ist
                        <code>false</code>.
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
        </para>

        <note>
            <para>
                Wenn <code>useStartTls = true</code> oder <code>useSsl = true</code> 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 "<code>TLS_REQCERT niemals</code>" im OpenLDAP
                Client <code>ldap.conf</code> 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.
            </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
            <code>authenticate()</code> Methode. Diese Information wird im
            <classname>Zend_Auth_Result</classname> Objekt als Nachrichten gespeichert. Das von
            <classname>Zend_Auth_Result::getMessages()</classname> zurückgegebene Array kann wie
            folgt beschrieben werden:

            <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>

            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 ADS sind die folgenden Optionen beachtenswert:

                <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>host</emphasis></entry>
                        <entry>
                            Wie bei allen Servern, wird diese Option benötigt.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>useStartTls</emphasis></entry>
                        <entry>
                            Zum Zwecke der Sicherheit, sollte das <code>true</code> sein wenn der
                            Server das notwendige Zertifikat installiert hat.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>useSsl</emphasis></entry>
                        <entry>
                            Möglicherweise als Alternative zu <code>useStartTls</code> zu verwenden
                            (siehe davor).
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>baseDn</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>accountCanonicalForm</emphasis></entry>
                        <entry>
                            Das wird man normalerweise für Schrägstrich-Stil Namen auf 3 stellen
                            (z.B., <emphasis>FOO\alice</emphasis>), 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., <emphasis>BAR\alice</emphasis> und
                            <emphasis>FOO\alice</emphasis> würden als der gleiche Benutzer
                            behandelt). (siehe auch die Notiz anbei.)
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>accountDomainName</emphasis></entry>
                        <entry>
                            Das wird mit AD benötigt, ausser
                            <emphasis>accountCanonicalForm</emphasis> 2 wird
                            verwendet, was wiederum nicht eingesetzt werden sollte.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>accountDomainNameShort</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
                            <emphasis>accountCanonicalForm</emphasis> verwendet wird.
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
            </para>

            <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, die die Domain wärend 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 LDAP Server der ein typisches posixAccount
                Stil Schema verwendet sind die folgenden Optionen beachtenswert:

                <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>host</emphasis></entry>
                        <entry>
                            Wie bei allen Servern, wird diese Option benötigt.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>useStartTls</emphasis></entry>
                        <entry>
                            Zum Zwecke der Sicherheit, sollte das <code>true</code> sein wenn der
                            Server das notwendige Zertifikat installiert hat.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>useSsl</emphasis></entry>
                        <entry>
                            Möglicherweise als Alternative zu <code>useStartTls</code> zu verwenden
                            (siehe davor).
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>username</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 privelegierten Account zu verwenden.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>password</emphasis></entry>
                        <entry>
                            Das Passwort das zum Benutzernamen von oben gehört. Es kann aber
                            unterdrückt werden wenn der LDAP Server anonymes Binden bei Abfragen zu
                            Benutzer Accounts erlaubt.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>bindRequiresDn</emphasis></entry>
                        <entry>
                            Benötigt und muß <code>true</code> sein, da OpenLDAP den Benutzernamen
                            in DN Form benötigt wenn ein Binden durchgeführt wird.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>baseDn</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>accountCanonicalForm</emphasis></entry>
                        <entry>
                            Optional, aber der Standardwert ist 4 (prinzipielle-Stil Namen wie
                            <emphasis>alice@foo.net</emphasis>) und könnte für die Benutzer nicht
                            ideal sein wenn diese Schrägstrich-Stil Namen verwendetn (z.B.,
                            <emphasis>FOO\alice</emphasis>). Für Schrägstrich-Stil Namen sollte der
                            Wert 3 verwendet werden.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>accountDomainName</emphasis></entry>
                        <entry>
                            Benötigt es sei denn man verwendet
                            <emphasis>accountCanonicalForm</emphasis> 2, was nicht
                            zu empfehlen ist.
                        </entry>
                      </row>
                      <row>
                        <entry><emphasis>accountDomainNameShort</emphasis></entry>
                        <entry>
                            Wenn AD auch nicht verwendet wird, wird dieser Wert nicht benötigt.
                            Andernfalls, wenn
                            <emphasis>accountCanonicalForm</emphasis> 3 verwendet
                            wird, wird diese Option benötigt und sollte ein Kurzname sein der
                            adäquat zu <emphasis>accountDomainName</emphasis>
                            korrespondiert (z.B., wenn
                            <emphasis>accountDomainName</emphasis>
                            <emphasis>foo.net</emphasis> ist, wäre ein guter
                            <emphasis>accountDomainNameShort</emphasis> Wert
                            <emphasis>FOO</emphasis>).
                        </entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>

            </para>

        </sect3>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->