repo_zf1/documentation/manual/es/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>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-2617</acronym>
            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
                            <property>accept_schemes</property>
                            contiene
                            <emphasis>'digest'</emphasis>
                        </entry>
                        <entry>
                            Lista de
                            <acronym>URI</acronym>
                            s separadas por
                            espacios para las cuales la misma información de
                            autenticación es válida. No es necesario que todas
                            las
                            <acronym>URI</acronym>
                            s apunten al mismo
                            oservidor.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <emphasis>
                                <property>nonce_timeout</property>
                            </emphasis>
                        </entry>
                        <entry>
                            Si, cuando
                            <property>accept_schemes</property>
                            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 language="txt"><![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>