repo_zf1/documentation/manual/de/module_specs/Zend_Ldap-Introduction.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 16828 -->
<!-- Reviewed: no -->
<sect1 id="zend.ldap.introduction">
    <title>Einführung</title>

    <para>
        <classname>Zend_Ldap</classname> ist eine Klasse, mit der <acronym>LDAP</acronym>
        Operationen, wie das Durchsuchen, das Bearbeiten oder die Bindung an Einträge im
        <acronym>LDAP</acronym> Verzeichnis, durchgeführt werden können.
    </para>

    <sect2 id="zend.ldap.introduction.theory-of-operations">
        <title>Theorie der Verwendung</title>

        <para>
            Diese Komponente besteht aus der Hauptklasse <classname>Zend_Ldap</classname> welche
            konzeptionell eine Bindung an einen einzelnen <acronym>LDAP</acronym> Server
            repräsentiert und die Ausführung von Operationen an diesem <acronym>LDAP</acronym>
            Server erlaubt, wie zum Beispiel OpenLDAP oder ActiveDirectory (AD) Server. Die
            Parameter für das Binden können explizit oder in der Form eines Options Arrays
            angegeben werden. <classname>Zend_Ldap_Node</classname> bietet ein Objektorientiertes
            Interface für einen einzelnen <acronym>LDAP</acronym> Node und kann verwendet werden
            um eine Basis für ein Active-Record artiges Interface für ein <acronym>LDAP</acronym>
            basiertes Domain-Modell zu bieten.
        </para>

        <para>
            Die Komponente bietet verschiedene Helfer Klassen um Operationen auf
            <acronym>LDAP</acronym> Einträgen (<classname>Zend_Ldap_Attribute</classname>)
            durchzuführen, wie das Setzen und Empfangen von Attributen (Datumswerte, Passwörter,
            Boolsche Werte, ...), um <acronym>LDAP</acronym> Filter Strings
            (<classname>Zend_Ldap_Filter</classname>) zu Erstellen und zu Ändern, und um
            <acronym>LDAP</acronym> Distinguished Names (DN) (<classname>Zend_Ldap_Dn</classname>)
            zu manipulieren.
        </para>

        <para>
            Zusätzlich abstrahiert die Komponente das Suchen im <acronym>LDAP</acronym> Schema
            für OpenLDAP und ActiveDirectory Server <classname>Zend_Ldap_Node_Schema</classname>
            und das empfangen von Server Informationen für OpenLDAP-, ActiveDirectory- und Novell
            eDirectory Server (<classname>Zend_Ldap_Node_RootDse</classname>).
        </para>

        <para>
            Die Verwendung der <classname>Zend_Ldap</classname> Klasse hängt vom Typ des
            <acronym>LDAP</acronym> Servers ab und wird am besten mit einigen einfachen Beispielen
            gezeigt.
        </para>

        <para>
            Wenn man OpenLDAP Verwendet sieht ein einfaches Beispiel wie folgt aus
            (es ist zu beachten das die <emphasis>bindRequiresDn</emphasis> Option wichtig ist wenn
            man <emphasis>nicht</emphasis> AD verwendet):
        </para>

        <programlisting language="php"><![CDATA[
$options = array(
    'host'              => 's0.foo.net',
    'username'          => 'CN=user1,DC=foo,DC=net',
    'password'          => 'pass1',
    'bindRequiresDn'    => true,
    'accountDomainName' => 'foo.net',
    'baseDn'            => 'OU=Sales,DC=foo,DC=net',
);
$ldap = new Zend_Ldap($options);
$acctname = $ldap->getCanonicalAccountName('abaker',
                                           Zend_Ldap::ACCTNAME_FORM_DN);
echo "$acctname\n";
]]></programlisting>

        <para>
            Wenn man Microsoft AD verwendet ist ein einfaches Beispiel:
        </para>

        <programlisting language="php"><![CDATA[
$options = array(
    'host'                   => 'dc1.w.net',
    'useStartTls'            => true,
    'username'               => 'user1@w.net',
    'password'               => 'pass1',
    'accountDomainName'      => 'w.net',
    'accountDomainNameShort' => 'W',
    'baseDn'                 => 'CN=Users,DC=w,DC=net',
);
$ldap = new Zend_Ldap($options);
$acctname = $ldap->getCanonicalAccountName('bcarter',
                                           Zend_Ldap::ACCTNAME_FORM_DN);
echo "$acctname\n";
]]></programlisting>

        <para>
            Es ist zu beachten das die <methodname>getCanonicalAccountName()</methodname> Methode
            verwendet wird um den DN Account zu empfangen da jenes das einige ist was das meiste
            in diesem kleinen Code zeigt der aktuell in dieser Klasse vorhanden ist.
        </para>

        <sect3 id="zend.ldap.introduction.theory-of-operations.automatic-username-canonicalization">
            <title>Automatische Kanonisierung des Benutzernamens beim Binden</title>

            <para>
                Wenn <code>bind()</code> mit einem nicht-DN Benutzernamen aufgerufen wird
                aber <code>bindRequiresDN</code> <constant>TRUE</constant> ist und kein
                Benutzername in DN-Form als Option angegeben wurde, dann wird die Server-Bindung
                fehlschlagen. Wenn allerdings ein Benutzername in DN-Form im Optionen-Array
                übergeben wurde, wird <classname>Zend_Ldap</classname> sich zuerst mit diesem
                Benutzernamen an den Server binden, den Account DN für den Benutzernamen empfangen
                der bei <code>bind()</code> angegeben wurde und dann mit diesem zum DN verbinden.
            </para>

            <para>
                Dieses Verhalten ist kritisch für <link
                    linkend="zend.auth.adapter.ldap"><classname>Zend_Auth_Adapter_Ldap</classname></link>,
                welches den vom Benutzer angegebenen Benutzernamen direkt an
                <methodname>bind()</methodname> übergibt.
            </para>

            <para>
                Das folgende Beispiel zeigt wie der nicht-DN Benutzername
                '<emphasis>abaker</emphasis>' mit <methodname>bind()</methodname> verwendet werden
                kann:
            </para>

            <programlisting language="php"><![CDATA[
$options = array(
        'host'              => 's0.foo.net',
        'username'          => 'CN=user1,DC=foo,DC=net',
        'password'          => 'pass1',
        'bindRequiresDn'    => true,
        'accountDomainName' => 'foo.net',
        'baseDn'            => 'OU=Sales,DC=foo,DC=net',
);
$ldap = new Zend_Ldap($options);
$ldap->bind('abaker', 'moonbike55');
$acctname = $ldap->getCanonicalAccountName('abaker',
                                           Zend_Ldap::ACCTNAME_FORM_DN);
echo "$acctname\n";
]]></programlisting>

            <para>
                Der Aufruf von <methodname>bind()</methodname> in diesem Beispiel sieht das der
                Benutzer '<emphasis>abaker</emphasis>' nicht in DN Form ist, findet das
                <emphasis>bindRequiresDn</emphasis> <constant>TRUE</constant> ist, verwendet
                '<command>CN=user1,DC=foo,DC=net</command>' und '<emphasis>pass1</emphasis>' um zu
                Binden, empfängt den DN für '<emphasis>abaker</emphasis>', entbindet und Bindet
                dann nochmals mit dem neu erkannten
                '<command>CN=Alice Baker,OU=Sales,DC=foo,DC=net</command>'.
            </para>
        </sect3>

        <sect3 id="zend.ldap.introduction.theory-of-operations.account-name-canonicalization">
            <title>Kanonisierung des Account Namens</title>

            <para>
                Die Optionen <emphasis>accountDomainName</emphasis> und
                <emphasis>accountDomainNameShort</emphasis> werden für zwei Zwecke verwendet:
                (1) bieten Sie multi-Domain Authentifizierung und Failover Möglichkeiten, und
                (2) werden Sie auch verwendet um Benutzernamen zu kanonisieren. Speziell Namen
                werden in die Form kanonisiert die in der <emphasis>accountCanonicalForm</emphasis>
                Option spezifiziert ist. Diese Option kann einen der folgenden Werte enthalten:
            </para>

            <table id="zend.ldap.using.theory-of-operation.account-name-canonicalization.table">
                <title>Optionen für accountCanonicalForm</title>
                <tgroup cols="3">
                    <thead>
                        <row>
                            <entry>Name</entry>
                            <entry>Wert</entry>
                            <entry>Beispiel</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>
                                <constant>ACCTNAME_FORM_DN</constant>
                            </entry>
                            <entry>1</entry>
                            <entry>CN=Alice Baker,CN=Users,DC=example,DC=com</entry>
                        </row>
                        <row>
                            <entry>
                                <constant>ACCTNAME_FORM_USERNAME</constant>
                            </entry>
                            <entry>2</entry>
                            <entry>abaker</entry>
                        </row>
                        <row>
                            <entry>
                                <constant>ACCTNAME_FORM_BACKSLASH</constant>
                            </entry>
                            <entry>3</entry>
                            <entry>EXAMPLE\abaker</entry>
                        </row>
                        <row>
                            <entry>
                                <constant>ACCTNAME_FORM_PRINCIPAL</constant>
                            </entry>
                            <entry>4</entry>
                            <entry><filename>abaker@example.com</filename></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <para>
                Die Standardmäßige Kanonisierung hängt davon ab welche Optionen für Account Domain
                Namen angegeben wurden. Wenn <emphasis>accountDomainNameShort</emphasis> angegeben
                wurde, ist der Standardwert von <emphasis>accountCanonicalForm</emphasis>
                <constant>ACCTNAME_FORM_BACKSLASH</constant>. Andernfall, wenn
                <emphasis>accountDomainName</emphasis> angegeben wurde, ist der Standardwert
                <constant>ACCTNAME_FORM_PRINCIPAL</constant>.
            </para>

            <para>
                Die Kanonisierung des Account Namens stellt sicher das der String der zur
                Identifikation des Accounts verwendet wird konsistent ist, unabhängig davon was an
                <methodname>bind()</methodname> übergeben wurde. Wenn der Benutzer, zum Beispiel,
                den Account Namen <filename>abaker@example.com</filename> oder nur
                <emphasis>abaker</emphasis> angibt, und <emphasis>accountCanonicalForm</emphasis>
                auf 3 gesetzt ist, wird der resultierende kanonisierte Name
                <emphasis>EXAMPLE\abaker</emphasis> sein.
            </para>
        </sect3>

        <sect3 id="zend.ldap.introduction.theory-of-operations.multi-domain-failover">
            <title>Multi-domain Authentication and Failover</title>

            <para>
                The <classname>Zend_Ldap</classname> component by itself makes no attempt
                to authenticate with multiple servers. However, <classname>Zend_Ldap</classname>
                is specifically designed to handle this scenario gracefully. The
                required technique is to simply iterate over an array of arrays of serve
                 options and attempt to bind with each server. As described above
                 <methodname>bind()</methodname> will automatically canonicalize each name, so
                it does not matter if the user passes <filename>abaker@foo.net</filename> or
                <emphasis>W\bcarter</emphasis> or <emphasis>cdavis</emphasis> - the
                <methodname>bind()</methodname> method will only succeed if the credentials were
                successfully used in the bind.
            </para>

            <para>
                Consider the following example that illustrates the technique required to
                implement multi-domain authentication and failover:
            </para>

            <programlisting language="php"><![CDATA[
$acctname = 'W\\user2';
$password = 'pass2';

$multiOptions = array(
    'server1' => array(
        'host'                   => 's0.foo.net',
        'username'               => 'CN=user1,DC=foo,DC=net',
        'password'               => 'pass1',
        'bindRequiresDn'         => true,
        'accountDomainName'      => 'foo.net',
        'accountDomainNameShort' => 'FOO',
        'accountCanonicalForm'   => 4, // ACCT_FORM_PRINCIPAL
        'baseDn'                 => 'OU=Sales,DC=foo,DC=net',
    ),
    'server2' => array(
        'host'                   => 'dc1.w.net',
        'useSsl'                 => true,
        'username'               => 'user1@w.net',
        'password'               => 'pass1',
        'accountDomainName'      => 'w.net',
        'accountDomainNameShort' => 'W',
        'accountCanonicalForm'   => 4, // ACCT_FORM_PRINCIPAL
        'baseDn'                 => 'CN=Users,DC=w,DC=net',
    ),
);

$ldap = new Zend_Ldap();

foreach ($multiOptions as $name => $options) {

    echo "Trying to bind using server options for '$name'\n";

    $ldap->setOptions($options);
    try {
        $ldap->bind($acctname, $password);
        $acctname = $ldap->getCanonicalAccountName($acctname);
        echo "SUCCESS: authenticated $acctname\n";
        return;
    } catch (Zend_Ldap_Exception $zle) {
        echo '  ' . $zle->getMessage() . "\n";
        if ($zle->getCode() === Zend_Ldap_Exception::LDAP_X_DOMAIN_MISMATCH) {
            continue;
        }
    }
}
]]></programlisting>

            <para>
                If the bind fails for any reason, the next set of server options is tried.
            </para>

            <para>
                The <methodname>getCanonicalAccountName()</methodname> call gets the canonical
                account name that the application would presumably use to associate data with such
                as preferences. The <emphasis>accountCanonicalForm = 4</emphasis> in all server
                options ensures that the canonical form is consistent regardless of which
                server was ultimately used.
            </para>

            <para>
                The special <constant>LDAP_X_DOMAIN_MISMATCH</constant> exception occurs when an
                account name with a domain component was supplied (e.g.,
                <filename>abaker@foo.net</filename> or <emphasis>FOO\abaker</emphasis> and not just
                <emphasis>abaker</emphasis>) but the domain component did not match either domain
                in the currently selected server options. This exception indicates
                that the server is not an authority for the account. In this
                case, the bind will not be performed, thereby eliminating unnecessary
                communication with the server. Note that the <emphasis>continue</emphasis>
                instruction has no effect in this example, but in practice for error handling and
                debugging purposes, you will probably want to check for
                <constant>LDAP_X_DOMAIN_MISMATCH</constant> as well as
                <constant>LDAP_NO_SUCH_OBJECT</constant> and
                <constant>LDAP_INVALID_CREDENTIALS</constant>.
            </para>

            <para>
                The above code is very similar to code used within <link
                    linkend="zend.auth.adapter.ldap"><classname>Zend_Auth_Adapter_Ldap</classname></link>.
                In fact, we recommend that you simply use that authentication adapter for
                multi-domain + failover <acronym>LDAP</acronym> based authentication
                (or copy the code).
            </para>
        </sect3>
    </sect2>
</sect1>