Zend Framework 1.10.9 Manual

Ein Zend_Auth Adapter wird verwendet um sich gegenüber einem speziellen Typ von Authentifizierungs Services zu authentifizieren, wie LDAP, RDBMS, oder Datei-basierenden Speichern. Verschiedene Adapter besitzen leicht unterschiedliche Optionen und Verhaltensweisen, aber einige grundlegende Dinge sind für Authentifizierungs Adapter üblich. Zum Beispiel das die Authentifizierung Zeugnisse akzeptiert werden (enthält auch vorgegebene Identitäten), das Abfragen am Authentifizierungsservice durchgeführt werden, und das Ergebnisse zurückgegeben werden, sind für Zend_Auth Adapter üblich.

Jede Zend_Auth Adapter Klasse implementiert Zend_Auth_Adapter_Interface. Dieses Interface definiert eine Methode, authenticate(), die eine Adapter Klasse implementieren muß um eine Authentifizierungsanfrage auszuführen. Jede Adapter Klasse muß vorher vorbereitet sein bevor authenticate() aufgerufen wird. Diese Vorbereitung des Adapters enthält das Setzen der Zeugnisse (z.B. Benutzername und Passwort) und die Definition von Werten für Adapter spezifische Konfigurationoptionen, wie Datenbank Verbindungsdaten für einen Datenbank Tabellen Adapter.

Das folgende ist ein Beispiel eines Authentifierungs-Adapters der einen Benutzernamen und ein Passwort für die Authentifizierung benötigt. Andere Details, wie zum Beispiel der Authentifizierungs-Service abgefragt wird, werden der Kürze halber ausgelassen:

class MyAuthAdapter implements Zend_Auth_Adapter_Interface
{
    /**
     * Setzt Benutzername und Passwort für die Authentifizierung
     *
     * @return void
     */
    public function __construct($username, $password)
    {
        // ...
    }

    /**
     * Führt einen Authentifizierungs-Versuch durch
     *
     * @throws Zend_Auth_Adapter_Exception Wenn die Authentifizierung nicht
     *                                     durchgeführt wurde
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
        // ...
    }
}

Wie im Docblock angegeben, muß authenticate() eine Instanz von Zend_Auth_Result (oder einer von Zend_Auth_Result abgeleiteten Klassen) zurückgeben. Wenn aus bestimmten Gründen eine Durchführung einer Authentifizierungs-Anfrage nicht möglich ist, sollte authenticate() eine Ausnahme werfen die von Zend_Auth_Adapter_Exception abgeleitet ist.

Zend_Auth Adapter geben eine Instanz von Zend_Auth_Result mit Hilfe von authenticate() zurück um die Ergebnisse des Authentifizierungs-Versuches darzustellen. Adapter veröffentlichen das Zend_Auth_Result Objekt bei der Erstellung, so das die folgenden vier Methoden ein grundsätzliches Set von Benutzerbezogenen Operationen bieten die für die Ergebnisse von Zend_Auth Adapter üblich sind:

• isValid() - Gibt TRUE zurück wenn und nur wenn das Ergebnis einen erfolgreichen Authentifizierungs-Versuch repräsentiert

• getCode() - Gibt einen konstanten Zend_Auth_Result Identifizierer damit der Typ des Authentifizierungs-Fehlers, oder des Erfolgs der stattgefunden hat, ermittelt werden kann. Das kann in Situationen verwendet werden in denen der Entwickler die verschiedenen Ergebnistypen der Authentifizierung unterschiedlich behandeln will. Das erlaubt es dem Entwickler zum Beispiel detailierte Statistiken über die Authentifizierungs-Ergebnisse zu erhalten. Eine andere Verwendung dieses Features ist es spezielle, benutzerdefinierte Nachrichten anzubieten, um Benutzern eine bessere Usability zu ermöglichen, einfach dadurch das Entwickler dazu aufgerufen sind die Risiken solche defailierte Informationen Benutzern anzubieten, statt einer generellen Nachricht eines Authentifizierungs-Fehlers. Für weitere Informationen siehe die Notiz anbei.

• getIdentity() - Gibt die Identität des Authentifizierungs-Versuchs zurück

• getMessages() - Gibt ein Array von Nachrichten zurück nach einem fehlgeschlagenen Authentifizierungs-Versuch

Ein Entwickler kann wünschen basierend auf dem Typ des Authentifizierungs-Ergebnisses zu verzweigen um spezialisiertere Operationen durchzuführen. Einige Operationen die für Entwickler nützlich sein können sind zum Beispiel das Sperren von Konten nachdem zu oft ein falsches Passwort angegeben wurde, das markieren von IP Adressen nachdem zuviele nicht existierende Identitäten angegeben wurden und das anbieten von speziellen, benutzerdefinierten Nachrichten für Authentifizierungs-Ergebnisse an den Benutzer. Die folgenden Ergebniscodes sind vorhanden:

Zend_Auth_Result::SUCCESS
Zend_Auth_Result::FAILURE
Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
Zend_Auth_Result::FAILURE_UNCATEGORIZED

Das folgende Beispiel zeigt wie ein Entwickler anhand des Ergebniscodes verzweigen könnte:

// Innerhalb von AuthController / loginAction
$result = $this->_auth->authenticate($adapter);

switch ($result->getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** Was wegen nicht existierender Identität machen **/
        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
        /** Was wegen ungültigen Zeugnissen machen **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** Was wegen erfolgreicher Authentifizierung machen **/
        break;

