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: <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 <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> Si la ruta está vacía o no se puede leer, se lanza una excepción. 

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