Introduction

Zend_Auth provides an API for authentication and includes concrete authentication adapters for common use case scenarios.

Zend_Auth is concerned only with authentication and not with authorization. Authentication is loosely defined as determining whether an entity actually is what it purports to be (i.e., identification), based on some set of credentials. Authorization, the process of deciding whether to allow an entity access to, or to perform operations upon, other entities is outside the scope of Zend_Auth. For more information about authorization and access control with Zend Framework, please see Zend_Acl.

Note: The Zend_Auth class implements the Singleton pattern - only one instance of the class is available - through its static getInstance() method. This means that using the new operator and the clone keyword will not work with the Zend_Auth class; use Zend_Auth::getInstance() instead.

Adapters

A Zend_Auth adapter is used to authenticate against a particular type of authentication service, such as LDAP, RDBMS, or file-based storage. Different adapters are likely to have vastly different options and behaviors, but some basic things are common among authentication adapters. For example, accepting authentication credentials (including a purported identity), performing queries against the authentication service, and returning results are common to Zend_Auth adapters.

Each Zend_Auth adapter class implements Zend_Auth_Adapter_Interface. This interface defines one method, authenticate(), that an adapter class must implement for performing an authentication query. Each adapter class must be prepared prior to calling authenticate(). Such adapter preparation includes setting up credentials (e.g., username and password) and defining values for adapter-specific configuration options, such as database connection settings for a database table adapter.

The following is an example authentication adapter that requires a username and password to be set for authentication. Other details, such as how the authentication service is queried, have been omitted for brevity:

span style="color: #808080; font-style: italic;">/**
     * Sets username and password for authentication
     *
     * @return void
     */// ...
    }
 
    /**
     * Performs an authentication attempt
     *
     * @throws Zend_Auth_Adapter_Exception If authentication cannot
     *                                     be performed
     * @return Zend_Auth_Result
     */// ...
    }
}

As indicated in its docblock, authenticate() must return an instance of Zend_Auth_Result (or of a class derived from Zend_Auth_Result). If for some reason performing an authentication query is impossible, authenticate() should throw an exception that derives from Zend_Auth_Adapter_Exception.

Results

Zend_Auth adapters return an instance of Zend_Auth_Result with authenticate() in order to represent the results of an authentication attempt. Adapters populate the Zend_Auth_Result object upon construction, so that the following four methods provide a basic set of user-facing operations that are common to the results of Zend_Auth adapters:

isValid() - returns TRUE if and only if the result represents a successful authentication attempt
getCode() - returns a Zend_Auth_Result constant identifier for determining the type of authentication failure or whether success has occurred. This may be used in situations where the developer wishes to distinguish among several authentication result types. This allows developers to maintain detailed authentication result statistics, for example. Another use of this feature is to provide specific, customized messages to users for usability reasons, though developers are encouraged to consider the risks of providing such detailed reasons to users, instead of a general authentication failure message. For more information, see the notes below.
getIdentity() - returns the identity of the authentication attempt
getMessages() - returns an array of messages regarding a failed authentication attempt

A developer may wish to branch based on the type of authentication result in order to perform more specific operations. Some operations developers might find useful are locking accounts after too many unsuccessful password attempts, flagging an IP address after too many nonexistent identities are attempted, and providing specific, customized authentication result messages to the user. The following result codes are available:

The following example illustrates how a developer may branch on the result code:

// inside of AuthController / loginAction
/** do stuff for nonexistent identity **//** do stuff for invalid credential **//** do stuff for successful authentication **//** do stuff for other failure **/

Identity Persistence

Authenticating a request that includes authentication credentials is useful per se, but it is also important to support maintaining the authenticated identity without having to present the authentication credentials with each request.

HTTP is a stateless protocol, however, and techniques such as cookies and sessions have been developed in order to facilitate maintaining state across multiple requests in server-side web applications.

Default Persistence in the PHP Session

By default, Zend_Auth provides persistent storage of the identity from a successful authentication attempt using the PHP session. Upon a successful authentication attempt, Zend_Auth::authenticate() stores the identity from the authentication result into persistent storage. Unless configured otherwise, Zend_Auth uses a storage class named Zend_Auth_Storage_Session, which, in turn, uses Zend_Session. A custom class may instead be used by providing an object that implements Zend_Auth_Storage_Interface to Zend_Auth::setStorage().

