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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20763 -->
<!-- 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>