repo_zf1/documentation/manual/fr/module_specs/Zend_Auth.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 15617 -->
<!-- Reviewed: no -->
<sect1 id="zend.auth.introduction">
    <title>Introduction</title>

    <para>
        <classname>Zend_Auth</classname> fournit une API pour l'authentification et inclut
        des adaptateurs concrets d'authentification pour les cas les plus courants.
    </para>

    <para>
        <classname>Zend_Auth</classname> est uniquement concerné par
        <emphasis>le processus d'authentification</emphasis> et non pas par
        <emphasis>le processus d'autorisation</emphasis>. 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
        <classname>Zend_Auth</classname>. Pour plus d'informations sur les autorisations et le
        contrôle d'accès via Zend Framework, voyez
        <link linkend="zend.acl"><classname>Zend_Acl</classname></link>.
    </para>

    <note>
        <para>
            La classe <classname>Zend_Auth</classname> inclut un singleton - uniquement une
            instance de la classe est disponible - à travers la méthode statique
            <code>getInstance()</code>. Celle ci utilise un opérateur <code>new</code> et le
            mot-clé <code>clone</code> ne fonctionnera pas avec la classe
            <classname>Zend_Auth</classname>, utilisez <code>getInstance()</code> à la
            place.
        </para>
    </note>

    <sect2 id="zend.auth.introduction.adapters">
        <title>Adaptateurs</title>

        <para>
            Un adaptateur <classname>Zend_Auth</classname> 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
            <classname>Zend_Auth</classname>.
        </para>

        <para>
            Chaque classe d'adaptateur <classname>Zend_Auth</classname> implémente
            <classname>Zend_Auth_Adapter_Interface</classname>. Cette interface définit une
            méthode, <code>authenticate</code>, 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 <code>authenticate()</code>. 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.
        </para>

        <para>
            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é&#160;:
            <programlisting language="php"><![CDATA[
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()
    {
        // ...
    }
}
]]></programlisting>
            Comme indiqué dans la documentation "docblock", <code>authenticate()</code> doit
            retourner une instance de <classname>Zend_Auth_Result</classname> (ou d'une classe
            dérivée de <classname>Zend_Auth_Result</classname>). Si pour quelque raison que ce
            soit, la requête d'authentification ne peut pas être réalisée,
            <code>authenticate()</code> retournera une exception dérivée de
            <classname>Zend_Auth_Adapter_Exception</classname>.
        </para>
    </sect2>

    <sect2 id="zend.auth.introduction.results">
        <title>Résultats</title>

        <para>
            Les adaptateurs <classname>Zend_Auth</classname> retournent une instance de
            <classname>Zend_Auth_Result</classname> via <code>authenticate()</code> de manière à
            présenter les résultats d'une tentative d'authentification. Les adaptateurs alimentent
            l'objet <classname>Zend_Auth_Result</classname> 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 <classname>Zend_Auth</classname>&#160;:
            <itemizedlist>
                <listitem>
                    <para>
                        <code>isValid()</code>&#160;: retourne <code>true</code> si et seulement
                        si le résultat représente une tentative réussie d'authentification
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>getCode()</code>&#160;: retourne une constante
                        <classname>Zend_Auth_Result</classname> qui détermine le type de retour
                        accepté ou refusé (NDT : 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.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>getIdentity()</code>&#160;: retourne l'identité de la tentative
                        d'authentification.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>getMessages()</code>&#160;: retourne un tableau de messages relatifs
                        à une tentative infructueuse d'authentification.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            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&#160;:
        <programlisting language="php"><![CDATA[
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
]]></programlisting>
        </para>

        <para>
            L'exemple suivant illustre comment utiliser le retour&#160;:
        <programlisting language="php"><![CDATA[
// A l'intérieur de la méthode AuthController / loginAction
$resultat = $this->_auth->authenticate($adapter);

switch ($resultat->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;
}
]]></programlisting>
        </para>
    </sect2>

    <sect2 id="zend.auth.introduction.persistence">
        <title>Persistance d'identité</title>

        <para>
            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.
        </para>

        <para>
            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.
        </para>

        <sect3 id="zend.auth.introduction.persistence.default">
            <title>Persistance par défaut dans une session PHP</title>

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

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

            <example id="zend.auth.introduction.persistence.default.example">
                <title>Changer l'espace de nommage de la session</title>

                <para>
                    <classname>Zend_Auth_Storage_Session</classname> utilise un espace de
                    nommage de <code>"Zend_Auth"</code>. Cet espace peut être écrit en passant les
                    valeurs au constructeur de <classname>Zend_Auth_Storage_Session</classname>, et
                    ces valeurs sont passées en interne au constructeur de
                    <classname>Zend_Session_Namespace</classname>. Cela doit être fait avant
                    l'authentification, et avant que
                    <classname>Zend_Auth::authenticate()</classname> ait accompli le stockage
                    automatique de l'identité.
                    <programlisting language="php"><![CDATA[
// Sauver une référence du singleton, instance de Zend_Auth
$auth = Zend_Auth::getInstance();

// Utiliser 'unEspaceDeNommage' instance de 'Zend_Auth'
$auth->setStorage(new Zend_Auth_Storage_Session('unEspaceDeNommage'));

/**
 * @todo Paramètrage de l'adaptateur d'authentification :
 *       $authAdaptateur
 */

// authentification, sauvegarde du résultat
// et stockage du résultat en cas de succès
$resultat = $auth->authenticate($authAdaptateur);
]]></programlisting>
                </para>
            </example>
        </sect3>

        <sect3 id="zend.auth.introduction.persistence.custom">
            <title>Installer un stockage personnalisé</title>

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

            <example id="zend.auth.introduction.persistence.custom.example">
                <title>Utiliser une classe de stockage personnalisée</title>

                <para>
                    Pour utiliser une classe de stockage d'identité persistante autre que
                    <classname>Zend_Auth_Storage_Session</classname>, le développeur commence par
                    implémenter <classname>Zend_Auth_Storage_Interface</classname>&#160;:
                    <programlisting language="php"><![CDATA[
class MonStockage implements Zend_Auth_Storage_Interface
{
    /**
     * Retourne true si et seulement si le stockage est vide
     *
     * @throws Zend_Auth_Storage_Exception S'il est impossible de déterminer
     *                                     si le stockage est vide
     * @return boolean
     */
    public function isEmpty()
    {
        /**
         * @todo implémentation
         */
    }

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

    /**
     * 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
         */
    }

}
]]></programlisting>
                </para>

                <para>
                    Ensuite la classe personnalisée est invoquée, avant la requête
                    d'authentification, avec <classname>Zend_Auth::setStorage()</classname>&#160;:
                    <programlisting language="php"><![CDATA[
// Définit la classe personnalisée à utiliser
Zend_Auth::getInstance()->setStorage(new MonStockage());

/**
 * @todo Paramètrage de l'adaptateur d'authentification :
 *       $authAdaptateur
 */

// Authentification, sauvegarde et
// persistance du résultat en cas de succès.
$result = Zend_Auth::getInstance()->authenticate($authAdaptateur);
]]></programlisting>
                </para>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.auth.introduction.using">
        <title>Utilisation de Zend_Auth</title>

        <para>
            Deux manières d'utiliser les adaptateurs <classname>Zend_Auth</classname> sont
            proposées&#160;:
            <orderedlist>
                <listitem>
                    <para>
                        indirectement, via <classname>Zend_Auth::authenticate()</classname>&#160;;
                    </para>
                </listitem>
                <listitem>
                    <para>
                        directement, via la méthode <code>authenticate()</code> de
                        l'adaptateur.
                    </para>
                </listitem>
            </orderedlist>
        </para>

        <para>
            L'exemple suivant illustre la manière d'utiliser un adaptateur
            <classname>Zend_Auth</classname> de manière indirecte via l'utilisation de la classe
            <classname>Zend_Auth</classname>&#160;:
            <programlisting language="php"><![CDATA[
// Obtention d'une référence de l'instance du Singleton de Zend_Auth
$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()) {
    // Echec 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
}
]]></programlisting>
        </para>

        <para>
            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&#160;:
            <programlisting language="php"><![CDATA[
$auth = Zend_Auth::getInstance();
if ($auth->hasIdentity()) {
    // l'identité existe ; on la récupère
    $identite = $auth->getIdentity();
}
]]></programlisting>
        </para>

        <para>
            Pour retirer une identité du stockage persistant, utilisez simplement la méthode
            <code>clearIdentity()</code>. A utiliser typiquement pour implémenter une opération de
            déconnexion d'une application&#160;:
            <programlisting language="php"><![CDATA[
Zend_Auth::getInstance()->clearIdentity();
]]></programlisting>
        </para>

        <para>
            Quand l'utilisation automatique du stockage persistant n'est pas appropriée, le
            développeur peut simplement contourner l'utilisation de la classe
            <classname>Zend_Auth</classname> 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 <code>authenticate()</code>. Les détails
            spécifiques à un adaptateur sont décrits dans la documentation de chacun d'entre-eux.
            L'exemple suivant utilise directement <classname>MonAdaptateurAuth</classname>&#160;:
            <programlisting language="php"><![CDATA[
// 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
}
]]></programlisting>
        </para>
    </sect2>
</sect1>