Note: If automatic persistent storage of the identity is not appropriate for a particular use case, then developers may forgot using the Zend_Auth class altogether, instead using an adapter class directly.

Example #1 Modifying the Session Namespace

Zend_Auth_Storage_Session uses a session namespace of 'Zend_Auth'. This namespace may be overridden by passing a different value to the constructor of Zend_Auth_Storage_Session, and this value is internally passed along to the constructor of Zend_Session_Namespace. This should occur before authentication is attempted, since Zend_Auth::authenticate() performs the automatic storage of the identity.

// Save a reference to the Singleton instance of Zend_Auth
// Use 'someNamespace' instead of 'Zend_Auth'
'someNamespace'));
 
/**
 * @todo Set up the auth adapter, $authAdapter
 */
 
// Authenticate, saving the result, and persisting the identity on
// success
$result = $auth->authenticate($authAdapter);

Implementing Customized Storage

Sometimes developers may need to use a different identity storage mechanism than that provided by Zend_Auth_Storage_Session. For such cases developers may simply implement Zend_Auth_Storage_Interface and supply an instance of the class to Zend_Auth::setStorage().

Example #2 Using a Custom Storage Class

In order to use an identity persistence storage class other than Zend_Auth_Storage_Session, a developer implements Zend_Auth_Storage_Interface:

span style="color: #808080; font-style: italic;">/**
     * Returns true if and only if storage is empty
     *
     * @throws Zend_Auth_Storage_Exception If it is impossible to
     *                                     determine whether storage
     *                                     is empty
     * @return boolean
     *//**
         * @todo implementation
         */
    }
 
    /**
     * Returns the contents of storage
     *
     * Behavior is undefined when storage is empty.
     *
     * @throws Zend_Auth_Storage_Exception If reading contents from
     *                                     storage is impossible
     * @return mixed
     *//**
         * @todo implementation
         */
    }
 
    /**
     * Writes $contents to storage
     *
     * @param  mixed $contents
     * @throws Zend_Auth_Storage_Exception If writing $contents to
     *                                     storage is impossible
     * @return void
     *//**
         * @todo implementation
         */
    }
 
    /**
     * Clears contents from storage
     *
     * @throws Zend_Auth_Storage_Exception If clearing contents from
     *                                     storage is impossible
     * @return void
     *//**
         * @todo implementation
         */
    }
}

In order to use this custom storage class, Zend_Auth::setStorage() is invoked before an authentication query is attempted:

// Instruct Zend_Auth to use the custom storage class
/**
 * @todo Set up the auth adapter, $authAdapter
 */
 
// Authenticate, saving the result, and persisting the identity on
// success

Usage

There are two provided ways to use Zend_Auth adapters:

indirectly, through Zend_Auth::authenticate()
directly, through the adapter's authenticate() method

The following example illustrates how to use a Zend_Auth adapter indirectly, through the use of the Zend_Auth class:

// Get a reference to the singleton instance of Zend_Auth
// Set up the authentication adapter
// Attempt authentication, saving the result
// Authentication failed; print the reasons why
"$message\n"// Authentication succeeded; the identity ($username) is stored
    // in the session
    // $result->getIdentity() === $auth->getIdentity()
    // $result->getIdentity() === $username
}

Once authentication has been attempted in a request, as in the above example, it is a simple matter to check whether a successfully authenticated identity exists:

span style="color: #808080; font-style: italic;">// Identity exists; get it
    $identity = $auth->getIdentity();
}

To remove an identity from persistent storage, simply use the clearIdentity() method. This typically would be used for implementing an application "logout" operation:

When the automatic use of persistent storage is inappropriate for a particular use case, a developer may simply bypass the use of the Zend_Auth class, using an adapter class directly. Direct use of an adapter class involves configuring and preparing an adapter object and then calling its authenticate() method. Adapter-specific details are discussed in the documentation for each adapter. The following example directly utilizes MyAuthAdapter:

// Set up the authentication adapter
// Attempt authentication, saving the result
// Authentication failed; print the reasons why
"$message\n"// Authentication succeeded
    // $result->getIdentity() === $username
}