includes/auth/auth.php

   1 <?php
   2 /*=====================================================================*\
   3 || ###################################################################
   4 || # Bugdar
   5 || # Copyright ©2002-2007 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 2 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 - 2007, 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         * Mapping of Bugdar fields to authentication database fields; these will be synced between databases upon login.
  70         * AT THE VERY MINIMUM, YOU MUST MAP THESE FIELDS:
  71         * @var array
  72         */
  73         var $fieldMap = array(
  74                 'authid'                => null,
  75                 'displayname'   => null,
  76                 'email'                 => null,
  77         );
  78
  79         // ###################################################################
  80         /**
  81         * Constructor
  82         */
  83         function __construct()
  84         {
  85                 global $bugsys;
  86
  87                 $this->registry =& $bugsys;
  88                 $this->db =& $bugsys->db;
  89
  90                 $this->registry->debug('authentication system: ' . get_class($this));
  91
  92                 $this->_setupDatabase();
  93         }
  94
  95         // ###################################################################
  96         /**
  97         * (PHP 4) Constructor
  98         */
  99         function Authentication()
 100         {
 101                 $this->__construct();
 102         }
 103
 104         // ###################################################################
 105         /**
 106         * Returns the information array for the Bugdar user. This must be
 107         * called after an authentication method.
 108         */
 109         function fetchBugdarUser()
 110         {
 111                 return $this->bugdarUser;
 112         }
 113
 114         // ###################################################################
 115         /**
 116         * Sets up the database to authenticate against. You can create a new
 117         * database object here. Whatever you choose, you need to reference
 118         * Authentication->authDb to the object
 119         */
 120         function _setupDatabase()
 121         {
 122                 // connect to the DB
 123                 $this->authDb = new DB_MySQL($this->registry);
 124
 125                 require_once 'includes/auth/config.php';
 126                 $this->authDb->connect(
 127                         $config['auth']['dbServer'],
 128                         $config['auth']['dbUser'],
 129                         $config['auth']['dbPassword'],
 130                         $config['auth']['dbName'],
 131                         false
 132                 );
 133         }
 134
 135         // ###################################################################
 136         /**
 137         * Returns the sanitized value of the user ID or unique identifier
 138         * found in the cookie of an already-authenticated user.
 139         */
 140         function _fetchCookieUniqueId() {}
 141
 142         // ###################################################################
 143         /**
 144         * Returns the sanitized value of the authentication key or cookie-safe
 145         * password found in the cookies of an already-authenticated user.
 146         */
 147         function _fetchCookiePassword() {}
 148
 149         // ###################################################################
 150         /**
 151         * Returns an array of user data fetched using the user information
 152         * values found in cookies. It should NOT be responsible for verifying
 153         * the authentication information, but only fetching it.
 154         */
 155         function _fetchUserUsingCookies() {}
 156
 157         // ###################################################################
 158         /**
 159         * Returns TRUE if the cookie data values are valid in the data array
 160         * returned from _fetchUserUsingCookies(), and FALSE if they are not.
 161         */
 162         function _verifyCookieData() {}
 163
 164         // ###################################################################
 165         /**
 166         * Authenticates the user using cookie data. You shouldn't need to
 167         * customize this method if you implement all the helpers correctly.
 168         * Returns TRUE if the cookies are valid and the user is logged in.
 169         */
 170         function authenticateCookies()
 171         {
 172                 if (!$this->_fetchCookieUniqueId() OR !$this->_fetchCookiePassword())
 173                 {
 174                         return false;
 175                 }
 176
 177                 $this->authUser = $this->_fetchUserUsingCookies();
 178                 if (!$this->authUser)
 179                 {
 180                         $this->authUser = null;
 181                         return false;
 182                 }
 183
 184                 if ($this->_verifyCookieData())
 185                 {
 186                         $this->_setCookies(true);
 187                         $this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
 188                         if ($this->_syncBugdarUser())
 189                         {
 190                                 $this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
 191                         }
 192                         return true;
 193                 }
 194                 else
 195                 {
 196                         $this->authUser = null;
 197                         $this->clearCookies();
 198                         return false;
 199                 }
 200         }
 201
 202         // ###################################################################
 203         /**
 204         * Returns an array with the authentication user information, found
 205         * by the unique login identifier passed to the function.
 206         */
 207         function _fetchUserWithIdentifier($string) {}
 208
 209         // ###################################################################
 210         /**
 211         * Verifies that the authUser's password matches the plain-text password
 212         * passed to this function. This is basically the transformation of
 213         * the plaintext to the hashed password and the result of the comparison.
 214         */
 215         function _verifyLoginUser($password) {}
 216
 217         // ###################################################################
 218         /**
 219         * Authenticates a user at login from two keys: an identifier and
 220         * a password. In Bugdar, the identifier is an email, but it can be
 221         * any unique string found in the authentication database. Returns
 222         * TRUE if the authentication is successful, and FALSE if not. Also
 223         * determines if the cookies are sticky ("rememember me" login)
 224         */
 225         function authenticateLogin($string, $password, $sticky = false)
 226         {
 227                 $this->authUser = $this->_fetchUserWithIdentifier($string);
 228
 229                 if (!$this->authUser)
 230                 {
 231                         $this->authUser = null;
 232                         return false;
 233                 }
 234
 235                 if ($this->_verifyLoginUser($password))
 236                 {
 237                         $this->_setCookies($sticky);
 238                         $this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
 239                         $this->_syncBugdarUser();
 240                         return true;
 241                 }
 242                 else
 243                 {
 244                         $this->authUser = null;
 245                         return false;
 246                 }
 247         }
 248
 249         // ###################################################################
 250         /**
 251         * Returns the BUGDAR user array from the data in the AUTHENTICATION user
 252         * array. If the Bugdar user does not exist, call _createBugdarUser()
 253         * to add the user into the Bugdar database. This is necessary so Bugdar options
 254         * can be saved in the Bugdar database (and not in the auth one), however
 255         * authentication details will NOT be stored in the Bugdar database.
 256         */
 257         function _fetchBugdarUserFromAuthUser()
 258         {
 259                 $user = $this->db->query_first("SELECT * FROM " . TABLE_PREFIX . "user WHERE authid = '" . $this->authUser[ $this->fieldMap['authid'] ] . "'");
 260                 if (!$user)
 261                 {
 262                         return $this->_createBugdarUser();
 263                 }
 264                 return $user;
 265         }
 266
 267         // ###################################################################
 268         /**
 269         * Creates a Bugdar user with the authentication details specified in
 270         * the auth array and returns it. You need to call this in
 271         * _fetchBugdarUserFromAuthUser() and use the UserAPI to create the user.
 272         * This will create a new user in Bugdar with the data from the authentication DB
 273         * with the fields specified in fieldMap.
 274         */
 275         function _createBugdarUser()
 276         {
 277                 $user = new UserAPI($this->registry);
 278
 279                 // if the email already exists in the DB, it must be the same person so just hook up the authid
 280                 if ($check = $this->db->query_first("SELECT * FROM " . TABLE_PREFIX . "user WHERE email = '" . $this->db->escape_string($this->authUser[ $this->fieldMap['email'] ]) . "'"))
 281                 {
 282                         $user->set('userid', $check['userid']);
 283                         $user->set_condition();
 284                         $user->set('authid', $this->authUser[ $this->fieldMap['authid'] ]);
 285                         $user->update();
 286                         $user->fetch();
 287
 288                         return $user->objdata;
 289                 }
 290                 else
 291                 {
 292                         $user = new UserAPI($this->registry);
 293                         foreach ($this->fieldMap AS $bugdar => $authdb)
 294                         {
 295                                 $user->set($bugdar, $this->authUser["$authdb"]);
 296                         }
 297                         $user->set('usergroupid', 2);
 298                         $user->insert();
 299
 300                         return $user->values;
 301                 }
 302         }
 303
 304         // ###################################################################
 305         /**
 306         * Syncs a Bugdar user's fieldMap'ed values to the authentication DB's
 307         * values. This allows the users to stay mostly-in-sync for the most
 308         * basic of information (like email, timezone, etc.). Passwords are
 309         * NOT synced. Returns TRUE if the user data was changed.
 310         */
 311         function _syncBugdarUser()
 312         {
 313                 $fields = $this->fieldMap;
 314                 unset($fields['authid']);
 315                 unset($fields['password']);
 316
 317                 $change = false;
 318
 319                 $user = new UserAPI($this->registry);
 320                 $user->set('userid', $this->bugdarUser['userid']);
 321                 $user->set_condition();
 322                 foreach ($fields AS $bugdar => $auth)
 323                 {
 324                         if ($this->bugdarUser["$bugdar"] != $this->authUser["$auth"])
 325                         {
 326                                 $user->set($bugdar, $this->authUser["$auth"]);
 327                                 $change = true;
 328                         }
 329                 }
 330                 if ($change)
 331                 {
 332                         $user->update();
 333                 }
 334
 335                 return $change;
 336         }
 337
 338         // ###################################################################
 339         /**
 340         * Responsible for unsetting all authentication cookies because they
 341         * are invalid
 342         */
 343         function clearCookies() {}
 344
 345         // ###################################################################
 346         /**
 347         * Sets the authentication cookies; this is done both at login and
 348         * for renewing the cookies upon successful cookie validation. The
 349         * option it takes determines whether the cookies are sticky or not.
 350         */
 351         function _setCookies($permanent = false) {}
 352 }
 353
 354 /*=====================================================================*\
 355 || ###################################################################
 356 || # $HeadURL$
 357 || # $Id$
 358 || ###################################################################
 359 \*=====================================================================*/
 360 ?>