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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 16855 -->
<!-- Reviewed: no -->
<sect1 id="zend.auth.adapter.http">

    <title>Adaptador de Autenticación HTTP</title>

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

        <title>Introducción</title>

        <para>
            <classname>Zend_Auth_Adapter_Http</classname> proporciona una
            implementación compatible con <ulink
                url="http://tools.ietf.org/html/rfc2617">RFC-2617</ulink>,
                <ulink
                url="http://en.wikipedia.org/wiki/Basic_authentication_scheme"
                >Basic</ulink> y <ulink
                url="http://en.wikipedia.org/wiki/Digest_access_authentication"
                >Digest</ulink> Autenticación <acronym>HTTP</acronym>. La
            autenticación "Digest" es un método de autenticación
                <acronym>HTTP</acronym> que mejora la autenticación básica
            proporcionando una manera de autenticar sin tener que transmitir la
            contraseña de manera clara en un texto a través de la red. </para>

        <para>
            <emphasis role="strong">Características Principales:</emphasis>
        </para>

        <itemizedlist>
            <listitem>
                <para> Soporta tanto Autenticación "Digest" como Básica. </para>
            </listitem>
            <listitem>
                <para> Establece retos en todos los proyectos soportados, por lo
                    que el cliente puede responder con cualquier proyecto que
                    soporte. </para>
            </listitem>
            <listitem>
                <para> Soporta autenticación proxy. </para>
            </listitem>
            <listitem>
                <para> Incluye soporte para la autenticación contra archivos de
                    texto y proporciona una interfaz para autenticar contra
                    otras fuentes, tales como bases de datos. </para>
            </listitem>
        </itemizedlist>


        <para> Hay algunas características notables del
            <acronym>RFC</acronym>-2617 no implementadas todavía: </para>
        <itemizedlist>
            <listitem>
                <para> Seguimiento "nonce", que permitiría un gran apoyo, y un
                    aumento de la protección de repetidos ataques. </para>
            </listitem>
            <listitem>
                <para> Autenticación con comprobación de integridad, o
                    "auth-int". </para>
            </listitem>
            <listitem>
                <para> Cabecera de información de la autenticación
                        <acronym>HTTP</acronym>. </para>
            </listitem>
        </itemizedlist>


    </sect2>

    <sect2 id="zend.auth.adapter.design_overview">

        <title>Descripción del diseño</title>

        <para> Este adaptador consiste en dos sub-componentes, la propia clase
            autenticación <acronym>HTTP</acronym>, y el llamado "Resolvers". La
            clase autenticación <acronym>HTTP</acronym> encapsula la lógica para
            llevar a cabo tanto la autenticación basica y la "Digest". Utiliza
            un Resolver para buscar la identidad de un cliente en los datos
            almacenados (por defecto, archivos de texto), y recuperar las
            credenciales de los datos almacenados. Las credenciales del
            "Resolved" se comparan con los valores presentados por el cliente
            para determinar si la autenticación es satisfactoria. </para>

    </sect2>

    <sect2 id="zend.auth.adapter.configuration_options">

        <title>Opciones de Configuración</title>

        <para> La clase <classname>Zend_Auth_Adapter_Http</classname> requiere
            un array configurado que pasará a su constructor. Hay varias
            opciones de configuración disponibles, y algunas son obligatorias: </para>
        <table id="zend.auth.adapter.configuration_options.table">
            <title>Opciones de Configuración</title>
            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Nombre de Opción</entry>
                        <entry>Obligatoria</entry>
                        <entry>Descripción</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>
                            <emphasis>
                                <property>accept_schemes</property>
                            </emphasis>
                        </entry>
                        <entry>Si</entry>
                        <entry> Determina que tareas de autenticación acepta el
                            adaptador del cliente. Debe ser una lista separada
                            por espacios que contengo
                                <emphasis>'basic'</emphasis> y/o
                                <emphasis>'digest'</emphasis>. </entry>
                    </row>
                    <row>
                        <entry>
                            <emphasis>
                                <property>realm</property>
                            </emphasis>
                        </entry>
                        <entry>Si</entry>
                        <entry> Establece el realm de autenticación; usernames
                            debe ser único dentro de un determinado realm.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <emphasis>
                                <property>digest_domains</property>
                            </emphasis>
                        </entry>
                        <entry>Si, cuando
                                <methodname>'accept_schemes'</methodname>
                            contiene <emphasis>'digest'</emphasis></entry>
                        <entry> Lista de URIs separadas por espacios para las
                            cuales la misma información de autenticación es
                            válida. No es necesario que todas las URIs apunten
                            al mismo oservidor. </entry>
                    </row>
                    <row>
                        <entry>
                            <emphasis>
                                <property>nonce_timeout</property>
                            </emphasis>
                        </entry>
                        <entry>Si, cuando
                                <methodname>'accept_schemes'</methodname>
                            contiene <emphasis>'digest'</emphasis></entry>
                        <entry> Establece el número de segundos para los cuales
                            el "nonce" es válido. Ver notas de abajo. </entry>
                    </row>
                    <row>
                        <entry>
                            <emphasis>
                                <property>proxy_auth</property>
                            </emphasis>
                        </entry>
                        <entry>No</entry>
                        <entry> Deshabilitado por defecto. Permite llevar a cabo
                            la autenticación del Proxy, en lugar de la
                            autenticación normal del servidor. </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <para> La implementación actual del
                    <property>nonce_timeout</property> tiene algunos efectos
                colaterales interesantes. Este ajuste es supuesto para
                determinar la vida util válida para un determinado "nonce", o de
                manera efectiva el tiempo que una información de autenticación
                del cliente es aceptada. Actualmente, si se establece en 3600
                (por ejemplo), hará que el adaptador indique al cliente las
                nuevas credenciales cada hora, a la hora en punto. </para>
        </note>

    </sect2>

    <sect2 id="zend.auth.adapter.http.resolvers">

        <title>Resolvers</title>

        <para> El trabajo del "Resolver" es tener un username y un realm, y
            devolver algún valor de tipo credencial. La autenticación básica
            espera recibir la versión codificada en Base64 de la contraseña del
            usuario. La autenticación "Digest" espera recibir un hash del
            username del usuario, un realm, y su contraseña (separados por
            coma). Actualmente, sólo se admite el algoritmo de hash
                <acronym>MD5</acronym>. </para>

        <para>
            <classname>Zend_Auth_Adapter_Http</classname> se basa en la
            implementación de objetos
                <classname>Zend_Auth_Adapter_Http_Resolver_Interface</classname>.
            Un archivo de texto de la clase "Resolve" se incluye con este
            adaptador, pero cualquier otro tipo de "resolver" puede ser creado
            simplemente implementando la interfaz del "resolver". </para>

        <sect3 id="zend.auth.adapter.http.resolvers.file">
            <title>Archivo Resolver</title>
            <para> El archivo "resolver" es una clase muy simple. Tiene una
                única propiedad que especifique un nombre de archivo, que
                también puede ser pasado al constructor. Su método
                    <methodname>resolve()</methodname> recorre el archivo de
                texto, buscando una linea con el correspondiente username y
                realm. El formato del archivo de texto es similar a los archivos
                htpasswd de Apache: 
                </para>
                <programlisting><![CDATA[
<username>:<realm>:<credentials>\n
]]></programlisting>
                <para>
                Cada linea consta de tres campos -username, realm, y
                credenciales - cada uno separados por dos puntos. El campo
                credenciales es opaco al archivo "resolver"; simplemente
                devuelve el valor tal como és al llamador. Por lo tanto, este
                formato de archivo sirve tanto de autenticación básica como
                "Digest". En la autenticación básica, el campo credenciales debe
                ser escrito en texto claro. En la autenticación "Digest",
                debería ser en hash <acronym>MD5</acronym> descrito
                anteriormente. </para>
            
            <para> Hay dos formas igualmente fácil de crear un archivo de
                "resolver": </para>
            <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
]]></programlisting>
            <para> o </para>
            <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File();
