ZFResource^beta

Un adaptateur Zend_Auth est utilisé pour authentifier un service particulier d'authentification, comme LDAP, RDBMS ou un stockage basé sur des fichiers. Les différents adaptateurs peuvent posséder des options et des comportements très divers. Cependant, quelques méthodes de base leur sont communes. Par exemple, accepter des éléments d'authentification (incluant une identité prétendue), authentifier et retourner un résultat sont des éléments communs aux adaptateurs Zend_Auth.

Chaque classe d'authentification, adaptateur de Zend_Auth implémente Zend_Auth_Adapter_Interface. Cette interface définit une méthode, authenticate, celle-ci est implémentée par une classe adaptateur à fin de l'authentification. Chaque classe adaptateur doit être préparée avant tout appel de authenticate(). Cela implique que chaque adaptateur fournisse la possibilité de définir des éléments d'authentification (par exemple identifiant et mot de passe) et de définir des valeurs pour les options spécifiques de l'adaptateurs, tels que les paramètres de connexion à une base de données pour un adaptateur qui en fait usage.

L'exemple suivant est un adaptateur d'authentification qui requiert un identifiant et un mot de passe. D'autres détails, tel que la manière d'interroger le service d'authentification, ont été omis par souci de clarté :

<?php
require_once 'Zend/Auth/Adapter/Interface.php';

class MonAdaptateurAuth implements Zend_Auth_Adapter_Interface
{
    /**
     * Définition de l'identifiant et du mot de passe pour authentification
     *
     * @return void
     */
    public function __construct($identifiant, $motdepasse)
    {
        // ...
    }

    /**
     * Réalise une tentative d'authentification
     *
     * @throws Zend_Auth_Adapter_Exception si l'authentification ne peut pas être réalisée
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
        // ...
    }
}
    		

Comme indiqué dans le bloc de documentation, authenticate() doit retourner une instance de Zend_Auth_Result (ou d'une classe derivée de Zend_Auth_Result). Si pour quelque raison que ce soit, la requête d'authentification ne peut pas être réalisée, authenticate() retournera une exception dérivée de Zend_Auth_Adapter_Exception.

Les adaptateurs Zend_Auth retournent une instance de Zend_Auth_Result via authenticate() de manière à présenter les résultats d'une tentative d'authentification. Les adaptateurs alimentent l'objet Zend_Auth_Result lors de sa construction, de manière à ce que les trois méthodes suivantes fournissent un lot de base d'opérations communes aux résultats des adaptateurs Zend_Auth :

Un développeur peut connecté le résultat de l'authentification avec des opérations spécifiques. Certaines opérations développées peuvent regarder le compte après plusieurs refus du mot de passe, marquer une adresse IP après plusieurs essais sur des compte inexistants et de fournir un message spécifique à l'utilisateur final. Les codes suivants sont disponibles :

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
    		

L'exemple suivant illustre comment utiliser le retour :

<?php
// A l'interieur de la méthode AuthController / loginAction
$result = $this->_auth->authenticate($adapter);

switch ($result->getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** l'identifiant n'existe pas **/
        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
        /** mauvaise authentification **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** authentification acceptée **/
        break;

    default:
        /** autres cas **/
        break;
}
    		

Authentifier une requête qui contient des paramètres d'authentification est utiles en soi, mais il est également important de permettre le maintient de l'identité authentifiée sans avoir à présenter ces paramètres d'authentification à chaque requête.

HTTP est un protocole sans état, cependant, des techniques telles que les cookies ou les sessions ont été développées de manière à faciliter le maintien d'un contexte lors de multiples requêtes dans les applications web.

3.1.3.1. Persitence par défaut dans une session PHP

Zend_Session est utilisé par Zend_Auth pour fournir un stockage persistant de l'identité, après une authentification réussie, via les sessions PHP. Après une authentification réussie, Zend_Auth::authenticate() conserve l'identité résultant de l'authentification dans un stockage persistant. Par défaut, Zend_Auth utilise une classe de stockage basée sur Zend_Session. La classe de stockage peut être changée en fournissant un objet de stockage différent à Zend_Auth::setStorage(). Une classe personnalisée peut fournir une implémentation de l'objet Zend_Auth_Storage_Interface à Zend_Auth::setStorage().

	Note
	Si la persistance automatique de l'identité n'est pas souhaitable dans un cas particulier, alors le développeur peut renoncer à utiliser la classe Zend_Auth et préférer utiliser directement une classe adaptateur.

Exemple 3.1. Changer l'espace de nomage de la session

