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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 15617 -->
<!-- Reviewed: no -->
<sect1 id="zend.auth.adapter.http">
    <title>Adaptateur d'authentification HTTP</title>

    <sect2 id="zend.auth.adapter.http.introduction">
        <title>Introduction</title>

        <para>
            <classname>Zend_Auth_Adapter_Http</classname> fournit une implémentation des
            authentifications HTTP
            <ulink url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">Basic</ulink>et
            <ulink url="http://en.wikipedia.org/wiki/Digest_access_authentication">Digest</ulink>,
            au regard de la norme
            <ulink url="http://tools.ietf.org/html/rfc2617">RFC-2617</ulink>. Digest est une
            méthode d'authentification HTTP basée sur Basic, mais qui augmente la sécurité en
            fournissant un moyen d'authentification sans transmettre le mot de passe en clair, sur
            le réseau.
        </para>

        <para>
            <emphasis>Caractéristiques principales&#160;:</emphasis>
            <itemizedlist>
                <listitem>
                    <para>Support des méthodes Basic et Digest&#160;;</para>
                </listitem>
                <listitem>
                    <para>
                        Propose tous les des schémas de challenge, le client peut répondre avec
                        le schéma qu'il supporte&#160;;
                    </para>
                </listitem>
                <listitem>
                    <para>Support de l'authentification Proxy&#160;;</para>
                </listitem>
                <listitem>
                    <para>
                        Inclus le support d'authentification de type fichier, et fournit une
                        interface pour créer son propre support, comme une base de données.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Il y a quelques caractéristiques de la RFC-2617 qui ne sont pas encore
            supportées&#160;:
            <itemizedlist>
                <listitem>
                    <para>
                        Le "Nonce tracking", mécanisme qui évite les attaques par
                        répétitions&#160;;
                    </para>
                </listitem>
                <listitem>
                    <para>Authentification avec vérification d'intégrité ("auth-int")&#160;;</para>
                </listitem>
                <listitem>
                    <para>En-tête HTTP "Authentication-Info".</para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.auth.adapter.design_overview">
        <title>Fonctionnement</title>

        <para>
            Cette adaptateur utilise 2 sous-composants, la classe d'authentification HTTP
            elle-même et des "Résolveurs." La classe d'authentification HTTP encapsule la logique
            de commande des authentifications Basic et Digest. Elle utilise aussi un résolveur pour
            chercher les identifiants sur un disque (fichier texte par défaut), et les analyser.
            Ils sont alors comparés aux valeurs envoyées par le client pour déterminer une
            éventuelle correspondance.
        </para>
    </sect2>

    <sect2 id="zend.auth.adapter.configuration_options">
        <title>Options de configuration</title>

        <para>
            La classe <classname>Zend_Auth_Adapter_Http</classname> requière un tableau de
            configuration lors de sa construction. Il y a plusieurs options de configuration
            disponibles, dont certaines requises&#160;:
            <table id="zend.auth.adapter.configuration_options.table">
                <title>Liste des options de configuration</title>

                <tgroup cols="3">
                    <thead>
                        <row>
                            <entry>Nom</entry>
                            <entry>Requise (?)</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><code>accept_schemes</code></entry>
                            <entry>Oui</entry>
                            <entry>
                                Détermine les schémas d'authentification que l'adaptateur va
                                accepter du client. Ce doit être une liste séparée par des espaces,
                                contenant <code>'basic'</code> et/ou <code>'digest'</code>.
                            </entry>
                        </row>
                        <row>
                            <entry><code>realm</code></entry>
                            <entry>Oui</entry>
                            <entry>
                                Fournit le nom de l'authentification (<code>realm</code>)&#160;;
                                chaque nom d'utilisateur doit être unique, par nom
                                d'authentification.
                            </entry>
                        </row>
                        <row>
                            <entry><code>digest_domains</code></entry>
                            <entry>
                                Oui lorsque<code> "accept_schemes"</code> contient
                                <code>"digest"</code>
                            </entry>
                            <entry>
                                Liste d'URI, séparées d'espace, pour lesquelles la même information
                                d'authentification est valide. Elles peuvent pointer vers
                                différents serveurs.
                            </entry>
                        </row>
                        <row>
                            <entry><code>nonce_timeout</code></entry>
                            <entry>
                                Oui lorsque <code>"accept_schemes"</code> contient
                                <code>"digest"</code>
                            </entry>
                            <entry>
                                Nombre de seconde pour la validité du jeton d'authentification.
                                Voyez les notes ci-dessous.
                            </entry>
                        </row>
                        <row>
                            <entry><code>proxy_auth</code></entry>
                            <entry>Non</entry>
                            <entry>
                                Désactivé par défaut. Activez le pour effectuer une
                                authentification via un Proxy.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>

        <note>
            <para>
                L'implémentation actuelle du <code>nonce_timeout</code> a des effets
                intéressants. Ce paramètre doit déterminer le temps de validité d'un jeton,
                autrement dit : le temps d'acceptation d'un client. Par exemple, une valeur de 3600
                aura pour effet de commander à l'adaptateur le rappel des informations
                d'identification du client, toutes les heures. Ce comportement sera changé lorsque
                le paramètre "nonce tracking" sera supporté.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.auth.adapter.http.resolvers">
        <title>Résolveurs</title>

        <para>
            Le travail du résolveur consiste à récupérer un nom d'utilisateur
            (<code>username</code>) et un nom d'authentification (<code>realm</code>) et retourner
            des identifiants. L'authentification Basic s'attend à recevoir une version encodée
            Base64 du mot de passe (<code>password</code>). L'authentification Digest, elle, attend
            un hash du <code>username</code>, du <code>realm</code>, et du <code>password</code>
            (séparés par des deux-points). Actuellement le seul algorithme de hash supporté est
            MD5.
        </para>

        <para>
            <classname>Zend_Auth_Adapter_Http</classname> se fie a des objets implémentant
            <classname>Zend_Auth_Adapter_Http_Resolver_Interface</classname>. Une classe de
            résolution de fichier texte est inclue avec cet adaptateur, mais n'importe quelle
            classe peut être écrite, grâce à l'interface.
        </para>

        <sect3 id="zend.auth.adapter.http.resolvers.file">
            <title>Résolveur fichiers</title>

            <para>
                Cette classe est très simple. Son constructeur ne prend qu'un paramètre qui
                définit le nom du fichier cible. Un accesseur existe aussi. Sa méthode
                <code>resolve()</code> traverse le fichier texte à la recherche de la ligne qui
                correspond au <code>username</code> et au <code>realm</code>. La syntaxe est
                similaire aux fichiers <code>htpasswd</code> d'Apache&#160;:
                <programlisting><![CDATA[
    <username>:<realm>:<credentials>\n
]]></programlisting>
                Chaque ligne se décompose en 3 champs - <code>username</code>, <code>realm</code>,
                et <code>credentials</code> - séparés par des deux-points. Le résolveur ne fait que
                retourner la valeur de "<code>credentials</code>". Ainsi, avec Basic cette valeur
                devra être le mot de passe en clair de l'utilisateur identifié par
                <code>username</code>. En mode Digest, la valeur MD5 de toute la chaîne
                <code>username:realm:password</code> (avec les deux-points).
            </para>

            <para>
                Pour créer des résolveurs de fichiers séparés, utilisez&#160;:
                <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
]]></programlisting>
                ou
                <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File();
