includes/auth/auth.php

   1 <?php
   2 /*=====================================================================*\
   3 || ###################################################################
   4 || # Bugdar [#]version[#]
   5 || # Copyright ©2002-[#]year[#] Blue Static
   6 || #
   7 || # This program is free software; you can redistribute it and/or modify
   8 || # it under the terms of the GNU General Public License as published by
   9 || # the Free Software Foundation; version [#]gpl[#] of the License.
  10 || #
  11 || # This program is distributed in the hope that it will be useful, but
  12 || # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13 || # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  14 || # more details.
  15 || #
  16 || # You should have received a copy of the GNU General Public License along
  17 || # with this program; if not, write to the Free Software Foundation, Inc.,
  18 || # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  19 || ###################################################################
  20 \*=====================================================================*/
  21
  22 require_once('./includes/api_user.php');
  23
  24 /**
  25 * Abstract Authentication
  26 *
  27 * This is an abstract class that is used to provide authentication for
  28 * Bugdar.
  29 *
  30 * @author               Blue Static
  31 * @copyright    Copyright (c)2002 - [#]year[#], Blue Static
  32 * @version              $Revision$
  33 * @package              Bugdar
  34 *
  35 */
  36 class Authentication
  37 {
  38         /**
  39         * The database connection to AUTHENTICATE against; can be to a separate database
  40         * @var object
  41         */
  42         var $authDb;
  43
  44         /**
  45         * The database connection to the BUGDAR database
  46         * @var object
  47         */
  48         var $db;
  49
  50         /**
  51         * The Bugdar registry
  52         * @var object
  53         */
  54         var $registry;
  55
  56         /**
  57         * Array of user data from the AUTHENTICATION database
  58         * @var array
  59         */
  60         var $authUser;
  61
  62         /**
  63         * Array of user data from the BUGDAR database
  64         * @var array
  65         */
  66         var $bugdarUser;
  67
  68         // ###################################################################
  69         /**
  70         * Constructor
  71         */
  72         function __construct()
  73         {
  74                 global $bugsys;
  75
  76                 $this->registry =& $bugsys;
  77                 $this->db =& $bugsys->db;
  78
  79                 $this->_setupDatabase();
  80         }
  81
  82         // ###################################################################
  83         /**
  84         * Sets up the database to authenticate against. You can create a new
  85         * database object here. Whatever you choose, you need to reference
  86         * Authentication->authDb to the object
  87         */
  88         function _setupDatabase() {}
  89
  90         // ###################################################################
  91         /**
  92         * Returns the sanitized value of the user ID or unique identifier
  93         * found in the cookie of an already-authenticated user.
  94         */
  95         function _fetchCookieUniqueId() {}
  96
  97         // ###################################################################
  98         /**
  99         * Returns the sanitized value of the authentication key or cookie-safe
 100         * password found in the cookies of an already-authenticated user.
 101         */
 102         function _fetchCookiePassword() {}
 103
 104         // ###################################################################
 105         /**
 106         * Returns an array of user data fetched using the user information
 107         * values found in cookies. It should NOT be responsible for verifying
 108         * the authentication information, but only fetching it.
 109         */
 110         function _fetchUserUsingCookies() {}
 111
 112         // ###################################################################
 113         /**
 114         * Returns TRUE if the cookie data values are valid in the data array
 115         * returned from _fetchUserUsingCookies(), and FALSE if they are not.
 116         */
 117         function _verifyCookieData() {}
 118
 119         // ###################################################################
 120         /**
 121         * Authenticates the user using cookie data. You shouldn't need to
 122         * customize this method if you implement all the helpers correctly.
 123         * Returns TRUE if the cookies are valid and the user is logged in.
 124         */
 125         function authenticateCookies()
 126         {
 127                 if (!$this->_fetchCookieUniqueId() OR !$this->_fetchCookiePassword())
 128                 {
 129                         $this->_clearCookies();
 130                         return false;
 131                 }
 132
 133                 $this->authUser = $this->_fetchUserUsingCookies();
 134
 135                 if (!$this->authUser)
 136                 {
 137                         $this->authUser = null;
 138                         $this->_clearCookies();
 139                         return false;
 140                 }
 141
 142                 if ($this->_verifyCookieData())
 143                 {
 144                         $this->_setCookies();
 145                         $this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
 146                         return true;
 147                 }
 148                 else
 149                 {
 150                         $this->authUser = null;
 151                         $this->_clearCookies();
 152                         return false;
 153                 }
 154         }
 155
 156         // ###################################################################
 157         /**
 158         * Returns an array with the authentication user information, found
 159         * by the unique login identifier passed to the function.
 160         */
 161         function _fetchUserWithIdentifier($string) {}
 162
 163         // ###################################################################
 164         /**
 165         * Verifies that the authUser's password matches the plain-text password
 166         * passed to this function. This is basically the transformation of
 167         * the plaintext to the hashed password and the result of the comparison.
 168         */
 169         function _verifyLoginUser($password) {}
 170
 171         // ###################################################################
 172         /**
 173         * Authenticates a user at login from two keys: an identifier and
 174         * a password. In Bugdar, the identifier is an email, but it can be
 175         * any unique string found in the authentication database. Returns
 176         * TRUE if the authentication is successful, and FALSE if not.
 177         */
 178         function authenticateLogin($string, $password)
 179         {
 180                 $this->authUser = $this->_fetchUserWithIdentifier($string);
 181
 182                 if (!$this->authUser)
 183                 {
 184                         $this->authUser = null;
 185                         return false;
 186                 }
 187
 188                 if ($this->_verifyLoginUser())
 189                 {
 190                         $this->_setCookies();
 191                         $this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
 192                         return true;
 193                 }
 194                 else
 195                 {
 196                         $this->authUser = null
 197                         return false;
 198                 }
 199         }
 200
 201         // ###################################################################
 202         /**
 203         * Returns the BUGDAR user array from the data in the AUTHENTICATION user
 204         * array. If the Bugdar user does not exist, call _createBugdarUser()
 205         * to add the user into the Bugdar database. This is necessary so Bugdar options
 206         * can be saved in the Bugdar database (and not in the auth one), however
 207         * authentication details will NOT be stored in the Bugdar database.
 208         */
 209         function _fetchBugdarUserFromAuthUser() {}
 210
 211         // ###################################################################
 212         /**
 213         * Creates a Bugdar user with the authentication details specified in
 214         * the auth array and returns it. You need to call this in
 215         * _fetchBugdarUserFromAuthUser() and use the UserAPI to create the user.
 216         * Example for this function is this (all of these fields are required):
 217         *
 218         * $user = new UserAPI($this->registry); // do not change this
 219         * $user->set('email', $this->authUser['email']);
 220         * $user->set('displayname', $this->authUser['name']);
 221         * $user->set('password', $this->authUser['password']); // some random value that won't be used for authentication
 222         * $user->set('usergroupid', 2); // default "Registered Users" group
 223         * $user->set('authid', $this->authUser['userid']); // This must be a COMPLETELY STATIC key that is found in the auth db that will permanently link Bugdar to the auth user
 224         * $user->insert(); // saves the user
 225         *
 226         * return $user->values; // returns the newly created user array
 227         */
 228         function _createBugdarUser() {}
 229
 230         // ###################################################################
 231         /**
 232         * Responsible for unsetting all authentication cookies because they
 233         * are invalid
 234         */
 235         function _clearCookies() {}
 236
 237         // ###################################################################
 238         /**
 239         * Sets the authentication cookies; this is done both at login and
 240         * for renewing the cookies upon successful cookie validation
 241         */
 242         function _setCookies() {}
 243 }
 244
 245 /*=====================================================================*\
 246 || ###################################################################
 247 || # $HeadURL$
 248 || # $Id$
 249 || ###################################################################
 250 \*=====================================================================*/
 251 ?>