documentation/manual/es/module_specs/Zend_Auth_Adapter_Http.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2     <!-- EN-Revision: 20763 -->
   3     <!-- Reviewed: no -->
   4 <sect1 id="zend.auth.adapter.http">
   5
   6     <title>Adaptador de Autenticación HTTP</title>
   7
   8     <sect2 id="zend.auth.adapter.http.introduction">
   9
  10         <title>Introducción</title>
  11
  12         <para>
  13             <classname>Zend_Auth_Adapter_Http</classname>
  14             proporciona una
  15             implementación compatible con
  16             <ulink url="http://tools.ietf.org/html/rfc2617">RFC-2617</ulink>
  17             ,
  18             <ulink url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">Basic</ulink>
  19             y
  20             <ulink url="http://en.wikipedia.org/wiki/Digest_access_authentication">Digest</ulink>
  21             Autenticación
  22             <acronym>HTTP</acronym>
  23             . La
  24             autenticación "Digest" es un método de autenticación
  25             <acronym>HTTP</acronym>
  26             que mejora la autenticación básica
  27             proporcionando una manera de autenticar sin tener que
  28             transmitir la
  29             contraseña de manera clara en un texto a través de la red.
  30         </para>
  31
  32         <para>
  33             <emphasis role="strong">Características Principales:</emphasis>
  34         </para>
  35
  36         <itemizedlist>
  37             <listitem>
  38                 <para>Soporta tanto Autenticación "Digest" como Básica.</para>
  39             </listitem>
  40             <listitem>
  41                 <para>Establece retos en todos los proyectos soportados, por lo
  42                     que el cliente puede
  43                     responder con cualquier proyecto que
  44                     soporte.</para>
  45             </listitem>
  46             <listitem>
  47                 <para>Soporta autenticación proxy.</para>
  48             </listitem>
  49             <listitem>
  50                 <para>Incluye soporte para la autenticación contra archivos de
  51                     texto y proporciona
  52                     una interfaz para autenticar contra
  53                     otras fuentes, tales como bases de datos.</para>
  54             </listitem>
  55         </itemizedlist>
  56
  57         <para>
  58             Hay algunas características notables del
  59             <acronym>RFC-2617</acronym>
  60             no implementadas todavía:
  61         </para>
  62         <itemizedlist>
  63             <listitem>
  64                 <para>Seguimiento "nonce", que permitiría un gran apoyo, y un
  65                     aumento de la
  66                     protección de repetidos ataques.</para>
  67             </listitem>
  68             <listitem>
  69                 <para>Autenticación con comprobación de integridad, o
  70                     "auth-int".</para>
  71             </listitem>
  72             <listitem>
  73                 <para>
  74                     Cabecera de información de la autenticación
  75                     <acronym>HTTP</acronym>
  76                     .
  77                 </para>
  78             </listitem>
  79         </itemizedlist>
  80
  81     </sect2>
  82
  83     <sect2 id="zend.auth.adapter.design_overview">
  84
  85         <title>Descripción del diseño</title>
  86
  87         <para>
  88             Este adaptador consiste en dos sub-componentes, la propia clase
  89             autenticación
  90             <acronym>HTTP</acronym>
  91             , y el llamado "Resolvers". La
  92             clase autenticación
  93             <acronym>HTTP</acronym>
  94             encapsula la lógica para
  95             llevar a cabo tanto la autenticación basica y la "Digest".
  96             Utiliza
  97             un Resolver para buscar la identidad de un cliente en los datos
  98             almacenados (por
  99             defecto, archivos de texto), y recuperar las
 100             credenciales de los datos almacenados. Las
 101             credenciales del
 102             "Resolved" se comparan con los valores presentados por el cliente
 103             para
 104             determinar si la autenticación es satisfactoria.
 105         </para>
 106
 107     </sect2>
 108
 109     <sect2 id="zend.auth.adapter.configuration_options">
 110
 111         <title>Opciones de Configuración</title>
 112
 113         <para>
 114             La clase
 115             <classname>Zend_Auth_Adapter_Http</classname>
 116             requiere
 117             un array configurado que pasará a su constructor. Hay varias
 118             opciones de
 119             configuración disponibles, y algunas son obligatorias:
 120         </para>
 121         <table id="zend.auth.adapter.configuration_options.table">
 122             <title>Opciones de Configuración</title>
 123             <tgroup cols="3">
 124                 <thead>
 125                     <row>
 126                         <entry>Nombre de Opción</entry>
 127                         <entry>Obligatoria</entry>
 128                         <entry>Descripción</entry>
 129                     </row>
 130                 </thead>
 131                 <tbody>
 132                     <row>
 133                         <entry>
 134                             <emphasis>
 135                                 <property>accept_schemes</property>
 136                             </emphasis>
 137                         </entry>
 138                         <entry>Si</entry>
 139                         <entry>
 140                             Determina que tareas de autenticación acepta el
 141                             adaptador del cliente.
 142                             Debe ser una lista separada
 143                             por espacios que contengo
 144                             <emphasis>'basic'</emphasis>
 145                             y/o
 146                             <emphasis>'digest'</emphasis>
 147                             .
 148                         </entry>
 149                     </row>
 150                     <row>
 151                         <entry>
 152                             <emphasis>
 153                                 <property>realm</property>
 154                             </emphasis>
 155                         </entry>
 156                         <entry>Si</entry>
 157                         <entry> Establece el realm de autenticación; usernames
 158                             debe ser único dentro
 159                             de un determinado realm.
 160                         </entry>
 161                     </row>
 162                     <row>
 163                         <entry>
 164                             <emphasis>
 165                                 <property>digest_domains</property>
 166                             </emphasis>
 167                         </entry>
 168                         <entry>
 169                             Si, cuando
 170                             <property>accept_schemes</property>
 171                             contiene
 172                             <emphasis>'digest'</emphasis>
 173                         </entry>
 174                         <entry>
 175                             Lista de
 176                             <acronym>URI</acronym>
 177                             s separadas por
 178                             espacios para las cuales la misma información de
 179                             autenticación es válida. No es necesario que todas
 180                             las
 181                             <acronym>URI</acronym>
 182                             s apunten al mismo
 183                             oservidor.
 184                         </entry>
 185                     </row>
 186                     <row>
 187                         <entry>
 188                             <emphasis>
 189                                 <property>nonce_timeout</property>
 190                             </emphasis>
 191                         </entry>
 192                         <entry>
 193                             Si, cuando
 194                             <property>accept_schemes</property>
 195                             contiene
 196                             <emphasis>'digest'</emphasis>
 197                         </entry>
 198                         <entry> Establece el número de segundos para los cuales
 199                             el "nonce" es válido.
 200                             Ver notas de abajo. </entry>
 201                     </row>
 202                     <row>
 203                         <entry>
 204                             <emphasis>
 205                                 <property>proxy_auth</property>
 206                             </emphasis>
 207                         </entry>
 208                         <entry>No</entry>
 209                         <entry> Deshabilitado por defecto. Permite llevar a cabo
 210                             la autenticación del
 211                             Proxy, en lugar de la
 212                             autenticación normal del servidor. </entry>
 213                     </row>
 214                 </tbody>
 215             </tgroup>
 216         </table>
 217
 218         <note>
 219             <para>
 220                 La implementación actual del
 221                 <property>nonce_timeout</property>
 222                 tiene algunos efectos
 223                 colaterales interesantes. Este ajuste es supuesto para
 224                 determinar la vida util válida para un determinado "nonce", o de
 225                 manera efectiva el
 226                 tiempo que una información de autenticación
 227                 del cliente es aceptada. Actualmente, si
 228                 se establece en 3600
 229                 (por ejemplo), hará que el adaptador indique al cliente las
 230                 nuevas credenciales cada hora, a la hora en punto.
 231             </para>
 232         </note>
 233
 234     </sect2>
 235
 236     <sect2 id="zend.auth.adapter.http.resolvers">
 237
 238         <title>Resolvers</title>
 239
 240         <para>
 241             El trabajo del "Resolver" es tener un username y un realm, y
 242             devolver algún valor de tipo
 243             credencial. La autenticación básica
 244             espera recibir la versión codificada en Base64 de la
 245             contraseña del
 246             usuario. La autenticación "Digest" espera recibir un hash del
 247             username del
 248             usuario, un realm, y su contraseña (separados por
 249             coma). Actualmente, sólo se admite el
 250             algoritmo de hash
 251             <acronym>MD5</acronym>
 252             .
 253         </para>
 254
 255         <para>
 256             <classname>Zend_Auth_Adapter_Http</classname>
 257             se basa en la
 258             implementación de objetos
 259             <classname>Zend_Auth_Adapter_Http_Resolver_Interface</classname>
 260             .
 261             Un archivo de texto de la clase "Resolve" se incluye con este
 262             adaptador, pero cualquier
 263             otro tipo de "resolver" puede ser creado
 264             simplemente implementando la interfaz del
 265             "resolver".
 266         </para>
 267
 268         <sect3 id="zend.auth.adapter.http.resolvers.file">
 269             <title>Archivo Resolver</title>
 270             <para>
 271                 El archivo "resolver" es una clase muy simple. Tiene una
 272                 única propiedad que
 273                 especifique un nombre de archivo, que
 274                 también puede ser pasado al constructor. Su
 275                 método
 276                 <methodname>resolve()</methodname>
 277                 recorre el archivo de
 278                 texto, buscando una linea con el correspondiente username y
 279                 realm. El formato del archivo de texto es similar a los archivos
 280                 htpasswd de Apache:
 281             </para>
 282             <programlisting language="txt"><![CDATA[
 283 <username>:<realm>:<credentials>\n
 284 ]]></programlisting>
 285             <para>
 286                 Cada linea consta de tres campos -username, realm, y
 287                 credenciales - cada uno
 288                 separados por dos puntos. El campo
 289                 credenciales es opaco al archivo "resolver";
 290                 simplemente
 291                 devuelve el valor tal como és al llamador. Por lo tanto, este
 292                 formato de
 293                 archivo sirve tanto de autenticación básica como
 294                 "Digest". En la autenticación
 295                 básica, el campo credenciales debe
 296                 ser escrito en texto claro. En la autenticación
 297                 "Digest",
 298                 debería ser en hash
 299                 <acronym>MD5</acronym>
 300                 descrito
 301                 anteriormente.
 302             </para>
 303
 304             <para>Hay dos formas igualmente fácil de crear un archivo de
 305                 "resolver":</para>
 306             <programlisting language="php"><![CDATA[
 307 $path     = 'files/passwd.txt';
 308 $resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
 309 ]]></programlisting>
 310             <para>o</para>
 311             <programlisting language="php"><![CDATA[
 312 $path     = 'files/passwd.txt';
 313 $resolver = new Zend_Auth_Adapter_Http_Resolver_File();
 314 $resolver->setFile($path);
 315 ]]></programlisting>
 316             <para>Si la ruta está vacía o no se puede leer, se lanza una
 317                 excepción.</para>
 318         </sect3>
 319
 320     </sect2>
 321
 322     <sect2 id="zend.auth.adapter.http.basic_usage">
 323
 324         <title>Uso Básico</title>
 325
 326         <para>En primer lugar, establecemos un array con los valores de
 327             configuración obligatorios:</para>
 328         <programlisting language="php"><![CDATA[
 329 $config = array(
 330     'accept_schemes' => 'basic digest',
 331     'realm'          => 'My Web Site',
 332     'digest_domains' => '/members_only /my_account',
 333     'nonce_timeout'  => 3600,
 334 );
 335 ]]></programlisting>
 336         <para>
 337             Este array hará que el adaptador acepte la autenticación básica o
 338             "Digest", y requerirá
 339             un acceso autenticado a todas las áreas del
 340             sitio en
 341             <filename>/members_only</filename>
 342             y
 343             <filename>/my_account</filename>
 344             . El valor realm es normalmente
 345             mostrado por el navegador en el cuadro de dialogo
 346             contraseña. El
 347             <property>nonce_timeout</property>
 348             , por supuesto, se comporta
 349             como se ha descrito anteriormente.
 350         </para>
 351
 352         <para>A continuación, creamos el objeto Zend_Auth_Adapter_Http:</para>
 353         <programlisting language="php"><![CDATA[
 354 $adapter = new Zend_Auth_Adapter_Http($config);
 355 ]]></programlisting>
 356
 357         <para>Ya que estamos soportando tanto la autenticación básica como la
 358             "Digest", necesitamos
 359             dos objetos diferentes resolver. Tenga en
 360             cuenta que esto podría ser facilmente dos
 361             clases diferentes:</para>
 362         <programlisting language="php"><![CDATA[
 363 $basicResolver = new Zend_Auth_Adapter_Http_Resolver_File();
 364 $basicResolver->setFile('files/basicPasswd.txt');
 365
 366 $digestResolver = new Zend_Auth_Adapter_Http_Resolver_File();
 367 $digestResolver->setFile('files/digestPasswd.txt');
 368
 369 $adapter->setBasicResolver($basicResolver);
 370 $adapter->setDigestResolver($digestResolver);
 371 ]]></programlisting>
 372
 373         <para>Por último, realizamos la autenticación. El adaptador necesita
 374             una referencia a ambos
 375             objetos solicitud y respuesta para hacer su
 376             trabajo:</para>
 377         <programlisting language="php"><![CDATA[
 378 assert($request instanceof Zend_Controller_Request_Http);
 379 assert($response instanceof Zend_Controller_Response_Http);
 380
 381 $adapter->setRequest($request);
 382 $adapter->setResponse($response);
 383
 384 $result = $adapter->authenticate();
 385 if (!$result->isValid()) {
 386     // Bad userame/password, or canceled password prompt
 387 }
 388 ]]></programlisting>
 389
 390     </sect2>
 391
 392 </sect1>