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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15346 -->
<!-- Reviewed: no -->
<sect1 id="zend.auth.adapter.http">

    <title>HTTP Authentication Adapter</title>

    <sect2 id="zend.auth.adapter.http.introduction">

        <title>Einführung</title>

        <para>
            <classname>Zend_Auth_Adapter_Http</classname> bietet die am meisten entsprechende
            Implementation von <ulink url="http://tools.ietf.org/html/rfc2617">RFC-2617</ulink>,
            <ulink url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">Basis</ulink> und
            <ulink url="http://en.wikipedia.org/wiki/Digest_access_authentication">Digest</ulink>
            HTTP Authentifizierung. Digest Authentifizierung ist eine Methode der HTTP
            Authentifikation die die Basis Authentifizierung erweitert indem ein Weg angeboten wird
            um sich zu Authentifizieren ohne das das Passwort im Klartext über das Netzwerk
            geschickt werden muß.
        </para>

        <para>
            <emphasis>Hauptsächliche Features:</emphasis>
            <itemizedlist>
                <listitem>
                    <para>
                        Unterstützt sowohl Basis als auch Digest Authentifizierung.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Enthält Aufrufe für alle unterstützten Schemas, damit Klienten mit jedem
                        unterstützten Schema arbeiten können.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Bietet Proxi Authentifizierung.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Enthält Unterstützung für die Authentifizierung gegenüber Textdateien und
                        bietet ein Interface für die Authentifizierung gegenüber anderen Quellen,
                        wie z.B. Datenbanken.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Es gibt ein paar nennenswerte Features von RFC-2617 die bis jetzt nicht implementiert
            wurden:
            <itemizedlist>
                <listitem>
                    <para>
                        Einstweilige Verfolgung, welche "stale" Support erlaubt und die
                        Unterstützung bei wiederholenden Attacken erhöht.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Authentifizierung mit Integritäts-Prüfung, oder "auth-int".
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Authentifizierungs-Info HTTP Header.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

    </sect2>

    <sect2 id="zend.auth.adapter.design_overview">

        <title>Design Übersicht</title>

        <para>
            Dieser Adapter besteht aus zwei Sub-Komponenten, die HTTP Authentifizierungs Klasse
            selbst, und den sogenannten "Auflöser". Die HTTP Authentifizierungs Klasse kapselt die
            Logik für die Ausführung beider, sowohl der Basis als auch der Digest Authentifizierung.
            Sie verwendet einen Auflöser um die Identität eines Klienten in Datenspeichern
            nachzusehen (standardmäßig eine Textdatei), und die Zeugnisse vom Datenspeicher zu
            empfangen. Die "aufgelösten" Zeugnisse werden dann mit den Werten verglichen die vom
            Klienten übermittelt wurden um zu eruieren ob die Authentifizierung erfolgreich war.
        </para>

    </sect2>

    <sect2 id="zend.auth.adapter.configuration_options">

        <title>Konfigurations Optionen</title>

        <para>
            Die <classname>Zend_Auth_Adapter_Http</classname> Klasse benötigt ein Konfigurations
            Array das Ihrem Konstruktor übergeben werden muß. Es sind verschiedene Konfigurations
            Optionen vorhanden, und einige davon werden benötigt:
            <table id="zend.auth.adapter.configuration_options.table">
                <title>Konfigurations Optionen</title>
                <tgroup cols="3">
                    <thead>
                        <row>
                            <entry>Options Name</entry>
                            <entry>Benötigt</entry>
                            <entry>Beschreibung</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><code>accept_schemes</code></entry>
                            <entry>Ja</entry>
                            <entry>
                                Ermittelt welches Authentifizierungs Schema der Adapter vom Klienten
                                akzeptiert. Muß eine Leerzeichen-getrennte Liste sein, die
                                <code>'basic'</code> und/oder <code>'digest'</code> enthält.
                            </entry>
                        </row>
                        <row>
                            <entry><code>realm</code></entry>
                            <entry>Ja</entry>
                            <entry>
                                Setzt das Authentifizierungs-Bereich; Benutzernamen sollten im
                                angegebenen Bereich einmalig sein.
                            </entry>
                        </row>
                        <row>
                            <entry><code>digest_domains</code></entry>
                            <entry>
                                Ja, wenn <code>'accept_schemes'</code> <code>'digest'</code> enthält
                            </entry>
                            <entry>
                                Leerzeichen-getrennte Liste von URIs für die die gleichen
                                Authentifizierungs Informationen gültig sind. Die URIs müssen nicht
                                alle auf den gleichen Server zeigen.
                            </entry>
                        </row>
                        <row>
                            <entry><code>nonce_timeout</code></entry>
                            <entry>
                                Ja, wenn <code>'accept_schemes'</code> <code>'digest'</code> enthält
                            </entry>
                            <entry>
                                Setzt die Anzahl an Sekunden für die die Verfolgung gültig ist.
                                Siehe die Notizen anbei.
                            </entry>
                        </row>
                        <row>
                            <entry><code>proxy_auth</code></entry>
                            <entry>Nein</entry>
                            <entry>
                                Standardmäßig ausgeschaltet. Einschalten um Proxi Authentifizierung
                                durchzuführen statt normaler originaler Server Authentifizierung.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>

        <note>
            <para>
                Die aktuelle Implementation von <code>nonce_timeout</code> hat einige interessante
                Nebeneffekte. Diese Einstellung soll die gültige Lebenszeit einer gegebenen
                Verfolgung ermitteln, oder effektiv, wie lange die Authentifizierungs Information
                eines Klienten akzeptiert wird. Aktuell ist es auf 3600 (zum Beispiel) gesetzt, und
                führt dazu das der Klient jede Stunde um neue Zeugnisse gebeten wird. Das wird in
                einem zukünftigen Release behoben werden, sobald Verfolgung und "stale" Support
                implementiert werden.
            </para>
        </note>

    </sect2>

    <sect2 id="zend.auth.adapter.http.resolvers">

        <title>Auflöser</title>

        <para>
            Der Job des Auflösers ist es einen Benutzernamen und einen Bereich, und gibt eine Art
            von Zeugnisswert zurück. Basis Authentifizierung erwartet einen Hash des Benutzernamens,
            des Bereichs, und dessen Passwörter (jedes seperiert durch ein Komma). Aktuell ist der
            einzige unterstützte Hash Algorithmus MD5.
        </para>

        <para>
            <classname>Zend_Auth_Adapter_Http</classname> ist darauf angewiesen das Objekte
            <classname>Zend_Auth_Adapter_Http_Resolver_Interface</classname> implementieren. Eine
            Textdatei Auflöser Klasse ist mit diesem Adapter inkludiert, aber jede Art von Auflöser
            kann einfach erstellt werden indem das Resolver Interface implementiert wird.
        </para>

        <sect3 id="zend.auth.adapter.http.resolvers.file">

            <title>Datei Auflöser</title>

            <para>
                Der Datei Auflöser ist eine sehr einfache Klasse. Sie hat eine einzelne Eigenschaft
                die einen Dateinamen spezifiziert, welcher auch dem Konstruktor übergeben werden
                kann. Ihre <code>resolve()</code> Methode geht durch die Textdatei, und sucht nach
                einer Zeile mit einem entsprechenden Benutzernamen und Bereich. Das Format der
                Textdatei ist ähnlich dem von Apache htpasswd Dateien:
                <programlisting><![CDATA[
<benutzername>:<bereich>:<zeugnisse>\n
]]></programlisting>
                Jede Zeile besteht aus drei Feldern - Benutzername, Bereich und Zeugnisse - jede
                abgeteilt durch einen Doppelpunkt. Das Zeugnis Feld ist für den Datei Auflöser nicht
                sichtbar; es gibt den Wert einfach, wie er ist, an den Aufrufer zurück. Deswegen
                kann dieses Dateiformat sowohl Basis als auch Digest Authentifizierung behandeln. In
                der Basis Authentifizierung sollte das Zeugnis Feld im Klartext stehen. In der
                Digest Authentifizierung sollte es der oben beschriebene MD5 Hash sein.
            </para>

            <para>
                Es gibt zwei gleiche einfache Wege um einen Datei Auflöser zu erstellen:
                <programlisting role="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
]]></programlisting>
                oder
                <programlisting role="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File();