Zend_Auth_Storage_Session utilise un espace de nomage de 'Zend_Auth'. Cet espace peut être écrit en passant les valeurs au constructeur de Zend_Auth_Storage_Session, et ces valeurs sont passées en interne au constructeur de Zend_Session_Namespace. Cela doit être fait avant l'authentification, aprés que Zend_Auth::authenticate() ait accompli le stockage automatique de l'identité.

<?php
// Sauver une référence du singleton, instance de Zend_Auth
require_once 'Zend/Auth.php';
$auth = Zend_Auth::getInstance();

// Utiliser 'someNamespace' instance de 'Zend_Auth'
require_once 'Zend/Auth/Storage/Session.php';
$auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// authentification, sauvegarde du résultat et stockage du résultat en cas de succès
$result = $auth->authenticate($authAdapter);
    				

<?php
require_once 'Zend/Auth/Storage/Interface.php';

class MyStorage implements Zend_Auth_Storage_Interface
{
    /**
     * Retourne true si et seulement si le stockage est vide
     *
     * @throws Zend_Auth_Storage_Exception Si c'est possible de determiner quand le stockage est vide
     * @return boolean
     */
    public function isEmpty()
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Retourne le contenu du stockage
     *
     * Comportement à définir si le stockage est vide.
     *
     * @throws Zend_Auth_Storage_Exception Si la llecture du stockage est possible
     * @return mixed
     */
    public function read()
    {
        /**
         * @todo implementation
         */
    }

    /**
     * Ecrit $contents dans le stockage
     *
     * @param  mixed $contents
     * @throws Zend_Auth_Storage_Exception si l'écriture de $contents est impossible
     * @return void
     */
    public function write($contents)
    {
        /**
         * @todo implementation
         */
    }

    /**
     * RAZ du stockage
     *
     * @throws Zend_Auth_Storage_Exception Si la remise à zéro (RAZ) est impossible
     * @return void
     */
    public function clear()
    {
        /**
         * @todo implementation
         */
    }

}
    				

<?php
// Definit la classe personnalisée à utiliser
Zend_Auth::getInstance()->setStorage(new MyStorage());

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Authentification, sauvegarde et persistance du résultat en cas de succès.
$result = Zend_Auth::getInstance()->authenticate($authAdapter);
    				

Deux manières d'utiliser les adaptateurs Zend_Auth sont fournies

L'exemple suivant illustre la manière d'utiliser un adaptateur Zend_Auth de manière indirecte via l'utilisation de la classe Zend_Auth :

<?php
// Obtention d'une référence de l'instance du singleton de Zend_Auth
require_once 'Zend/Auth.php';
$auth = Zend_Auth::getInstance();

// Définition de l'adaptateur d'authentification
$authAdaptateur = new MonAdaptateurAuth($identifiant, $motdepasse);

// Tentative d'authentification et stockage du résultat
$resultat = $auth->authenticate($authAdaptateur);

if (!$resultat->isValid()) {
    // échec de l'authentification ; afficher pourquoi
    foreach ($resultat->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Authentification réussie ; l'identité ($identifiant) est stockée dans la session
    // $resultat->getIdentity() === $auth->getIdentity()
    // $resultat->getIdentity() === $identifiant
}
    		

Une fois la tentative d'authentification réalisée, tel que montré ci-dessus, il est très simple de vérifier si une identité correctement authentifiée existe :

<?php
$auth = Zend_Auth::getInstance();
if ($auth->hasIdentity()) {
    // l'identité existe ; on la récupère
    $identite = $auth->getIdentity();
}
    		

Pour retirer une identité du stockage persistant, utilisez simplement la méthode clearIdentity(). A utiliser typiquement pour implémenter une opération de déconnexion d'une application :

<?php
Zend_Auth::getInstance()->clearIdentity();
    

Quand l'utilisation automatique du stockage persistant n'est pas appropriée, le développeur peut simplement contourner l'utilisation de la classe Zend_Auth en utilisant directement une classe adaptateur. L'usage direct d'une classe adaptateur implique de configurer et préparer l'objet de l'adaptateur et d'appeler ensuite sa méthode authenticate(). Les détails spécifiques à un adaptateur sont décrits dans la documentation de chacun d'entre-eux. L'exemple suivant utilise directement MonAdaptateurAuth :

<?php
// Définition de l'adaptateur d'authentification
$authAdaptateur = new MonAdaptateurAuth($identifiant, $motdepasse);

// Tentative d'authentification, stockage du résultat
$resultat = $authAdaptateur->authenticate();

if (!$resultat->isValid()) {
    // échec de l'authentification ; afficher pourquoi
    foreach ($resultat->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Authentification réussie
    // $resultat->getIdentity() === $identifiant
}