/documentation/manual/de/module_specs/Zend_Auth.xml

  1<?xml version="1.0" encoding="UTF-8"?>
  2<!-- EN-Revision: 24249 -->
  3<!-- Reviewed: 20763 -->
  4<sect1 id="zend.auth.introduction">
  5    <title>Einführung</title>
  6
  7    <para>
  8        <classname>Zend_Auth</classname> bietet eine <acronym>API</acronym> für das Authentifizieren
  9        und enthält konkrete Authentifizierungs-Adapter für übliche Use-Case-Szenarien.
 10    </para>
 11
 12    <para>
 13        <classname>Zend_Auth</classname> behandelt nur die
 14        <emphasis>Authentifizierung</emphasis> und nicht die
 15        <emphasis>Authorisierung</emphasis>. Authentifizierung ist frei definiert als
 16        das Ermitteln, ob eine Entität aktuell das ist, was sie vorgibt zu sein (z.B.
 17        Identifizierung), basierend auf einem Set von Anmeldedaten. Authorisierung, der Prozess des
 18        Entscheidens, ob es einer Entität erlaubt wird, auf andere Entitäten Zugriff zu erhalten,
 19        oder um auf diesen Operationen durchzuführen, ist ausserhalb der Möglichkeit von
 20        <classname>Zend_Auth</classname>. Für weitere Informationen über Authorisierung und
 21        Zugriffskontrolle mit dem Zend Framework, sollte <link
 22            linkend="zend.acl"><classname>Zend_Acl</classname></link> angeschaut werden.
 23    </para>
 24
 25    <note>
 26        <para>
 27            Die <classname>Zend_Auth</classname> Klasse implementiert das Singleton Pattern - nur
 28            eine Instanz der Klasse ist vorhanden - durch ihre statische
 29            Methode <methodname>getInstance()</methodname>. Das bedeutet, dass die Verwendung des
 30            Operators <emphasis>new</emphasis> und des Schlüsselworts <emphasis>clone</emphasis> mit der
 31            Klasse <classname>Zend_Auth</classname> nicht funktioniert; stattdessen muß
 32            <methodname>Zend_Auth::getInstance()</methodname> verwendet werden.
 33        </para>
 34    </note>
 35
 36    <sect2 id="zend.auth.introduction.adapters">
 37        <title>Adapter</title>
 38
 39        <para>
 40            Ein <classname>Zend_Auth</classname>-Adapter wird verwendet, um sich gegenüber einem
 41            speziellen Typ von Authentifizierungsdiensten zu authentifizieren, wie
 42            <acronym>LDAP</acronym>, <acronym>RDBMS</acronym>, oder dateibasierenden Speichern.
 43            Verschiedene Adapter besitzen leicht unterschiedliche Optionen und Verhaltensweisen,
 44            aber einige grundlegende Dinge haben Authentifizierungsadapter gemeinsam. Zum Beispiel
 45            dass für die Authentifizierung Anmeldedaten akzeptiert werden (enthält auch vorgegebene
 46            Identitäten), dass Abfragen am Authentifizierungsservice durchgeführt werden, und dass
 47            Ergebnisse zurückgegeben werden, sind für <classname>Zend_Auth</classname>-Adapter
 48            gebräuchlich.
 49        </para>
 50
 51        <para>
 52            Jede <classname>Zend_Auth</classname>-Adapterklasse implementiert
 53            <classname>Zend_Auth_Adapter_Interface</classname>. Dieses Interface definiert eine
 54            Methode <methodname>authenticate()</methodname>, die eine Adapterklasse
 55            implementieren muß, um eine Authentifizierungsanfrage auszuführen. Jede Adapterklasse
 56            muß vorher vorbereitet werden, bevor <methodname>authenticate()</methodname> aufgerufen
 57            wird. Diese Vorbereitung des Adapters enthält das Setzen der Anmeldedaten (z.B.
 58            Benutzername und Passwort) und die Definition von Werten für adapterspezifische
 59            Konfigurationoptionen, wie Datenbankverbindungsdaten für einen Datenbank-Tabellen-Adapter.
 60        </para>
 61
 62        <para>
 63            Das folgende ist ein Beispiel eines Authentifierungs-Adapters der einen Benutzernamen
 64            und ein Passwort für die Authentifizierung benötigt. Andere Details, wie zum Beispiel
 65            der Authentifizierungs-Service abgefragt wird, werden der Kürze halber ausgelassen:
 66        </para>
 67
 68        <programlisting language="php"><![CDATA[
 69class MyAuthAdapter implements Zend_Auth_Adapter_Interface
 70{
 71    /**
 72     * Setzt Benutzername und Passwort für die Authentifizierung
 73     *
 74     * @return void
 75     */
 76    public function __construct($username, $password)
 77    {
 78        // ...
 79    }
 80
 81    /**
 82     * Führt einen Authentifizierungs-Versuch durch
 83     *
 84     * @throws Zend_Auth_Adapter_Exception Wenn die Authentifizierung nicht
 85     *                                     durchgeführt wurde
 86     * @return Zend_Auth_Result
 87     */
 88    public function authenticate()
 89    {
 90        // ...
 91    }
 92}
 93]]></programlisting>
 94
 95        <para>
 96            Wie im Docblock angegeben, muß <methodname>authenticate()</methodname> eine Instanz von
 97            <classname>Zend_Auth_Result</classname> (oder einer von
 98            <classname>Zend_Auth_Result</classname> abgeleiteten Klassen) zurückgeben. Wenn aus
 99            bestimmten Gründen eine Durchführung einer Authentifizierungsanfrage nicht möglich
