documentation/manual/en/module_specs/Zend_Auth_Adapter_Http.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.auth.adapter.http">
   4     <title>HTTP Authentication Adapter</title>
   5
   6     <sect2 id="zend.auth.adapter.http.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Auth_Adapter_Http</classname> provides a mostly-compliant
  11             implementation of <ulink url="http://tools.ietf.org/html/rfc2617">RFC-2617</ulink>,
  12             <ulink url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">Basic</ulink>
  13             and <ulink
  14                 url="http://en.wikipedia.org/wiki/Digest_access_authentication">Digest</ulink>
  15             <acronym>HTTP</acronym> Authentication. Digest authentication is a method of
  16             <acronym>HTTP</acronym> authentication that improves upon Basic authentication by
  17             providing a way to authenticate without having to transmit the password in clear text
  18             across the network.
  19         </para>
  20
  21         <para>
  22             <emphasis>Major Features:</emphasis>
  23         </para>
  24
  25         <itemizedlist>
  26             <listitem>
  27                 <para>
  28                     Supports both Basic and Digest authentication.
  29                 </para>
  30             </listitem>
  31
  32             <listitem>
  33                 <para>
  34                     Issues challenges in all supported schemes, so client can respond with any
  35                     scheme it supports.
  36                 </para>
  37             </listitem>
  38
  39             <listitem>
  40                 <para>
  41                     Supports proxy authentication.
  42                 </para>
  43             </listitem>
  44
  45             <listitem>
  46                 <para>
  47                     Includes support for authenticating against text files and provides an
  48                     interface for authenticating against other sources, such as databases.
  49                 </para>
  50             </listitem>
  51         </itemizedlist>
  52
  53         <para>
  54             There are a few notable features of <acronym>RFC-2617</acronym> that are not
  55             implemented yet:
  56         </para>
  57
  58         <itemizedlist>
  59             <listitem>
  60                 <para>
  61                     Nonce tracking, which would allow for "stale" support, and increased replay
  62                     attack protection.
  63                 </para>
  64             </listitem>
  65
  66             <listitem>
  67                 <para>
  68                     Authentication with integrity checking, or "auth-int".
  69                 </para>
  70             </listitem>
  71
  72             <listitem>
  73                 <para>
  74                     Authentication-Info <acronym>HTTP</acronym> header.
  75                 </para>
  76             </listitem>
  77         </itemizedlist>
  78     </sect2>
  79
  80     <sect2 id="zend.auth.adapter.design_overview">
  81         <title>Design Overview</title>
  82
  83         <para>
  84             This adapter consists of two sub-components, the <acronym>HTTP</acronym> authentication
  85             class itself, and the so-called "Resolvers." The <acronym>HTTP</acronym> authentication
  86             class encapsulates the logic for carrying out both Basic and Digest authentication. It
  87             uses a Resolver to look up a client's identity in some data store (text file by
  88             default), and retrieve the credentials from the data store. The "resolved" credentials
  89             are then compared to the values submitted by the client to determine whether
  90             authentication is successful.
  91         </para>
  92     </sect2>
  93
  94     <sect2 id="zend.auth.adapter.configuration_options">
  95         <title>Configuration Options</title>
  96
  97         <para>
  98             The <classname>Zend_Auth_Adapter_Http</classname> class requires a configuration array
  99             passed to its constructor. There are several configuration options available, and some
 100             are required:
 101         </para>
 102
 103         <table id="zend.auth.adapter.configuration_options.table">
 104             <title>Configuration Options</title>
 105
 106             <tgroup cols="3">
 107                 <thead>
 108                     <row>
 109                         <entry>Option Name</entry>
 110                         <entry>Required</entry>
 111                         <entry>Description</entry>
 112                     </row>
 113                 </thead>
 114
 115                 <tbody>
 116                     <row>
 117                         <entry><emphasis><property>accept_schemes</property></emphasis></entry>
 118                         <entry>Yes</entry>
 119
 120                         <entry>
 121                             Determines which authentication schemes the adapter will accept from
 122                             the client. Must be a space-separated list containing
 123                             <emphasis>'basic'</emphasis> and/or <emphasis>'digest'</emphasis>.
 124                         </entry>
 125                     </row>
 126
 127                     <row>
 128                         <entry><emphasis><property>realm</property></emphasis></entry>
 129                         <entry>Yes</entry>
 130
 131                         <entry>
 132                             Sets the authentication realm; usernames should be unique within a
 133                             given realm.
 134                         </entry>
 135                     </row>
 136
 137                     <row>
 138                         <entry><emphasis><property>digest_domains</property></emphasis></entry>
 139
 140                         <entry>
 141                             Yes, when <property>accept_schemes</property> contains
 142                             <emphasis>digest</emphasis>
 143                         </entry>
 144
 145                         <entry>
 146                             Space-separated list of <acronym>URI</acronym>s for which the same
 147                             authentication information is valid. The <acronym>URI</acronym>s need
 148                             not all point to the same server.
 149                         </entry>
 150                     </row>
 151
 152                     <row>
 153                         <entry><emphasis><property>nonce_timeout</property></emphasis></entry>
 154
 155                         <entry>
 156                             Yes, when <property>accept_schemes</property> contains
 157                             <emphasis>digest</emphasis>
 158                         </entry>
 159
 160                         <entry>
 161                             Sets the number of seconds for which the nonce is valid. See notes
 162                             below.
 163                         </entry>
 164                     </row>
 165
 166                     <row>
 167                         <entry><emphasis><property>proxy_auth</property></emphasis></entry>
 168                         <entry>No</entry>
 169
 170                         <entry>
 171                             Disabled by default. Enable to perform Proxy authentication, instead
 172                             of normal origin server authentication.
 173                         </entry>
 174                     </row>
 175                 </tbody>
 176             </tgroup>
 177         </table>
 178
 179         <note>
 180             <para>
 181                 The current implementation of the <property>nonce_timeout</property> has some
 182                 interesting side effects. This setting is supposed to determine the valid lifetime
 183                 of a given nonce, or effectively how long a client's authentication information is
 184                 accepted. Currently, if it's set to 3600 (for example), it will cause the adapter
 185                 to prompt the client for new credentials every hour, on the hour. This will be
 186                 resolved in a future release, once nonce tracking and stale support are
 187                 implemented.
 188             </para>
 189         </note>
 190     </sect2>
 191
 192     <sect2 id="zend.auth.adapter.http.resolvers">
 193         <title>Resolvers</title>
 194
 195         <para>
 196             The resolver's job is to take a username and realm, and return some kind of credential
 197             value. Basic authentication expects to receive the Base64 encoded version of the user's
 198             password. Digest authentication expects to receive a hash of the user's username, the
 199             realm, and their password (each separated by colons). Currently, the only supported
 200             hash algorithm is <acronym>MD5</acronym>.
 201         </para>
 202
 203         <para>
 204             <classname>Zend_Auth_Adapter_Http</classname> relies on objects implementing
 205             <classname>Zend_Auth_Adapter_Http_Resolver_Interface</classname>. A text file resolver
 206             class is included with this adapter, but any other kind of resolver can be created
 207             simply by implementing the resolver interface.
 208         </para>
 209
 210         <sect3 id="zend.auth.adapter.http.resolvers.file">
 211             <title>File Resolver</title>
 212
 213             <para>
 214                 The file resolver is a very simple class. It has a single property specifying a
 215                 filename, which can also be passed to the constructor. Its
 216                 <methodname>resolve()</methodname> method walks through the text file, searching
 217                 for a line with a matching username and realm. The text file format similar to
 218                 Apache htpasswd files:
 219             </para>
 220
 221             <programlisting language="txt"><![CDATA[
 222 <username>:<realm>:<credentials>\n
 223 ]]></programlisting>
 224
 225             <para>
 226                 Each line consists of three fields - username, realm, and credentials - each
 227                 separated by a colon. The credentials field is opaque to the file resolver; it
 228                 simply returns that value as-is to the caller. Therefore, this same file format
 229                 serves both Basic and Digest authentication. In Basic authentication, the
 230                 credentials field should be written in clear text. In Digest authentication, it
 231                 should be the <acronym>MD5</acronym> hash described above.
 232             </para>
 233
 234             <para>
 235                 There are two equally easy ways to create a File resolver:
 236             </para>
 237
 238             <programlisting language="php"><![CDATA[
 239 $path     = 'files/passwd.txt';
 240 $resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
 241 ]]></programlisting>
 242
 243             <para>
 244                 or
 245             </para>
 246
 247             <programlisting language="php"><![CDATA[
 248 $path     = 'files/passwd.txt';
 249 $resolver = new Zend_Auth_Adapter_Http_Resolver_File();
 250 $resolver->setFile($path);
 251 ]]></programlisting>
 252
 253             <para>
 254                 If the given path is empty or not readable, an exception is thrown.
 255             </para>
 256         </sect3>
 257     </sect2>
 258
 259     <sect2 id="zend.auth.adapter.http.basic_usage">
 260         <title>Basic Usage</title>
 261
 262         <para>
 263             First, set up an array with the required configuration values:
 264         </para>
 265
 266         <programlisting language="php"><![CDATA[
 267 $config = array(
 268     'accept_schemes' => 'basic digest',
 269     'realm'          => 'My Web Site',
 270     'digest_domains' => '/members_only /my_account',
 271     'nonce_timeout'  => 3600,
 272 );
 273 ]]></programlisting>
 274
 275         <para>
 276             This array will cause the adapter to accept either Basic or Digest authentication, and
 277             will require authenticated access to all the areas of the site under
 278             <filename>/members_only</filename> and <filename>/my_account</filename>. The realm
 279             value is usually displayed by the browser in the password dialog box. The
 280             <property>nonce_timeout</property>, of course, behaves as described above.
 281         </para>
 282
 283         <para>
 284             Next, create the <classname>Zend_Auth_Adapter_Http</classname> object:
 285         </para>
 286
 287         <programlisting language="php"><![CDATA[
 288 $adapter = new Zend_Auth_Adapter_Http($config);
 289 ]]></programlisting>
 290
 291         <para>
 292             Since we're supporting both Basic and Digest authentication, we need two different
 293             resolver objects. Note that this could just as easily be two different classes:
 294         </para>
 295
 296         <programlisting language="php"><![CDATA[
 297 $basicResolver = new Zend_Auth_Adapter_Http_Resolver_File();
 298 $basicResolver->setFile('files/basicPasswd.txt');
 299
 300 $digestResolver = new Zend_Auth_Adapter_Http_Resolver_File();
 301 $digestResolver->setFile('files/digestPasswd.txt');
 302
 303 $adapter->setBasicResolver($basicResolver);
 304 $adapter->setDigestResolver($digestResolver);
 305 ]]></programlisting>
 306
 307         <para>
 308             Finally, we perform the authentication. The adapter needs a reference to both the
 309             Request and Response objects in order to do its job:
 310         </para>
 311
 312         <programlisting language="php"><![CDATA[
 313 assert($request instanceof Zend_Controller_Request_Http);
 314 assert($response instanceof Zend_Controller_Response_Http);
 315
 316 $adapter->setRequest($request);
 317 $adapter->setResponse($response);
 318
 319 $result = $adapter->authenticate();
 320 if (!$result->isValid()) {
 321     // Bad userame/password, or canceled password prompt
 322 }
 323 ]]></programlisting>
 324     </sect2>
 325 </sect1>
 326 <!--
 327 vim:se ts=4 sw=4 et:
 328 -->