$resolver->setFile($path);
]]></programlisting>
                Si le chemin donné n'est pas lisible, une exception est envoyée.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.auth.adapter.http.basic_usage">
        <title>Usage général&#160;:</title>

        <para>
            Tout d'abord, créez un tableau de configuration avec les options requises&#160;:
            <programlisting language="php"><![CDATA[
$config = array(
    'accept_schemes' => 'basic digest',
    'realm'          => 'My Web Site',
    'digest_domains' => '/members_only /my_account',
    'nonce_timeout'  => 3600,
);
]]></programlisting>
            Ce tableau va permettre d'accepter les modes Basic ou Digest et demandera une
            authentification pour les zones du site situées sous <code>/members_only</code> et
            <code>/my_account</code>. La valeur du <code>realm</code> est en général affichée par
            le navigateur dans la boite de dialogue. Le paramètre <code>nonce_timeout</code>,
            fonctionne comme expliqué plus haut.
        </para>

        <para>
            Ensuite, créez un objet de <classname>Zend_Auth_Adapter_Http</classname>&#160;:
            <programlisting language="php"><![CDATA[
$adapter = new Zend_Auth_Adapter_Http($config);
]]></programlisting>
        </para>

        <para>
            Comme nous supportons les 2 modes Basic et Digest, nous avons besoin de deux
            résolveurs différents&#160;:
            <programlisting language="php"><![CDATA[
$basicResolver = new Zend_Auth_Adapter_Http_Resolver_File();
$basicResolver->setFile('files/basicPasswd.txt');

$digestResolver = new Zend_Auth_Adapter_Http_Resolver_File();
$digestResolver->setFile('files/digestPasswd.txt');

$adapter->setBasicResolver($basicResolver);
$adapter->setDigestResolver($digestResolver);
]]></programlisting>
        </para>

        <para>
            Enfin, nous procédons à la demande d'authentification. L'adaptateur a besoin de
            deux objets <code>Request</code> et <code>Response</code>&#160;:
            <programlisting language="php"><![CDATA[
assert($request instanceof Zend_Controller_Request_Http);
assert($response instanceof Zend_Controller_Response_Http);

$adapter->setRequest($request);
$adapter->setResponse($response);

$result = $adapter->authenticate();
if (!$result->isValid()) {
    // Mauvais username/password, ou action annulée
}
]]></programlisting>
        </para>
    </sect2>
</sect1>