documentation/manual/en/tutorials/multiuser-authentication.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.multiuser.authentication">
   4     <title>Authenticating Users in Zend Framework</title>
   5
   6     <sect2 id="learning.multiuser.authentication.intro">
   7         <title>Introduction to Authentication</title>
   8
   9         <para>
  10             Once a web application has been able to distinguish one user from another by
  11             establishing a session, web applications typically want to validate the identity
  12             of a user. The process of validating a consumer as being authentic is "authentication."
  13             Authentication is made up of two distinctive parts: an identity and a set of
  14             credentials. It takes some variation of both presented to the application for
  15             processing so that it may authenticate a user.
  16         </para>
  17
  18         <para>
  19             While the most common pattern of authentication revolves around usernames and
  20             passwords, it should be stated that this is not always the case. Identities are
  21             not limited to usernames. In fact, any public identifier can be used: an assigned
  22             number, social security number, or residence address. Likewise, credentials are not
  23             limited to passwords. Credentials can come in the form of protected private
  24             information: fingerprint, eye retinal scan, passphrase, or any other obscure personal
  25             information.
  26         </para>
  27     </sect2>
  28
  29     <sect2 id="learning.multiuser.authentication.basic-usage">
  30         <title>Basic Usage of Zend_Auth</title>
  31
  32         <para>
  33             In the following example, we will be using <classname>Zend_Auth</classname> to
  34             complete what is probably the most prolific form of authentication: username and
  35             password from a database table. This example assumes that you have already setup your
  36             application using <classname>Zend_Application</classname>, and that inside that
  37             application you have configured a database connection.
  38         </para>
  39
  40         <para>
  41             The job of the <classname>Zend_Auth</classname> class is twofold. First, it should
  42             be able to accept an authentication adapter to use to authenticate a user. Secondly,
  43             after a successful authentication of a user, it should persist throughout each and
  44             every request that might need to know if the current user has indeed been
  45             authenticated. To persist this data, <classname>Zend_Auth</classname> consumes
  46             <classname>Zend_Session_Namespace</classname>, but you will generally never need
  47             to interact with this session object.
  48         </para>
  49
  50         <para>
  51             Lets assume we have the following database table setup:
  52         </para>
  53
  54         <programlisting language="php"><![CDATA[
  55 CREATE TABLE users (
  56     id INTEGER  NOT NULL PRIMARY KEY,
  57     username VARCHAR(50) UNIQUE NOT NULL,
  58     password VARCHAR(32) NULL,
  59     password_salt VARCHAR(32) NULL,
  60     real_name VARCHAR(150) NULL
  61 )
  62 ]]></programlisting>
  63
  64         <para>
  65             The above demonstrates a user table that includes a username, password, and also a
  66             password salt column. This salt column is used as part of a technique called salting
  67             that would improve the security of your database of information against brute force
  68             attacks targeting the algorithm of your password hashing. <ulink
  69                 url="http://en.wikipedia.org/wiki/Salting_%28cryptography%29">More
  70                 information</ulink> on salting.
  71         </para>
  72
  73         <para>
  74             For this implementation, we must first make a simple form that we can utilized as
  75             the "login form". We will use <classname>Zend_Form</classname> to accomplish this.
  76         </para>
  77
  78         <programlisting language="php"><![CDATA[
  79 // located at application/forms/Auth/Login.php
  80
  81 class Default_Form_Auth_Login extends Zend_Form
  82 {
  83     public function init()
  84     {
  85         $this->setMethod('post');
  86
  87         $this->addElement(
  88             'text', 'username', array(
  89                 'label' => 'Username:',
  90                 'required' => true,
  91                 'filters'    => array('StringTrim'),
  92             ));
  93
  94         $this->addElement('password', 'password', array(
  95             'label' => 'Password:',
  96             'required' => true,
  97             ));
  98
  99         $this->addElement('submit', 'submit', array(
 100             'ignore'   => true,
 101             'label'    => 'Login',
 102             ));
 103
 104     }
 105 }
 106 ]]></programlisting>
 107
 108         <para>
 109             With the above form, we can now go about creating our login action for
 110             our authentication controller. This controller will be called
 111             "<classname>AuthController</classname>", and will be located at
 112             <filename>application/controllers/AuthController.php</filename>. It will have a
 113             single method called "<methodname>loginAction()</methodname>" which will serve as the
 114             self-posting action. In other words, regardless of the url was POSTed to or GETed
 115             to, this method will handle the logic.
 116         </para>
 117
 118         <para>
 119             The following code will demonstrate how to construct the proper adapter, integrate it
 120             with the form:
 121         </para>
 122
 123         <programlisting language="php"><![CDATA[
 124 class AuthController extends Zend_Controller_Action
 125 {
 126
 127     public function loginAction()
 128     {
 129         $db = $this->_getParam('db');
 130
 131         $loginForm = new Default_Form_Auth_Login($_POST);
 132
 133         if ($loginForm->isValid()) {
 134
 135             $adapter = new Zend_Auth_Adapter_DbTable(
 136                 $db,
 137                 'users',
 138                 'username',
 139                 'password',
 140                 'MD5(CONCAT(?, password_salt))'
 141                 );
 142
 143             $adapter->setIdentity($loginForm->getValue('username'));
 144             $adapter->setCredential($loginForm->getValue('password'));
 145
 146             $result = $auth->authenticate($adapter);
 147
 148             if ($result->isValid()) {
 149                 $this->_helper->FlashMessenger('Successful Login');
 150                 $this->redirect('/');
 151                 return;
 152             }
 153
 154         }
 155
 156         $this->view->loginForm = $loginForm;
 157
 158     }
 159
 160 }
 161 ]]></programlisting>
 162
 163         <para>
 164             The corresponding view script is quite simple for this action. It will set the current
 165             url since this form is self processing, and it will display the form. This view script
 166             is located at <filename>application/views/scripts/auth/login.phtml</filename>:
 167         </para>
 168
 169         <programlisting language="php"><![CDATA[
 170 $this->form->setAction($this->url());
 171 echo $this->form;
 172 ]]></programlisting>
 173
 174         <para>
 175             There you have it. With these basics you can expand the general concepts to include
 176             more complex authentication scenarios. For more information on other
 177             <classname>Zend_Auth</classname> adapters, have a look in
 178             <link linkend="zend.auth">the reference guide</link>.
 179         </para>
 180     </sect2>
 181 </sect1>