Zend_Auth
Zend_Auth
Programmer's Reference Guide

Introduction

Zend_Auth fournit une API pour l'authentification et inclut des adaptateurs concrets d'authentification pour les cas les plus courants.

Zend_Auth est uniquement concerné par le processus d'authentification et non pas par le processus d'autorisation. L'authentification est définie de manière lâche (souple) afin de déterminer si une entité donnée est bien celle qu'elle prétend être (c.-à-d. identification), sur la base d'identifiants fournis. L'autorisation, l'action de décider si une entité donnée peut accéder à d'autres entités et / ou exécuter des opérations sur celles-ci ne fait pas partie des prérogatives de Zend_Auth. Pour plus d'informations sur les autorisations et le contrôle d'accès via Zend Framework, voyez Zend_Acl.

Note: La classe Zend_Auth inclut un singleton - uniquement une instance de la classe est disponible - à travers la méthode statique getInstance(). Celle ci utilise un opérateur new et le mot-clé clone ne fonctionnera pas avec la classe Zend_Auth, utilisez plutôt getInstance().

Adaptateurs

Un adaptateur Zend_Auth est utilisé pour authentifier via 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'adaptateur 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 réaliser 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'adaptateur, 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é :

  1. class MonAdaptateurAuth implements Zend_Auth_Adapter_Interface
  2. {
  3.     /**
  4.      * Définition de l'identifiant et du mot de passe
  5.      * pour authentification
  6.      *
  7.      * @return void
  8.      */
  9.     public function __construct($identifiant, $motdepasse)
  10.     {
  11.         // ...
  12.     }
  13.  
  14.     /**
  15.      * Réalise une tentative d'authentification
  16.      *
  17.      * @throws Zend_Auth_Adapter_Exception Si l'authentification
  18.      *                                     ne peut pas être réalisée
  19.      * @return Zend_Auth_Result
  20.      */
  21.     public function authenticate()
  22.     {
  23.         // ...
  24.     }
  25. }

