Chapter 1. Zend_Auth

Table of Contents

1.1. Introduction
1.1.1. Adapters
1.1.2. Tokens
1.1.3. Token Persistence
1.1.4. Using Zend_Auth
1.2. Digest Authentication
1.2.1. Introduction
1.2.2. Adapter
1.2.3. Token

1.1. Introduction

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

[Note] 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.

1.1.1. Adapters

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.

1.1.2. Tokens

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.

1.1.3. Token Persistence

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.

1.1.4. Using Zend_Auth

There are two main ways to use Zend_Auth adapters:

  1. indirectly, through Zend_Auth

  2. 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()