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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- 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 <acronym>HTTP</acronym>
            <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 <acronym>HTTP</acronym> 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>
        </para>

        <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>
            Il y a quelques caractéristiques de la <acronym>RFC-2617</acronym> qui ne sont pas
            encore supportées&#160;:
        </para>

        <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 <acronym>HTTP</acronym> "Authentication-Info".</para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            Cette adaptateur utilise 2 sous-composants, la classe d'authentification
            <acronym>HTTP</acronym> elle-même et des "Résolveurs." La classe d'authentification
            <acronym>HTTP</acronym> 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;:
        </para>

        <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><emphasis><property>accept_schemes</property></emphasis></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 <emphasis>'basic'</emphasis> et&#160;/&#160;ou
                            <emphasis>'digest'</emphasis>.
                        </entry>
                    </row>
                    <row>
                        <entry><emphasis><property>realm</property></emphasis></entry>
                        <entry>Oui</entry>
                        <entry>
                            Fournit le nom de l'authentification ("realm")&#160;;
                            chaque nom d'utilisateur doit être unique, par nom
                            d'authentification.
                        </entry>
                    </row>
                    <row>
                        <entry><emphasis><property>digest_domains</property></emphasis></entry>
                        <entry>
                            Oui lorsque <property>accept_schemes</property> contient
                            <emphasis>"digest"</emphasis>
                        </entry>
                        <entry>
                            Liste d'<acronym>URI</acronym>, séparées d'espace, pour lesquelles la
                            même information d'authentification est valide. Les
                            <acronym>URI</acronym> peuvent pointer vers différents serveurs.
                        </entry>
                    </row>
                    <row>
                        <entry><emphasis><property>nonce_timeout</property></emphasis></entry>
                        <entry>
                            Oui lorsque <property>accept_schemes</property> contient
                            <emphasis>"digest"</emphasis>
                        </entry>
                        <entry>
                            Nombre de seconde pour la validité du jeton d'authentification.
                            Voyez les notes ci-dessous.
                        </entry>
                    </row>
                    <row>
                        <entry><emphasis><property>proxy_auth</property></emphasis></entry>
                        <entry>Non</entry>
                        <entry>
                            Désactivé par défaut. Activez le pour effectuer une
                            authentification via un Proxy.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <para>
                L'implémentation actuelle du <property>nonce_timeout</property> 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
            ("username") et un nom d'authentification ("realm") et retourner
            des identifiants. L'authentification Basic s'attend à recevoir une version encodée
            Base64 du mot de passe ("password"). L'authentification Digest, elle, attend
            un hash du "username", du "realm", et du "password" (séparés par des deux-points).
            Actuellement le seul algorithme de hash supporté est <acronym>MD5</acronym>.
        </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
                <methodname>resolve()</methodname> traverse le fichier texte à la recherche de la
                ligne qui correspond au "username" et au "realm". La syntaxe est
                similaire aux fichiers htpasswd d'Apache&#160;:
            </para>

            <programlisting language="txt"><![CDATA[
    <username>:<realm>:<credentials>\n
]]></programlisting>

            <para>
                Chaque ligne se décompose en 3 champs - "username", "realm",
                et "credentials" - séparés par des deux-points. Le résolveur ne fait que
                retourner la valeur de "credentials". Ainsi, avec Basic cette valeur
                devra être le mot de passe en clair de l'utilisateur identifié par
                "username". En mode Digest, la valeur <acronym>MD5</acronym> de toute la chaîne
                "username:realm:password" (avec les deux-points).
            </para>

            <para>
                Pour créer des résolveurs de fichiers séparés, utilisez&#160;:
            </para>

            <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
]]></programlisting>

            <para>
                ou
            </para>

            <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File();
$resolver->setFile($path);
]]></programlisting>

            <para>
                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;:
        </para>

        <programlisting language="php"><![CDATA[
$config = array(
    'accept_schemes' => 'basic digest',
    'realm'          => 'My Web Site',
    'digest_domains' => '/members_only /my_account',
    'nonce_timeout'  => 3600,
);
]]></programlisting>

        <para>
            Ce tableau va permettre d'accepter les modes Basic ou Digest et demandera une
            authentification pour les zones du site situées sous <filename>/members_only</filename>
            et <filename>/my_account</filename>. La valeur du "real" est en général affichée par
            le navigateur dans la boite de dialogue. Le paramètre
            <property>nonce_timeout</property>, fonctionne comme expliqué plus haut.
        </para>

        <para>
            Ensuite, créez un objet de <classname>Zend_Auth_Adapter_Http</classname>&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$adapter = new Zend_Auth_Adapter_Http($config);
]]></programlisting>

        <para>
            Comme nous supportons les 2 modes Basic et Digest, nous avons besoin de deux
            résolveurs différents&#160;:
        </para>

        <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>
            Enfin, nous procédons à la demande d'authentification. L'adaptateur a besoin de
            deux objets "Request" et "Response"&#160;:
        </para>

        <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>
    </sect2>
</sect1>