$resolver->setFile($path);
]]></programlisting> 
            <para>
            Si la ruta está vacía o no se puede leer, se lanza una
            excepción.
            </para>
        </sect3>

    </sect2>

    <sect2 id="zend.auth.adapter.http.basic_usage">

        <title>Uso Básico</title>

        <para> En primer lugar, establecemos un array con los valores de
            configuración obligatorios: </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> Este array hará que el adaptador acepte la autenticación básica o
            "Digest", y requerirá un acceso autenticado a todas las áreas del
            sitio en <filename>/members_only</filename> y
                <filename>/my_account</filename>. El valor realm es normalmente
            mostrado por el navegador en el cuadro de dialogo contraseña. El
                <property>nonce_timeout</property>, por supuesto, se comporta
            como se ha descrito anteriormente. </para>

        <para> A continuación, creamos el objeto Zend_Auth_Adapter_Http: </para>
        <programlisting language="php"><![CDATA[
$adapter = new Zend_Auth_Adapter_Http($config);
]]></programlisting>


        <para> Ya que estamos soportando tanto la autenticación básica como la
            "Digest", necesitamos dos objetos diferentes resolver. Tenga en
            cuenta que esto podría ser facilmente dos clases diferentes: </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> Por último, realizamos la autenticación. El adaptador necesita
            una referencia a ambos objetos solicitud y respuesta para hacer su
            trabajo: </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()) {
    // Bad userame/password, or canceled password prompt
}
]]></programlisting>


    </sect2>

</sect1>