$resolver->setFile($path);
]]></programlisting>
                Wenn der angegebene Pfad leer oder nicht lesbar ist, wird eine Ausnahme geworfen.
            </para>

        </sect3>

    </sect2>

    <sect2 id="zend.auth.adapter.http.basic_usage">

        <title>Grundsätzliche Verwendung</title>

        <para>
            Zuerst muß ein Array mit den benötigen Konfigurationswerten gesetzt werden:
            <programlisting role="php"><![CDATA[
$config = array(
    'accept_schemes' => 'basic digest',
    'realm'          => 'My Web Site',
    'digest_domains' => '/members_only /my_account',
    'nonce_timeout'  => 3600,
);
]]></programlisting>
            Dieses Array bringt den Adapter dazu entwedet Basis oder Digest Authentifizierung zu
            akzeptieren, und benötigt einen authentifizierten Zugriff auf alle Areale der Site unter
            <code>/members_only</code> und <code>/my_account</code>. Der Bereichs Wert wird
            normalerweise durch den Browser in der Passwort Dialog Box angezeigt.
            <code>nonce_timeout</code> verhält sich natürlich so wie oben beschrieben.
        </para>

        <para>
            Dann wird ein Zend_Auth_Adapter_Http Objekt erstellt:
            <programlisting role="php"><![CDATA[
$adapter = new Zend_Auth_Adapter_Http($config);
]]></programlisting>
        </para>

        <para>
            Da beides, Basis und Digest Authentifizierung, unterstützt werden, werden zwei
            unterschiedliche Auflösungs-Objekte benötigt. Man könnte das auch einfach durch die
            Verwendung von zwei unterschiedlichen Klassen bewerkstelligen:
            <programlisting role="php"><![CDATA[
$basicResolver = new Zend_Auth_Adapter_Http_Resolver_File();
$basicResolver->setFile('files/basicPasswd.txt');

$digestResolver = new Zend_Auth_Adapter_Http_Resolver_File();
$digestResolver->setFile('files/digestPasswd.txt');

$adapter->setBasicResolver($basicResolver);
$adapter->setDigestResolver($digestResolver);
]]></programlisting>
        </para>

        <para>
            Letztendlich führen wir die Authentifizierung durch. Der Adapter benötigt eine Referenz
            zu beidem, dem Anfrage und Antwort Objekten um seinen Job durchführen zu können:
            <programlisting role="php"><![CDATA[
assert($request instanceof Zend_Controller_Request_Http);
assert($response instanceof Zend_Controller_Response_Http);

$adapter->setRequest($request);
$adapter->setResponse($response);

$result = $adapter->authenticate();
if (!$result->isValid()) {
    // Schlechter Benutzername/Passwort, oder abgebrochener Passwort Prompt
}
]]></programlisting>
        </para>

    </sect2>

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