Table of Contents
Zend_Auth provides an API for authentication and includes concrete authentication adapters for common use case scenarios.
![]() |
Note |
---|---|
Zend_Auth currently includes a digest authentication adapter as a simple proof-of-concept for the design. Additional adapters are planned for development. Interested in using a particular adapter? Your voting for an adapter and contributions are most welcome! |
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 out of scope with respect to Zend_Auth. For more information about authorization and access control with the Zend Framework, please see Zend_Acl.
Each Zend_Auth authentication adapter extends the abstract class Zend_Auth_Adapter
.
This abstract class provides two methods, staticAuthenticate()
and
authenticate()
, that the extending adapter class may implement for authentication
purposes. Each of these methods accepts a single array parameter, $options
, which
contains the options specific to an authentication attempt for the particular adapter (e.g.,
login credentials such as a username and password combination):
<?php require_once 'Zend/Auth/Adapter.php'; class MyAuthAdapter extends Zend_Auth_Adapter { public function authenticate($options) { // ... } }
Both staticAuthenticate()
and authenticate()
must return an instance of
a class that implements Zend_Auth_Token_Interface
unless they throw an exception that
derives from Zend_Auth_Adapter_Exception
.
In Zend_Auth, a token is used to represent the results of an authentication attempt. A token from one authentication adapter could contain very different information than a token from another adapter. Certainly applications will also have varying needs for what is contained in an authentication token.
To accommodate these varied needs, Zend_Auth_Token_Interface
is available for providing
a very basic set of common functionality, and it defines three methods:
isValid()
- returns whether the token represents a successful authentication
attempt
getIdentity()
- returns the identity of the authentication attempt
getMessage()
- returns a message regarding a failed authentication attempt
Because each authentication mechanism varies, each concrete adapter provides its own token class.
For example, the digest authentication adapter provides
Zend_Auth_Digest_Token
.
Of course, developers can extend such token classes to suit their particular needs. For example, the date and time of the authentication attempt is a typically useful piece of information to have recorded in the token object.
HTTP is a stateless protocol, and techniques such as cookies and sessions have been developed in order to facilitate maintaining state across multiple requests in server-side web applications. Zend_Session is used within Zend_Auth to provide persistence of authentication tokens using the PHP session.
This feature is on by default, but may be disabled for situations in which it may not be needed.
Upon an authentication attempt, Zend_Auth stores the resulting authentication token into the session
using Zend_Session. By default, the token is stored into a
session namespace of "Zend_Auth
" and has a token member name of "token
",
but these values are configurable where developers may need to store multiple tokens organized
in various ways.
There are two main ways to use Zend_Auth adapters:
indirectly, through Zend_Auth
directly, through the adapter
The following example illustrates how to use a Zend_Auth adapter indirectly, through the use of
Zend_Auth
:
<?php // create a new authentication object against MyAuth_Adapter require_once 'Zend/Auth.php'; $auth = new Zend_Auth(new MyAuth_Adapter()); // setup authentication options $options = array( 'username' => 'someUser', 'password' => 'somePassword' ); // authentication attempt; token is also saved in the session $token = $auth->authenticate($options); if (!$token->isValid()) { // authentication failed throw new Exception($token->getMessage()); } else { // authentication succeeded } // save the identity associated with the authentication attempt $identity = $token->getIdentity();
Once authentication has been attempted, as in the above example, it is a simple matter to see whether a valid authentication token exists in the session:
if ($auth->isLoggedIn()) { // valid authentication token exists; get it $token = $auth->getToken(); }
To remove a session token completely, just use the logout()
method:
$auth->logout()