repo_zf1/documentation/manual/en/module_specs/Zend_Auth_Adapter_Http.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.auth.adapter.http">

    <title>HTTP Authentication Adapter</title>

    <sect2 id="zend.auth.adapter.http.introduction">

        <title>Introduction</title>

        <para>
            <classname>Zend_Auth_Adapter_Http</classname> provides a mostly-compliant implementation
            of <ulink url="http://tools.ietf.org/html/rfc2617">RFC-2617</ulink>, <ulink
                url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">Basic</ulink> and
            <ulink url="http://en.wikipedia.org/wiki/Digest_access_authentication">Digest</ulink>
            HTTP Authentication. Digest authentication is a method of HTTP authentication that
            improves upon Basic authentication by providing a way to authenticate without having to
            transmit the password in clear text across the network.
        </para>

        <para>
            <emphasis>Major Features:</emphasis>
            <itemizedlist>
                <listitem>
                    <para>
                        Supports both Basic and Digest authentication.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Issues challenges in all supported schemes, so client can respond with any
                        scheme it supports.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Supports proxy authentication.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Includes support for authenticating against text files and provides an
                        interface for authenticating against other sources, such as databases.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            There are a few notable features of RFC-2617 that are not implemented yet:
            <itemizedlist>
                <listitem>
                    <para>
                        Nonce tracking, which would allow for "stale" support, and increased replay
                        attack protection.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Authentication with integrity checking, or "auth-int".
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Authentication-Info HTTP header.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

    </sect2>

    <sect2 id="zend.auth.adapter.design_overview">

        <title>Design Overview</title>

        <para>
            This adapter consists of two sub-components, the HTTP authentication class itself, and
            the so-called "Resolvers." The HTTP authentication class encapsulates the logic for
            carrying out both Basic and Digest authentication. It uses a Resolver to look up a
            client's identity in some data store (text file by default), and retrieve the
            credentials from the data store. The "resolved" credentials are then compared to the
            values submitted by the client to determine whether authentication is successful.
        </para>

    </sect2>

    <sect2 id="zend.auth.adapter.configuration_options">

        <title>Configuration Options</title>

        <para>
            The <classname>Zend_Auth_Adapter_Http</classname> class requires a configuration array
            passed to its constructor. There are several configuration options available, and some
            are required:
            <table id="zend.auth.adapter.configuration_options.table">
                <title>Configuration Options</title>
                <tgroup cols="3">
                    <thead>
                        <row>
                            <entry>Option Name</entry>
                            <entry>Required</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><emphasis>accept_schemes</emphasis></entry>
                            <entry>Yes</entry>
                            <entry>
                                Determines which authentication schemes the adapter will accept from
                                the client. Must be a space-separated list containing
                                <emphasis>'basic'</emphasis> and/or <emphasis>'digest'</emphasis>.
                            </entry>
                        </row>
                        <row>
                            <entry><emphasis>realm</emphasis></entry>
                            <entry>Yes</entry>
                            <entry>
                                Sets the authentication realm; usernames should be unique within a
                                given realm.
                            </entry>
                        </row>
                        <row>
                            <entry><emphasis>digest_domains</emphasis></entry>
                            <entry>
                                Yes, when <emphasis>'accept_schemes'</emphasis> contains
                                <emphasis>'digest'</emphasis>
                            </entry>
                            <entry>
                                Space-separated list of URIs for which the same authentication
                                information is valid. The URIs need not all point to the same
                                server.
                            </entry>
                        </row>
                        <row>
                            <entry><emphasis>nonce_timeout</emphasis></entry>
                            <entry>
                                Yes, when <emphasis>'accept_schemes'</emphasis> contains
                                <emphasis>'digest'</emphasis>
                            </entry>
                            <entry>
                                Sets the number of seconds for which the nonce is valid. See notes
                                below.
                            </entry>
                        </row>
                        <row>
                            <entry><emphasis>proxy_auth</emphasis></entry>
                            <entry>No</entry>
                            <entry>
                                Disabled by default. Enable to perform Proxy authentication, instead
                                of normal origin server authentication.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>

        <note>
            <para>
                The current implementation of the <emphasis>nonce_timeout</emphasis> has some
                interesting side effects. This setting is supposed to determine the valid lifetime
                of a given nonce, or effectively how long a client's authentication information is
                accepted. Currently, if it's set to 3600 (for example), it will cause the adapter to
                prompt the client for new credentials every hour, on the hour. This will be resolved
                in a future release, once nonce tracking and stale support are implemented.
            </para>
        </note>

    </sect2>

    <sect2 id="zend.auth.adapter.http.resolvers">

        <title>Resolvers</title>

        <para>
            The resolver's job is to take a username and realm, and return some kind of credential value. Basic
            authentication expects to receive the Base64 encoded version of the user's password. Digest authentication
            expects to receive a hash of the user's username, the realm, and their password (each separated by colons).
            Currently, the only supported hash algorithm is MD5.
        </para>

        <para>
            <classname>Zend_Auth_Adapter_Http</classname> relies on objects implementing
            <classname>Zend_Auth_Adapter_Http_Resolver_Interface</classname>. A text file resolver class is included with this
            adapter, but any other kind of resolver can be created simply by implementing the resolver interface.
        </para>

        <sect3 id="zend.auth.adapter.http.resolvers.file">

            <title>File Resolver</title>

            <para>
                The file resolver is a very simple class. It has a single property specifying a filename, which can also
                be passed to the constructor. Its <methodname>resolve()</methodname> method walks through the text file, searching
                for a line with a matching username and realm. The text file format similar to Apache htpasswd files:
                <programlisting language="txt"><![CDATA[
<username>:<realm>:<credentials>\n
]]></programlisting>
                Each line consists of three fields - username, realm, and credentials - each separated by a colon. The
                credentials field is opaque to the file resolver; it simply returns that value as-is to the caller.
                Therefore, this same file format serves both Basic and Digest authentication. In Basic authentication,
                the credentials field should be written in clear text. In Digest authentication, it
                should be the MD5 hash described above.
            </para>

            <para>
                There are two equally easy ways to create a File resolver:
                <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
]]></programlisting>
                or
                <programlisting language="php"><![CDATA[
$path     = 'files/passwd.txt';
$resolver = new Zend_Auth_Adapter_Http_Resolver_File();
$resolver->setFile($path);
]]></programlisting>
                If the given path is empty or not readable, an exception is thrown.
            </para>

        </sect3>

    </sect2>

    <sect2 id="zend.auth.adapter.http.basic_usage">

        <title>Basic Usage</title>

        <para>
            First, set up an array with the required configuration values:
            <programlisting language="php"><![CDATA[
$config = array(
    'accept_schemes' => 'basic digest',
    'realm'          => 'My Web Site',
    'digest_domains' => '/members_only /my_account',
    'nonce_timeout'  => 3600,
);
]]></programlisting>
            This array will cause the adapter to accept either Basic or Digest authentication, and will require
            authenticated access to all the areas of the site under <filename>/members_only</filename> and
            <filename>/my_account</filename>. The realm value is usually displayed by the browser in the password dialog box.
            The <emphasis>nonce_timeout</emphasis>, of course, behaves as described above.
        </para>

        <para>
            Next, create the Zend_Auth_Adapter_Http object:
            <programlisting language="php"><![CDATA[
$adapter = new Zend_Auth_Adapter_Http($config);
]]></programlisting>
        </para>

        <para>
            Since we're supporting both Basic and Digest authentication, we need two different resolver objects. Note
            that this could just as easily be two different classes:
            <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>

        <para>
            Finally, we perform the authentication. The adapter needs a reference to both the Request and Response
            objects in order to do its job:
            <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>
        </para>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->