<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- 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>
            <acronym>HTTP</acronym> Authentifizierung. Digest Authentifizierung ist eine Methode der
            <acronym>HTTP</acronym> Authentifikation welche die Basis Authentifizierung erweitert
            indem ein Weg angeboten wird um sich zu Authentifizieren ohne dass das Passwort im
            Klartext über das Netzwerk geschickt werden muß.
        </para>

        <para>
            <emphasis>Hauptsächliche Features:</emphasis>
        </para>

        <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 Proxy 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>
            Es gibt ein paar nennenswerte Features von <acronym>RFC-2617</acronym> die bis jetzt
            nicht implementiert wurden:
        </para>

        <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 <acronym>HTTP</acronym> Header.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.auth.adapter.design_overview">
        <title>Design Übersicht</title>

        <para>
            Dieser Adapter besteht aus zwei Sub-Komponenten, die <acronym>HTTP</acronym>
            Authentifizierungs Klasse selbst, und den sogenannten "Auflöser". Die
            <acronym>HTTP</acronym> 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:
        </para>

        <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><emphasis><property>accept_schemes</property></emphasis></entry>
                        <entry>Ja</entry>

                        <entry>
                            Ermittelt welches Authentifizierungs Schema der Adapter vom
                            Klienten akzeptiert. Muß eine Leerzeichen-getrennte Liste sein, die
                            <emphasis>'basic'</emphasis> und, oder <emphasis>'digest'</emphasis>
                            enthält.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>realm</property></emphasis></entry>
                        <entry>Ja</entry>

                        <entry>
                            Setzt das Authentifizierungs-Bereich; Benutzernamen sollten im
                            angegebenen Bereich einmalig sein.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>digest_domains</property></emphasis></entry>

                        <entry>
                            Ja, wenn <property>accept_schemes</property>
                            <emphasis>digest</emphasis> enthält
                        </entry>

                        <entry>
                            Leerzeichen-getrennte Liste von <acronym>URI</acronym>s für welche die
                            gleichen Authentifizierungs Informationen gültig sind. Die
                            <acronym>URI</acronym>s müssen nicht alle auf den gleichen Server
                            zeigen.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>nonce_timeout</property></emphasis></entry>

                        <entry>
                            Ja, wenn <property>accept_schemes</property>
                            <emphasis>digest</emphasis> enthält
                        </entry>

                        <entry>
                            Setzt die Anzahl an Sekunden für welche die Verfolgung gültig ist.
                            Siehe die Notizen anbei.
                        </entry>
                    </row>

                    <row>
                        <entry><emphasis><property>proxy_auth</property></emphasis></entry>
                        <entry>Nein</entry>

                        <entry>
                            Standardmäßig ausgeschaltet. Einschalten um Proxi Authentifizierung
                            durchzuführen statt normaler originaler Server Authentifizierung.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <para>
                Die aktuelle Implementation von <property>nonce_timeout</property> 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 <acronym>MD5</acronym>.
        </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 <methodname>resolve()</methodname> 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:
            </para>

            <programlisting language="txt"><![CDATA[
<benutzername>:<bereich>:<zeugnisse>\n
]]></programlisting>

            <para>
                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 <acronym>MD5</acronym> Hash
                sein.
            </para>

            <para>
                Es gibt zwei gleiche einfache Wege um einen Datei Auflöser zu erstellen:
            </para>

            <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
]]></programlisting>

            <para>
                oder
            </para>

            <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File();
$resolver->setFile($path);
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
$config = array(
    'accept_schemes' => 'basic digest',
    'realm'          => 'My Web Site',
    'digest_domains' => '/members_only /my_account',
    'nonce_timeout'  => 3600,
);
]]></programlisting>

        <para>
            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 <filename>/members_only</filename> und <filename>/my_account</filename>. Der
            Bereichs Wert wird normalerweise durch den Browser in der Passwort Dialog Box
            angezeigt. <property>nonce_timeout</property> verhält sich natürlich so wie oben
            beschrieben.
        </para>

        <para>
            Dann wird ein <classname>Zend_Auth_Adapter_Http</classname> Objekt erstellt:
        </para>

        <programlisting language="php"><![CDATA[
$adapter = new Zend_Auth_Adapter_Http($config);
]]></programlisting>

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

        <programlisting language="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>
            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:
        </para>

        <programlisting language="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>
    </sect2>
</sect1>