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

<?xml version="1.0" encoding="UTF-8"?>
<!-- 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 HTTP.
            La autenticación "Digest" es un método de autenticación HTTP 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>
            <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>

        <para>
            Hay algunas características notables del RFC-2617 no implementadas todavía:
            <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 HTTP.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

    </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 HTTP, y el llamado "Resolvers". 
            La clase autenticación HTTP 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:
            <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><code>accept_schemes</code></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 <code>'basic'</code> y/o <code>'digest'</code>.
                            </entry>
                        </row>
                        <row>
                            <entry><code>realm</code></entry>
                            <entry>Si</entry>
                            <entry>
                                Establece el realm de autenticación; usernames debe ser único dentro de un determinado realm.
                            </entry>
                        </row>
                        <row>
                            <entry><code>digest_domains</code></entry>
                            <entry>Si, cuando <code>'accept_schemes'</code> contiene <code>'digest'</code></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><code>nonce_timeout</code></entry>
                            <entry>Si, cuando <code>'accept_schemes'</code> contiene <code>'digest'</code></entry>
                            <entry>
                                Establece el número de segundos para los cuales el "nonce" es válido.
                                Ver notas de abajo.
                            </entry>
                        </row>
                        <row>
                            <entry><code>proxy_auth</code></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>
        </para>

        <note>
            <para>
                La implementación actual del <code>nonce_timeout</code> 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 MD5.
        </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 <code>resolve()</code> 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:
                <programlisting><![CDATA[
<username>:<realm>:<credentials>\n
]]></programlisting>
                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 MD5 descrito 
                anteriormente.
            </para>

            <para>
                Hay dos formas igualmente fácil de crear un archivo de "resolver":
                <programlisting role="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
]]></programlisting>
                o
                <programlisting role="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File();
$resolver->setFile($path);
]]></programlisting>
                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:
            <programlisting role="php"><![CDATA[
$config = array(
    'accept_schemes' => 'basic digest',
    'realm'          => 'My Web Site',
    'digest_domains' => '/members_only /my_account',
    'nonce_timeout'  => 3600,
);
]]></programlisting>
			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 <code>/members_only</code> y <code>/my_account</code>. El valor realm es normalmente 
			mostrado por el navegador en el cuadro de dialogo contraseña. El <code>nonce_timeout</code>, por supuesto, se 
			comporta como se ha descrito anteriormente.
        </para>

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

        <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:
            <programlisting role="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>
            Por último, realizamos la autenticación. El adaptador necesita una referencia a ambos objetos solicitud y 
            respuesta para hacer su trabajo:
            <programlisting role="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>
        </para>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->