100            ist, sollte <methodname>authenticate()</methodname> eine Ausnahme werfen, die von
101            <classname>Zend_Auth_Adapter_Exception</classname> abgeleitet ist.
102        </para>
103    </sect2>
104
105    <sect2 id="zend.auth.introduction.results">
106        <title>Ergebnisse</title>
107
108        <para>
109            <classname>Zend_Auth</classname>-Adapter geben eine Instanz von
110            <classname>Zend_Auth_Result</classname> mit Hilfe von
111            <methodname>authenticate()</methodname> zurück, um die Ergebnisse des
112            Authentifizierungsversuchs darzustellen. Adapter befüllen das
113            Objekt <classname>Zend_Auth_Result</classname> bei der Erstellung, so dass die folgenden
114            vier Methoden ein grundsätzliches Set von benutzerbezogenen Operationen bieten, die für
115            die Ergebnisse von <classname>Zend_Auth</classname> Adapter üblich sind:
116        </para>
117
118        <itemizedlist>
119            <listitem>
120                <para>
121                    <methodname>isValid()</methodname> - Gibt <constant>TRUE</constant> zurück, wenn
122                    und nur wenn das Ergebnis einen erfolgreichen Authentifizierungsversuch
123                    repräsentiert.
124                </para>
125            </listitem>
126
127            <listitem>
128                <para>
129                    <methodname>getCode()</methodname> - Gibt einen konstanten
130                    <classname>Zend_Auth_Result</classname>-Identifizierer zurück, damit der Typ des
131                    Authentifizierungsfehlers, oder des Erfolgs der stattgefunden hat,
132                    ermittelt werden kann. Das kann in Situationen verwendet werden, in denen der
133                    Entwickler die verschiedenen Ergebnistypen der Authentifizierung
134                    unterschiedlich behandeln will. Das erlaubt es dem Entwickler zum Beispiel
135                    detailierte Statistiken über die Authentifizierungsergebnisse zu erhalten.
136                    Eine andere Verwendung dieses Features ist es spezielle, benutzerdefinierte
137                    Nachrichten anzubieten, um Benutzern eine bessere Usability zu ermöglichen,
138                    einfach dadurch dass Entwickler dazu aufgerufen sind, die Risiken solche
139                    detaillierte Informationen Benutzern anzubieten, statt einer generellen
140                    Nachricht eines Authentifizierungsfehlers. Für weitere Informationen siehe
141                    die Notiz anbei.
142                </para>
143            </listitem>
144
145            <listitem>
146                <para>
147                    <methodname>getIdentity()</methodname> - Gibt die Identität des
148                    Authentifizierungsversuchs zurück
149                </para>
150            </listitem>
151
152            <listitem>
153                <para>
154                    <methodname>getMessages()</methodname> - Gibt ein Array von Nachrichten
155                    zurück nach einem fehlgeschlagenen Authentifizierungsversuch
156                </para>
157            </listitem>
158        </itemizedlist>
159
160        <para>
161            Ein Entwickler möchte basierend auf dem Typ des Authentifizierungsergebnisses zu
162            spezialisierteren Operationen verzweigen. Einige Operationen die für
163            Entwickler nützlich sein können, sind zum Beispiel das Sperren von Konten nachdem zu oft
164            ein falsches Passwort angegeben wurde, das Markieren von IP-Adressen, nachdem zuviele
165            nicht existierende Identitäten angegeben wurden und das Anbieten von speziellen,
166            benutzerdefinierten Nachrichten für Authentifizierungsergebnisse an den Benutzer. Die
167            folgenden Ergebniscodes sind vorhanden:
168        </para>
169
170        <programlisting language="php"><![CDATA[
171Zend_Auth_Result::SUCCESS
172Zend_Auth_Result::FAILURE
173Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
174Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
175Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
176Zend_Auth_Result::FAILURE_UNCATEGORIZED
177]]></programlisting>
178
179        <para>
180            Das folgende Beispiel zeigt, wie ein Entwickler anhand des Ergebniscodes verzweigen
181            könnte:
182        </para>
183
184        <programlisting language="php"><![CDATA[
185// Innerhalb von AuthController / loginAction
186$result = $this->_auth->authenticate($adapter);
187
188switch ($result->getCode()) {
189
190    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
191        /** Was wegen nicht existierender Identität machen **/
192        break;
193
194    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
195        /** Was wegen ungültigen Anmeldededaten machen **/
196        break;
197
198    case Zend_Auth_Result::SUCCESS:
199        /** Was wegen erfolgreicher Authentifizierung machen **/
200        break;
201
202    default:
203        /** Was wegen anderen Fehlern machen **/
204        break;
205}
206]]></programlisting>
207    </sect2>
208
209    <sect2 id="zend.auth.introduction.persistence">
210        <title>Dauerhafte Identitäten</title>
211
212        <para>
213            Eine Anfrage zu authentifizieren, die Anmeldedaten enthält ist per se
214            nützlich, aber auch wichtig, um die Authentifizierungs-Identität bearbeiten zu können,
215            ohne dass immer die Anmeldedaten bei jeder Anfrage vorhanden sein müssen.
216        </para>
217
218        <para>
219            Trotzdem ist <acronym>HTTP</acronym> ein statusloses Protokoll, und Techniken wie
220            Cookies und Sessions wurden entwickelt um Stati über mehrere Anfragen hinweg in
221            server-seitigen Web-Anwendungen zu erhalten.
222        </para>
223
224        <sect3 id="zend.auth.introduction.persistence.default">
225            <title>Normale Persistenz in PHP-Sessions</title>
226
227            <para>
228                 Standardmäßig bietet <classname>Zend_Auth</classname> dauerhafte Speicherung der
229                 Identität eines erfolgreichen Authentifizierungsversuches durch Verwendung der
230                 <acronym>PHP</acronym>-Session. Bei einem erfolgreichen Authentifizierungsversuch
231                 speichert <methodname>Zend_Auth::authenticate()</methodname> die Identität des
232                 Authentifizierungsergebnisses im persistenten Speicher. Solange die Konfiguration
233                 nicht verändert wird, verwendet <classname>Zend_Auth</classname> eine
234                 Speicherklasse die <classname>Zend_Auth_Storage_Session</classname> heißt und die
235                 im Gegenzug <link linkend="zend.session"><classname>Zend_Session</classname></link>
236                 verwendet. Eine eigene Klasse kann stattdessen verwendet werden, indem ein Objekt
237                 an <methodname>Zend_Auth::setStorage()</methodname> übergeben wird, welches
238                 <classname>Zend_Auth_Storage_Interface</classname> implementiert.
239            </para>
240
241            <note>
242                <para>
243                    Wenn das automatische persistente Speichern der Identität für einen bestimmten
244                    Anwendungsfall nicht anwendbar ist, können Entwickler trotzdem die
245                    <classname>Zend_Auth</classname> Klasse weiterhin verwenden, statt direkt eine
246                    Adapterklasse anzusprechen.
247                </para>
248            </note>
249
250            <example id="zend.auth.introduction.persistence.default.example">
251                <title>Den Namensraum der Session ändern</title>
252
253                <para>
254                    <classname>Zend_Auth_Storage_Session</classname> verwendet einen Session
255                    Namensraum von '<classname>Zend_Auth</classname>'. Dieser Namensraum kann
256                    überschrieben werden, indem ein anderer Wert an den Konstruktor von
257                    <classname>Zend_Auth_Storage_Session</classname> übergeben wird, und dieser Wert
258                    wird intern an den Konstruktor von <classname>Zend_Session_Namespace</classname>
259                    weitergereicht. Das sollte vor einem Versuch einer Authentifizierung stattfinden,
260                    da <methodname>Zend_Auth::authenticate()</methodname> die automatische
261                    Speicherung der Identität durchführt.
262                </para>
263
264                <programlisting language="php"><![CDATA[
265// Eine Referenz zur Singleton Instanz von Zend_Auth speichern
266$auth = Zend_Auth::getInstance();
267
268// 'someNamespace' statt 'Zend_Auth' verwenden
269$auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));
270
271/**
272 * @todo Den Auth Adapter $authAdapter erstellen
273 */
274
275// Authentifizieren, das Ergebnis speichern, und die Identität bei Erfolg
276// persistent machen
277$result = $auth->authenticate($authAdapter);
278]]></programlisting>
279            </example>
280        </sect3>
281
282        <sect3 id="zend.auth.introduction.persistence.custom">
283            <title>Eigene Speicher implementieren</title>
284
285            <para>
286                Zeitweise wollen Entwickler einen anderen Speichermechanismus für Identitäten
287                verwenden als es von <classname>Zend_Auth_Storage_Session</classname> angeboten
288                wird. Für solche Fälle können Entwickler einfach
289                <classname>Zend_Auth_Storage_Interface</classname> implementieren und eine Instanz
290                der Klasse an <methodname>Zend_Auth::setStorage()</methodname> übergeben.
291            </para>
292
293            <example id="zend.auth.introduction.persistence.custom.example">
294                <title>Eine eigene Speicherklasse verwenden</title>
295
296                <para>
297                    Um eine andere Speicherklasse für die Persistenz von Identitäten zu verwenden
298                    als sie durch <classname>Zend_Auth_Storage_Session</classname> angeboten wird,
299                    können Entwickler <classname>Zend_Auth_Storage_Interface</classname>
300                    implementieren:
301                </para>
302
303                <programlisting language="php"><![CDATA[
304class MyStorage implements Zend_Auth_Storage_Interface
305{
306    /**
307     * Gibt true zurück wenn und nur wenn der Speicher leer ist
308     *
309     * @throws Zend_Auth_Storage_Exception Wenn es unmöglich ist festzustellen,
310     *                                     ob der Speicher leer ist
311     * @return boolean
312     */
313    public function isEmpty()
314    {
315        /**
316         * @todo Implementierung
317         */
318    }
319
320    /**
321     * Gibt den Inhalt des Speichers zurück
322     *
323     * Das Verhalten ist undefiniert, wenn der Speicher leer ist.
324     *
325     * @throws Zend_Auth_Storage_Exception Wenn das Lesen vom Speicher
326     *                                     unmöglich ist
327     * @return mixed
328     */
329    public function read()
330    {
331        /**
332         * @todo Implementierung
333         */
334    }
335
336    /**
337     * Schreibt $contents in den Speicher
338     *
339     * @param  mixed $contents
340     * @throws Zend_Auth_Storage_Exception Wenn das Schreiben von $contents in
341     *                                     den Speicher unmöglich ist
342     * @return void
343     */
344    public function write($contents)
345    {
346        /**
347         * @todo Implementierung
348         */
349    }
350
351    /**
352     * Löscht die Intalte vom Speicher
353     *
354     * @throws Zend_Auth_Storage_Exception Wenn das Löschen der Inhalte vom
355     *                                     Speicher unmöglich ist
356     * @return void
357     */
358    public function clear()
359    {
360        /**
361         * @todo Implementierung
362         */
363    }
364
365}
366]]></programlisting>
367
368                <para>
369                    Um diese selbstgeschriebene Speicherklasse zu verwenden wird,
370                    <methodname>Zend_Auth::setStorage()</methodname> aufgerufen, bevor eine
371                    Authentifizierungsanfrage stattfindet:
372                </para>
373
374                <programlisting language="php"><![CDATA[
375// Zend_Auth anweisen, dass die selbstdefinierte Speicherklasse verwendet wird
376Zend_Auth::getInstance()->setStorage(new MyStorage());
377
378/**
379 * @todo Den Auth Adapter $authAdapter erstellen
380 */
381
382// Authentifizieren, das Ergebnis speichern, und die Identität bei Erfolg
383$result = Zend_Auth::getInstance()->authenticate($authAdapter);
384]]></programlisting>
385            </example>
386        </sect3>
387    </sect2>
388
389    <sect2 id="zend.auth.introduction.using">
390        <title>Verwendung</title>
391
392        <para>
393            Es gibt zwei vorhandene Wege um <classname>Zend_Auth</classname>-Adapter zu verwenden:
394        </para>
395
396        <orderedlist>
397            <listitem>
398                <para>
399                    Indirekt durch <methodname>Zend_Auth::authenticate()</methodname>
400                </para>
401            </listitem>
402
403            <listitem>
404                <para>
405                    Direkt durch die <methodname>authenticate()</methodname> Methode des Adapters
406                </para>
407            </listitem>
408        </orderedlist>
409
410        <para>
411            Das folgende Beispiel zeigt, wie ein <classname>Zend_Auth</classname>-Adapter indirekt
412            verwendet werden kann, durch die Verwendung der Klasse <classname>Zend_Auth</classname>:
413        </para>
414
415        <programlisting language="php"><![CDATA[
416// Eine Referenz zur Singleton-Instanz von Zend_Auth erhalten
417$auth = Zend_Auth::getInstance();
418
419// Authentifizierungs Adapter erstellen
420$authAdapter = new MyAuthAdapter($username, $password);
421
422// Authentifizierungsversuch, das Ergebnis abspeichern
423$result = $auth->authenticate($authAdapter);
424
425if (!$result->isValid()) {
426    // Authentifizierung fehlgeschlagen; die genauen Gründe ausgeben
427    foreach ($result->getMessages() as $message) {
428        echo "$message\n";
429    }
430} else {
431    // Authentifizierung erfolgreich; die Identität ($username) wird in
432    // der Session gespeichert
433    // $result->getIdentity() === $auth->getIdentity()
434    // $result->getIdentity() === $username
435}
436]]></programlisting>
437
438        <para>
439            Sobald die Authentifizierung in einer Anfrage durchgeführt wurde, so wie im obigen
440            Beispiel, ist es sehr einfach zu prüfen, ob eine erfolgreich authentifizierte Identität
441            existiert:
442        </para>
443
444        <programlisting language="php"><![CDATA[
445$auth = Zend_Auth::getInstance();
446if ($auth->hasIdentity()) {
447    // Identität existiert; auslesen
448    $identity = $auth->getIdentity();
449}
450]]></programlisting>
451
452        <para>
453            Um eine Identität vom persistenten Speicher zu entfernen, muß einfach die
454            Methode <methodname>clearIdentity()</methodname> verwendet werden. Das würde
455            typischerweise für die Implementierung einer "Abmelde"-Operation in einer
456            Anwendung Verwendung finden.
457        </para>
458
459        <programlisting language="php"><![CDATA[
460Zend_Auth::getInstance()->clearIdentity();
461]]></programlisting>
462
463        <para>
464            Wenn die automatische Verwendung von persistenten Speichern für einen bestimmten
465            Verwendungszweck unangebracht ist, kann ein Entwickler einfach die Verwendung der
466            Klasse <classname>Zend_Auth</classname> umgehen, und eine Adapterklasse direkt
467            verwenden. Die direkte Verwendung einer Adapterklasse enthält das Konfigurieren und
468            Vorbereiten eines Adapter-Objekts und den Aufruf dessen
469            Methode <methodname>authenticate()</methodname>. Adapter-spezifische Details werden in
470            der Dokumentation jedes Adapters besprochen. Das folgende Beispeil verwendet
471            <classname>MyAuthAdapter</classname> direkt:
472        </para>
473
474        <programlisting language="php"><![CDATA[
475// Den Authentifizierungsadapter erstellen
476$authAdapter = new MyAuthAdapter($username, $password);
477
478// Authentifizierungsversuch, speichere das Ergebnis
479$result = $authAdapter->authenticate();
480
481if (!$result->isValid()) {
482    // Authentifizierung fehlgeschlagen; die genauen Gründe ausgeben
483    foreach ($result->getMessages() as $message) {
484        echo "$message\n";
485    }
486} else {
487    // Authentifizierung erfolgreich
488    // $result->getIdentity() === $username
489}
490]]></programlisting>
491    </sect2>
492</sect1>