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

<?xml version="1.0" encoding="UTF-8"?>
    <!-- EN-Revision: 16652 -->
    <!-- Reviewed: no -->
<sect1 id="zend.auth.introduction">
    <title>Introducción</title>
    <para>
        <classname>Zend_Auth</classname>
        provee una
        <acronym>API</acronym>
        para
        autenticación e incluye adaptadores concretos de autenticación para
        escenarios de casos
        de uso común.
    </para>
    <para>
        <classname>Zend_Auth</classname>
        es concerniente sólo con
        <emphasis>autenticación</emphasis>
        y no con
        <emphasis>autorización</emphasis>
        . Autenticación es vagamente
        definido como: determinar si una entidad realmente es lo que
        pretende
        ser (o sea, identificación), basandose en un grupo de credenciales.
        Autorización, el
        proceso de decidir si se permite a una entidad: acceso
        a, o el realizar operaciones en, otras
        entidades esta fuera del alcance
        de
        <classname>Zend_Auth</classname>
        . Para más información sobre
        autorización y control de acceso con Zend Framework, por favor
        vea
        <link linkend="zend.acl">Zend_Acl</link>
        .
    </para>
    <note>
        <para>
            La clase
            <classname>Zend_Auth</classname>
            implementa el patrón
            Singleton - sólo una instancia de la clase está disponible - a
            través de su método estático
            <methodname>getInstance()</methodname>
            . Esto significa que usar el operador
            <emphasis>new</emphasis>
            y
            la keyword
            <emphasis>clone</emphasis>
            no va a funcionar con la
            clase
            <classname>Zend_Auth</classname>
            : use
            <methodname>Zend_Auth::getInstance()</methodname>
            en su lugar.
        </para>
    </note>
    <sect2 id="zend.auth.introduction.adapters">

        <title>Adaptadores</title>

        <para>
            Un adaptador
            <classname>Zend_Auth</classname>
            es usado para
            autenticar en contra de un tipo particular de servicio de
            autenticación,
            como
            <acronym>LDAP</acronym>
            ,
            <acronym>RDBMS</acronym>
            , o almacenamiento basado en
            ficheros. Diferentes adaptadores pueden tener opciones y
            compotamientos muy diferentes, pero algunas cosas básicas son
            comunes entre los
            adaptadores de autenticación. Por ejemplo, aceptar
            credenciales de autenticación
            (incluyendo una identidad supuesta),
            realizar consultas ante el servicio de
            autenticación, y regresar
            resultados, son comunes para los adaptadores
            <classname>Zend_Auth</classname>
            .
        </para>

        <para>
            Cada clase adaptadora
            <classname>Zend_Auth</classname>
            implementa
            <classname>Zend_Auth_Adapter_Interface</classname>
            . Esta
            interface define un metodo,
            <methodname>authenticate()</methodname>
            , que la clase adaptadora debe implementar para realizar una
            peticion de autenticación.
            Cada clase adaptadora debe ser preparada
            antes de llamar a
            <methodname>authenticate()</methodname>
            . Esta
            preparación del adaptador incluye la creación de credenciales (p.ej.
            nombre de
            usuario y contraseña) y la definición de valores para
            opciones de configuración
            especificos del adaptador, como valores de
            coneccion a base de datos para un adaptador de
            tabla de base de
            datos.
        </para>

        <para>El siguente ejemplo es un adaptador de autenticación que requiere
            que un nombre de
            usuario y contraseña sean especificados para la
            autenticación. Otros detalles, como la
            forma de realizar peticiones
            al servicio de autenticación, han sido omitídos por
            brevedad:
       </para>

        <programlisting language="php"><![CDATA[
class MyAuthAdapter implements Zend_Auth_Adapter_Interface
{
    /**
     * Establece nombre de usuario y contraseña para autenticacón
     *
     * @return void
     */
    public function __construct($username, $password)
    {
        // ...
    }

    /**
     * Realiza un intento de autenticación
     *
     * @throws Zend_Auth_Adapter_Exception Si la autenticación no puede
     *                                     ser realizada
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
        // ...
    }
}
]]></programlisting>

        <para>
            Como se ha indicado en su docblock,
            <methodname>authenticate()</methodname>
            debe regresar una
            instancia de
            <classname>Zend_Auth_Result</classname>
            (o de una clase
            derivada de
            <classname>Zend_Auth_Result</classname>
            ). Si por alguna
            razón es imposible realizar una petición de autenticación,
            <methodname>authenticate()</methodname>
            debería arrojar una
            excepción que se derive de
            <classname>Zend_Auth_Adapter_Exception</classname>
            .
        </para>

    </sect2>

    <sect2 id="zend.auth.introduction.results">

        <title>Resultados</title>

        <para>
            Los adaptadores
            <classname>Zend_Auth</classname>
            regresan una instancia de
            <classname>Zend_Auth_Result</classname>
            con
            <methodname>authenticate()</methodname>
            para representar el
            resultado de un intento de autenticación. Los adaptadores llenan el
            objeto
            <classname>Zend_Auth_Result</classname>
            en cuanto se
            construye, así que los siguientes cuatro métodos proveen un grupo
            básico de
            operaciones "frente al usuario" que son comunes a los
            resultados de adaptadores
            Zend_Auth:
        </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>isValid()</methodname>
                        - regresa true si y
                        solo si el resultado representa un intento de
                        autenticación exitoso
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>getCode()</methodname>
                        - regresa una
                        constante identificadora
                        <classname>Zend_Auth_Result</classname>
                        para
                        determinar el tipo de fallo en la autenticación o si ha
                        sido exitosa.
                        Este puede ser usado en situaciones cuando
                        el desarrollador desea distinguir
                        entre varios tipos de
                        resultados de autenticación. Esto permite a los
                        desarrolladores, por ejemplo, mantener estadísticas
                        detalladas de los
                        resultados de autenticación. Otro uso
                        de esta característica es: proporcionar
                        al usuario
                        mensajes específicos detallados por razones de
                        usabilidad, aunque
                        los desarrolladores son exhortados a
                        considerar el riesgo de proporcionar
                        tales detalles a
                        los usuarios, en vez de un mensaje general de fallo en
                        la
                        autenticación. Para más información, vea las
                        siguientes notas:
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>getIdentity()</methodname>
                        - regresa la
                        identidad del intento de autenticación
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>getMessages()</methodname>
                        - regresa un
                        arreglo de mensajes pertinentes a un fallido intento de
                        autenticación
                    </para>
                </listitem>
            </itemizedlist>


        <para>El desarrollador podría desear ramificar basado en el tipo de
            resultado de la
            autenticación a fin de realizar operaciones mas
            específicas. Algunas operaciones que los
            desarrolladores podrían
            encontrar útiles son: bloquear cuentas despues de varios intentos
            fallidos de ingresar una contraseña, marcar una dirección IP despues
            de que ha intentado
            muchas identidades no existentes, y porporcionar
            al usuario mensajes especificos
            resultados de la autenticación. Los
            siguientes codigos de resultado están disponibles:
       </para>

        <programlisting language="php"><![CDATA[
Zend_Auth_Result::SUCCESS
Zend_Auth_Result::FAILURE
Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
Zend_Auth_Result::FAILURE_UNCATEGORIZED
]]></programlisting>

        <para>El siguiente ejemplo ilustra como un desarrollador podría
            ramificar basado en el código
            resultado:
       </para>
        <programlisting language="php"><![CDATA[
// debtri de AuthController / loginAction
$result = $this->_auth->authenticate($adapter);

switch ($result->getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** realiza algo para identidad inexistente **/
        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
        /** realiza algo para credencial invalida **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** realiza algo para autenticación exitosa **/
        break;

    default:
        /** realiza algo para otras fallas **/
        break;
}
]]></programlisting>

    </sect2>

    <sect2 id="zend.auth.introduction.persistence">

        <title>Persistencia de Identidad</title>

        <para>Autenticar una petición que incluye credenciales de autenticación
            es util por sí mismo,
            pero también es importante el soportar
            mantener la identidad autenticada sin tener que
            presentar las
            credenciales de autenticación con cada petición.</para>

        <para>
            <acronym>HTTP</acronym>
            es un protocolo sin estado, sin embargo, se han desarrollado
            técnicas como las cookies y
            sesiones a fin de facilitar mantener el
            estado a través de multiples peticiones en
            aplicaciones web del lado
            del servidor.
        </para>

        <sect3 id="zend.auth.introduction.persistence.default">

            <title>Persistencia por Defecto en la Sesión PHP</title>

            <para>
                Por defecto,
                <classname>Zend_Auth</classname>
                provee
                almacenamiento persistente de la identidad desde un intento de
                autenticación
                exitoso usando la sesión
                <acronym>PHP</acronym>
                . En un intento de
                autenticación exitoso,
                <methodname>end_Auth::authenticate()</methodname>
                almacena la
                identidad del resultado de autenticación en almacenamiento
                persistente. A
                menos que se configure diferente,
                <classname>Zend_Auth</classname>
                usa una clase de
                almacenamiento llamada
                <classname>Zend_Auth_Storage_Session</classname>
                , la cual,
                a su vez usa
                <link linkend="zend.session">
                    <classname>Zend_Session</classname>
                </link>
                . Una clase diferente podría ser utilizada mediante
                proveer un objeto que implemente
                <classname>Zend_Auth_Storage_Interface</classname>
                a
                <methodname>Zend_Auth::setStorage()</methodname>
            </para>

            <note>
                <para>
                    Si el automático almacenamiento persistente de la
                    identidad no es apropiado para
                    un caso en particular,
                    entonces los desarrolladores podrían dejar de usar la
                    clase
                    <classname>Zend_Auth</classname>
                    al mismo tiempo,
                    utilizando en su lugar una clase adaptadora directamente.
                </para>
            </note>

            <example id="zend.auth.introduction.persistence.default.example">

                <title>Modifying the Session Namespace</title>

                <para>
                    <classname>Zend_Auth_Storage_Session</classname>
                    usa un
                    espacionombre (namespace) de sesión 'Zend_Auth'. Este
                    espacio-nombre podría
                    ser OVERRIDDEN al pasar un valor
                    diferente al contructor de
                    <classname>Zend_Auth_Storage_Session</classname>
                    , y
                    este valor es pasado internamente al constructor de
                    <classname>Zend_Session_Namespace</classname>
                    . Esto
                    debería ocurrir antes de que se intente la autenticación, ya
                    que
                    <methodname>Zend_Auth::authenticate()</methodname>
                    realiza
                    el almacenamiento automático de la identidad.
                </para>

                <programlisting language="php"><![CDATA[
// Almacena una referencia a la instancia Singleton de Zend_Auth
$auth = Zend_Auth::getInstance();

// Usa 'unEspacionombre' en lugar de 'Zend_Auth'
$auth->setStorage(new Zend_Auth_Storage_Session('unEspacionombre'));

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Autenticar, almacenando el resultado, y persistiendo la identidad en
// suceso
$result = $auth->authenticate($authAdapter);
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.auth.introduction.persistence.custom">

            <title>Implementando Almacenamiento Personalizado</title>

            <para>
                En ocaciones los desarrolladores podrían necesitar usar un
                diferente comportamiento
                de persistencia de identidad que el
                provisto por
                <classname>Zend_Auth_Storage_Session</classname>
                .
                Para esos casos los desarrolladores podrían simplemente
                implementar
                <classname>Zend_Auth_Storage_Interface</classname>
                y
                suplir una instancia de la clase a
                <methodname>Zend_Auth::setStorage()</methodname>
                .
            </para>

            <example id="zend.auth.introduction.persistence.custom.example">

                <title>Usando una Clase de Almacenamiento Personalizada</title>

                <para>
                    Para poder utilizar una clase de almacenamiento
                    persistente de identidad
                    diferente a
                    <classname>Zend_Auth_Storage_Session</classname>
                    , el
                    desarrollador implementa
                    <classname>Zend_Auth_Storage_Interface</classname>
                    :
                    <programlisting language="php"><![CDATA[
class MyStorage implements Zend_Auth_Storage_Interface
{
    /**
     * Regresa true si y solo si el almacenamiento esta vacio
     *
     * @arroja Zend_Auth_Storage_Exception Si es imposible
     *                                     determinar si el almacenamiento
     *                                     esta vacio
     * @regresa boleano
     */
    public function isEmpty()
    {
        /**
         * @por hacer implementación
         */
    }

    /**
     * Regresa el contenido del almacenamiento
     *
     * El comportamiento es indefinido cuando el almacenamiento esta vacio
     *
     * @arroja Zend_Auth_Storage_Exception Si leer contenido de
     *                                     almacenamiento es imposible
     * @regresa mixto
     */
    public function read()
    {
        /**
         * @por hacer implementación
         */
    }

    /**
     * Escribe $contents al almacenamiento
     *
     * @parametros mezclado $contents
     * @arroja Zend_Auth_Storage_Exception Si escribir $contents al
     *                                     almacenamiento es imposible
     * @regresa boleano
     */
    public function write($contents)
    {
        /**
         * @por hacer implementación
         */
    }

    /**
     * limpia contenidos del almacenamiento
     *
     * @arroja Zend_Auth_Storage_Exception Si limpiar contenidos del
     *                                     almacenamiento es imposible
     * @regresa void
     */
    public function clear()
    {
        /**
         * @por hacer implementación
         */
    }
}
]]></programlisting>
                </para>

                <para>
                    A fin de poder usar esta clase de almacenamiento
                    personalizada,
                    <methodname>Zend_Auth::setStorage()</methodname>
                    es
                    invocada antes de intentar una petición de autenticación:
                </para>
                <programlisting language="php"><![CDATA[
// Instruye Zend_Auth para usar la clase de almacenamiento personalizada
Zend_Auth::getInstance()->setStorage(new MyStorage());

/**
 * @por hacer Configurar el adaptador de autenticación, $authAdapter
 */

// Autenticar, almacenando el resultado, y persistiendo la identidad
// si hay exito
$result = Zend_Auth::getInstance()->authenticate($authAdapter);
]]></programlisting>

            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.auth.introduction.using">

        <title>Uso</title>

        <para>
            Hay dos formas provistas de usar adaptadores
            <classname>Zend_Auth</classname>
            :

        </para>
        <orderedlist>
            <listitem>
                <para>
                    indirectamente, a través de
                    <methodname>Zend_Auth::authenticate()</methodname>
                </para>
            </listitem>
            <listitem>
                <para>
                    directamente, a través del metodo
                    <methodname>authenticate()</methodname>
                    del
                    adaptador
                </para>
            </listitem>
        </orderedlist>

        <para>
            El siguiente ejemplo ilustra como usar el adaptador
            <classname>:Zend_Auth</classname>
            : indirectamente, a través del
            uso de la clase
            <classname>Zend_Auth</classname>
            :
            <programlisting language="php"><![CDATA[
// Recibe una referencia a la instancia singleton de Zend_Auth
$auth = Zend_Auth::getInstance();

// Configura el adaptador de autenticación
$authAdapter = new MyAuthAdapter($username, $password);

// Intenta la autenticación, almacenando el resultado
$result = $auth->authenticate($authAdapter);

if (!$result->isValid()) {
    // Fautenticación fallida: imprime el por que
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Autenticación exitosa, la identidad ($username) es almacenada
    // en la sesión
    // $result->getIdentity() === $auth->getIdentity()
    // $result->getIdentity() === $username
}
]]></programlisting>
        </para>

        <para>Una vez que la autenticación ha sido intentada en una petición,
            como en el ejemplo
            anterior, es fácil verificar si existe una
            identidad autenticada exitosamente:
       </para>
        <programlisting language="php"><![CDATA[
$auth = Zend_Auth::getInstance();
if ($auth->hasIdentity()) {
    // Existe la identidad; obtenla
    $identity = $auth->getIdentity();
}
]]></programlisting>

        <para>
            Para remover una identidad del almacenamiento persistente,
            simplemente usa el metodo
            <methodname>clearIdentity()</methodname>
            method. Comunmente esto sería usado para implementar una operación
            "cerrar sesión" en la
            aplicación:
            <programlisting language="php"><![CDATA[
Zend_Auth::getInstance()->clearIdentity();
]]></programlisting>
        </para>

        <para>
            Cuando el uso automático de almacenamiento persistente es
            inapropiado para un caso en
            particular, el desarrollador podría
            simplemente omitir el uso de la clase
            <classname>Zend_Auth</classname>
            , usando una clase adaptadora
            directamente. El uso directo de una clase adaptadora
            implica
            configurar y preparar un objeto adaptador y despues llamar a su
            metodo
            <methodname>authenticate()</methodname>
            . Los detalles
            específicos del adaptador son discutidos en la documentación de cada
            adaptador. El siguiente ejemplo utiliza directamente
            <classname>MyAuthAdapter</classname>
            :
        </para>

        <programlisting language="php"><![CDATA[
// Configura el adaptador de autenticación
$authAdapter = new MyAuthAdapter($username, $password);

// Intenta la autenticación, almacenando el resultado
$result = $authAdapter->authenticate();

if (!$result->isValid()) {
    // Autenticación fallida, imprime el porque
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Autenticación exitosa
    // $result->getIdentity() === $username
}
]]></programlisting>

    </sect2>

</sect1>