Comme indiqué dans la documentation "docblock", authenticate() doit retourner une instance de Zend_Auth_Result (ou d'une classe dérivé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.

Résultats

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 quatre méthodes suivantes fournissent de base un lot d'opérations communes aux résultats des adaptateurs Zend_Auth :

  • isValid() : retourne TRUE si et seulement si le résultat représente une tentative réussie d'authentification.

  • getCode() : retourne une constante Zend_Auth_Result qui détermine le type de retour accepté ou refusé (N.D.T. : voir tableau ci dessous). Cela peut être utilisé pour les développeurs voulant distinguer en amont les différents types de résultat. Il est possible d'avoir des statistiques détaillées, par exemple. Une autre utilisation est la personnalisation du message de retour au client. Attention cependant à ne pas trop donner de détails aux clients pour des raisons de sécurité. Pour plus de détails, consultez les notes ci-dessous.

  • getIdentity() : retourne l'identité de la tentative d'authentification.

  • getMessages() : retourne un tableau de messages relatifs à une tentative infructueuse d'authentification.

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

  1. Zend_Auth_Result::SUCCESS
  2. Zend_Auth_Result::FAILURE
  3. Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
  4. Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
  5. Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
  6. Zend_Auth_Result::FAILURE_UNCATEGORIZED

L'exemple suivant illustre comment utiliser le retour :

  1. // A l'intérieur de la méthode AuthController / loginAction
  2. $resultat = $this->_auth->authenticate($adapter);
  3.  
  4. switch ($resultat->getCode()) {
  5.  
  6.     case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
  7.         /** l'identifiant n'existe pas **/
  8.         break;
  9.  
  10.     case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
  11.         /** mauvaise authentification **/
  12.         break;
  13.  
  14.     case Zend_Auth_Result::SUCCESS:
  15.         /** authentification acceptée **/
  16.         break;
  17.  
  18.     default:
  19.         /** autres cas **/
  20.         break;
  21. }

Persistance d'identité

Authentifier une requête qui contient des paramètres d'authentification est utile en soi, mais il est également important de permettre le maintien de l'identité authentifiée sans avoir à repré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.

Persistance par défaut dans une session PHP

Par défaut, Zend_Auth fournit 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. A moins d'une configuration particulière, Zend_Auth utilise une classe de stockage nommée Zend_Auth_Storage_Session, qui utilise Zend_Session. Une classe personnalisée peut être utilisée pour fournir un objet implémentant 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.

Example #1 Changer l'espace de nommage de la session

Zend_Auth_Storage_Session utilise un espace de nommage 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, et avant que Zend_Auth::authenticate() ait accompli le stockage automatique de l'identité.

  1. // Sauver une référence du singleton, instance de Zend_Auth
  2. $auth = Zend_Auth::getInstance();
  3.  
  4. // Utiliser 'unEspaceDeNommage' instance de 'Zend_Auth'
  5. $auth->setStorage(new Zend_Auth_Storage_Session('unEspaceDeNommage'));
  6.  
  7. /**
  8. * @todo Paramètrage de l'adaptateur d'authentification :
  9. *       $authAdaptateur
  10. */
  11.  
  12. // authentification, sauvegarde du résultat
  13. // et stockage du résultat en cas de succès
  14. $resultat = $auth->authenticate($authAdaptateur);

Installer un stockage personnalisé

Parfois les développeurs ont besoin d'utiliser un comportement de persistance d'identité différent de celui fourni par Zend_Auth_Storage_Session. Dans ces cas, les développeurs implémentent simplement Zend_Auth_Storage_Interface et fournissent t une instance de la classe à Zend_Auth::setStorage().

Example #2 Utiliser une classe de stockage personnalisée

Pour utiliser une classe de stockage d'identité persistante autre que Zend_Auth_Storage_Session, le développeur commence par implémenter Zend_Auth_Storage_Interface :

  1. class MonStockage implements Zend_Auth_Storage_Interface
  2. {
  3.     /**
  4.      * Retourne true si et seulement si le stockage est vide
  5.      *
  6.      * @throws Zend_Auth_Storage_Exception S'il est impossible de déterminer
  7.      *                                     si le stockage est vide
  8.      * @return boolean
  9.      */
  10.     public function isEmpty()
  11.     {
  12.         /**
  13.          * @todo implémentation
  14.          */
  15.     }
  16.  
  17.     /**
  18.      * Retourne le contenu du stockage
  19.      *
  20.      * Comportement à définir si le stockage est vide.
  21.      *
  22.      * @throws Zend_Auth_Storage_Exception Si la lecture du stockage
  23.      *                                     est impossible
  24.      * @return mixed
  25.      */
  26.     public function read()
  27.     {
  28.         /**
  29.          * @todo implémentation
  30.          */
  31.     }
  32.  
  33.     /**
  34.      * Ecrit $contents dans le stockage
  35.      *
  36.      * @param  mixed $contents
  37.      * @throws Zend_Auth_Storage_Exception Si l'écriture de $contents
  38.      *                                     est impossible
  39.      * @return void
  40.      */
  41.     public function write($contents)
  42.     {
  43.         /**
  44.          * @todo implementation
  45.          */
  46.     }
  47.  
  48.     /**
  49.      * RAZ du stockage
  50.      *
  51.      * @throws Zend_Auth_Storage_Exception Si la remise à zéro (RAZ)
  52.      *                                     est impossible
  53.      * @return void
  54.      */
  55.     public function clear()
  56.     {
  57.         /**
  58.          * @todo implementation
  59.          */
  60.     }
  61.  
  62. }

Ensuite la classe personnalisée est invoquée, avant la requête d'authentification, avec Zend_Auth::setStorage() :

  1. // Définit la classe personnalisée à utiliser
  2. Zend_Auth::getInstance()->setStorage(new MonStockage());
  3.  
  4. /**
  5. * @todo Paramètrage de l'adaptateur d'authentification :
  6. *       $authAdaptateur
  7. */
  8.  
  9. // Authentification, sauvegarde et
  10. // persistance du résultat en cas de succès.
  11. $result = Zend_Auth::getInstance()->authenticate($authAdaptateur);

Utilisation de Zend_Auth

Deux manières d'utiliser les adaptateurs Zend_Auth sont proposées :

  1. indirectement, via Zend_Auth::authenticate() ;

  2. directement, via la méthode authenticate() de l'adaptateur.

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 :

  1. // Obtention d'une référence de l'instance du Singleton de Zend_Auth
  2. $auth = Zend_Auth::getInstance();
  3.  
  4. // Définition de l'adaptateur d'authentification
  5. $authAdaptateur = new MonAdaptateurAuth($identifiant, $motdepasse);
  6.  
  7. // Tentative d'authentification et stockage du résultat
  8. $resultat = $auth->authenticate($authAdaptateur);
  9.  
  10. if (!$resultat->isValid()) {
  11.     // Echec de l'authentification ; afficher pourquoi
  12.     foreach ($resultat->getMessages() as $message) {
  13.         echo "$message\n";
  14.     }
  15. } else {
  16.     // Authentification réussie ; l'identité ($identifiant) est
  17.     // stockée dans la session
  18.     // $resultat->getIdentity() === $auth->getIdentity()
  19.     // $resultat->getIdentity() === $identifiant
  20. }

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 :

  1. $auth = Zend_Auth::getInstance();
  2. if ($auth->hasIdentity()) {
  3.     // l'identité existe ; on la récupère
  4.     $identite = $auth->getIdentity();
  5. }

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 :

  1. 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 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 :

  1. // Définition de l'adaptateur d'authentification
  2. $authAdaptateur = new MonAdaptateurAuth($identifiant, $motdepasse);
  3.  
  4. // Tentative d'authentification, stockage du résultat
  5. $resultat = $authAdaptateur->authenticate();
  6.  
  7. if (!$resultat->isValid()) {
  8.     // échec de l'authentification ; afficher pourquoi
  9.     foreach ($resultat->getMessages() as $message) {
  10.         echo "$message\n";
  11.     }
  12. } else {
  13.     // Authentification réussie
  14.     // $resultat->getIdentity() === $identifiant
  15. }
Zend_Auth
Zend_Auth
Programmer's Reference Guide