    default:
        /** Was wegen anderen Fehlern machen **/
        break;
}

Eine Anfrage zu authentifizieren die Authentifizierungs Zeugnisse enthält ist per se nützlich, aber auch wichtig um die Authentifizierungs Identität bearbeiten zu können ohne das immer die Authentifizierungs Zeugnisse mit jeder Anfrage vorhanden sein müssen.

Trotzdem ist HTTP ein statusloses Protokoll, und Techniken wie Cookies und Sessions wurden entwickelt um Stati über mehrere Anfragen hinweg in Server-seitigen Web Anwendungen zu erhalten.

// Eine Referenz zur Singleton Instanz von Zend_Auth speichern
$auth = Zend_Auth::getInstance();

// 'someNamespace' statt 'Zend_Auth' verwenden
$auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));

/**
 * @todo Den Auth Adapter $authAdapter erstellen
 */

// Authentifizieren, das Ergebnis speichern, und die Identität bei Erfolg
// persistent machen
$result = $auth->authenticate($authAdapter);

class MyStorage implements Zend_Auth_Storage_Interface
{
    /**
     * Gibt true zurück wenn und nur wenn der Speicher leer ist
     *
     * @throws Zend_Auth_Storage_Exception Wenn es unmöglich ist festzustellen
     *                                     ob der Speicher leer ist
     * @return boolean
     */
    public function isEmpty()
    {
        /**
         * @todo Implementierung
         */
    }

    /**
     * Gibt den Inhalt des Speichers zurück
     *
     * Das Verhalten ist undefiniert wenn der Speicher leer ist.
     *
     * @throws Zend_Auth_Storage_Exception Wenn das Lesen von Lesen vom Speicher
     *                                     unmöglich ist
     * @return mixed
     */
    public function read()
    {
        /**
         * @todo Implementierung
         */
    }

    /**
     * Schreibt $contents in den Speicher
     *
     * @param  mixed $contents
     * @throws Zend_Auth_Storage_Exception Wenn das Schreiben von $contents in
     *                                     den Speicher unmöglich ist
     * @return void
     */
    public function write($contents)
    {
        /**
         * @todo Implementierung
         */
    }

    /**
     * Löscht die Intalte vom Speicher
     *
     * @throws Zend_Auth_Storage_Exception Wenn das Löschen der Inhalte vom
     *                                     Speicher unmöglich ist
     * @return void
     */
    public function clear()
    {
        /**
         * @todo Implementierung
         */
    }

}

// Zend_Auth anweisen das die selbstdefinierte Speicherklasse verwendet wird
Zend_Auth::getInstance()->setStorage(new MyStorage());

/**
 * @todo Den Auth Adapter $authAdapter erstellen
 */

// Authentifizieren, das Ergebnis speichern, und die Identität bei Erfolg
$result = Zend_Auth::getInstance()->authenticate($authAdapter);

Es gibt zwei vorhandene Wege um Zend_Auth Adapter zu verwenden:

1. Indirekt durch Zend_Auth::authenticate()

2. Direkt durch die authenticate() Methode des Adapters

Das folgende Beispiel zeigt wie ein Zend_Auth Adapter indirekt verwendet werden kann, durch die Verwendung der Zend_Auth Klasse:

// Eine Referenz zur Singleton-Instanz von Zend_Auth erhalten
$auth = Zend_Auth::getInstance();

// Authentifizierungs Adapter erstellen
$authAdapter = new MyAuthAdapter($username, $password);

// Authentifizierungs Versuch, das Ergebnis abspeichern
$result = $auth->authenticate($authAdapter);

if (!$result->isValid()) {
    // Authentifizierung fehlgeschlagen; die genauen Gründe ausgeben
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Authentifizierung erfolgreich; die Identität ($username) wird in
    // der Session gespeichert
    // $result->getIdentity() === $auth->getIdentity()
    // $result->getIdentity() === $username
}

Sobald die Authentifizierung in einer Anfrage durchgeführt wurde, so wie im obigen Beispiel, ist es sehr einfach zu Prüfen ob eine erfolgreich authentifizierte Identität existiert:

$auth = Zend_Auth::getInstance();
if ($auth->hasIdentity()) {
    // Identität existiert; auslesen
    $identity = $auth->getIdentity();
}

Um eine Identität vom persistenten Speicher zu entfernen muß einfach die clearIdentity() Methode verwendet werden. Das würde typischerweise für die Implementierung einer "Abmelde" Operation in einer Anwendung Verwendung finden.

Zend_Auth::getInstance()->clearIdentity();

Wenn die automatische Verwendung von persistenten Speichern für einen bestimmten Verwendungszweck unangebracht ist, kann ein Entwickler einfach die Verwendung der Zend_Auth Klasse umgehen, und eine Adapter Klasse direkt verwenden. Die direkte Verwendung einer Adapterklasse enthält das Konfigurieren und Vorbereiten eines Adapter Objektes und den Aufruf dessen authenticate() Methode. Adapter-spezifische Details werden in der Dokumentation jeden Adapters besprochen. Das folgende Beispeil verwendet MyAuthAdapter direkt:

// Den Authentifizierungs Adapter erstellen
$authAdapter = new MyAuthAdapter($username, $password);

// Authentifizierungs Versuch, speichere das Ergebnis
$result = $authAdapter->authenticate();

if (!$result->isValid()) {
    // Authentifizierung fehlgeschlagen; die genauen Gründe ausgeben
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Authentifizierung erfolgreich
    // $result->getIdentity() === $username
}