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         * Returns the information array for the Bugdar user. This must be
  85         * called after an authentication method.
  86         */
  87         function fetchBugdarUser()
  88         {
  89                 return $this->bugdarUser;
  90         }
  91
  92         // ###################################################################
  93         /**
  94         * Sets up the database to authenticate against. You can create a new
  95         * database object here. Whatever you choose, you need to reference
  96         * Authentication->authDb to the object
  97         */
  98         function _setupDatabase() {}
  99
 100         // ###################################################################
 101         /**
 102         * Returns the sanitized value of the user ID or unique identifier
 103         * found in the cookie of an already-authenticated user.
 104         */
 105         function _fetchCookieUniqueId() {}
 106
 107         // ###################################################################
 108         /**
 109         * Returns the sanitized value of the authentication key or cookie-safe
 110         * password found in the cookies of an already-authenticated user.
 111         */
 112         function _fetchCookiePassword() {}
 113
 114         // ###################################################################
 115         /**
 116         * Returns an array of user data fetched using the user information
 117         * values found in cookies. It should NOT be responsible for verifying
 118         * the authentication information, but only fetching it.
 119         */
 120         function _fetchUserUsingCookies() {}
 121
 122         // ###################################################################
 123         /**
 124         * Returns TRUE if the cookie data values are valid in the data array
 125         * returned from _fetchUserUsingCookies(), and FALSE if they are not.
 126         */
 127         function _verifyCookieData() {}
 128
 129         // ###################################################################
 130         /**
 131         * Authenticates the user using cookie data. You shouldn't need to
 132         * customize this method if you implement all the helpers correctly.
 133         * Returns TRUE if the cookies are valid and the user is logged in.
 134         */
 135         function authenticateCookies()
 136         {
 137                 if (!$this->_fetchCookieUniqueId() OR !$this->_fetchCookiePassword())
 138                 {
 139                         $this->_clearCookies();
 140                         return false;
 141                 }
 142
 143                 $this->authUser = $this->_fetchUserUsingCookies();
 144
 145                 if (!$this->authUser)
 146                 {
 147                         $this->authUser = null;
 148                         $this->_clearCookies();
 149                         return false;
 150                 }
 151
 152                 if ($this->_verifyCookieData())
 153                 {
 154                         $this->_setCookies();
 155                         $this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
 156                         return true;
 157                 }
 158                 else
 159                 {
 160                         $this->authUser = null;
 161                         $this->_clearCookies();
 162                         return false;
 163                 }
 164         }
 165
 166         // ###################################################################
 167         /**
 168         * Returns an array with the authentication user information, found
 169         * by the unique login identifier passed to the function.
 170         */
 171         function _fetchUserWithIdentifier($string) {}
 172
 173         // ###################################################################
 174         /**
 175         * Verifies that the authUser's password matches the plain-text password
 176         * passed to this function. This is basically the transformation of
 177         * the plaintext to the hashed password and the result of the comparison.
 178         */
 179         function _verifyLoginUser($password) {}
 180
 181         // ###################################################################
 182         /**
 183         * Authenticates a user at login from two keys: an identifier and
 184         * a password. In Bugdar, the identifier is an email, but it can be
 185         * any unique string found in the authentication database. Returns
 186         * TRUE if the authentication is successful, and FALSE if not.
 187         */
 188         function authenticateLogin($string, $password)
 189         {
 190                 $this->authUser = $this->_fetchUserWithIdentifier($string);
 191
 192                 if (!$this->authUser)
 193                 {
 194                         $this->authUser = null;
 195                         return false;
 196                 }
 197
 198                 if ($this->_verifyLoginUser($password))
 199                 {
 200                         $this->_setCookies();
 201                         $this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
 202                         return true;
 203                 }
 204                 else
 205                 {
 206                         $this->authUser = null;
 207                         return false;
 208                 }
 209         }
 210
 211         // ###################################################################
 212         /**
 213         * Returns the BUGDAR user array from the data in the AUTHENTICATION user
 214         * array. If the Bugdar user does not exist, call _createBugdarUser()
 215         * to add the user into the Bugdar database. This is necessary so Bugdar options
 216         * can be saved in the Bugdar database (and not in the auth one), however
 217         * authentication details will NOT be stored in the Bugdar database.
 218         */
 219         function _fetchBugdarUserFromAuthUser() {}
 220
 221         // ###################################################################
 222         /**
 223         * Creates a Bugdar user with the authentication details specified in
 224         * the auth array and returns it. You need to call this in
 225         * _fetchBugdarUserFromAuthUser() and use the UserAPI to create the user.
 226         * Example for this function is this (all of these fields are required):
 227         *
 228         * $user = new UserAPI($this->registry); // do not change this
 229         * $user->set('email', $this->authUser['email']);
 230         * $user->set('displayname', $this->authUser['name']);
 231         * $user->set('password', $this->authUser['password']); // some random value that won't be used for authentication
 232         * $user->set('usergroupid', 2); // default "Registered Users" group
 233         * $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
 234         * $user->insert(); // saves the user
 235         *
 236         * return $user->values; // returns the newly created user array
 237         */
 238         function _createBugdarUser() {}
 239
 240         // ###################################################################
 241         /**
 242         * Responsible for unsetting all authentication cookies because they
 243         * are invalid
 244         */
 245         function _clearCookies() {}
 246
 247         // ###################################################################
 248         /**
 249         * Sets the authentication cookies; this is done both at login and
 250         * for renewing the cookies upon successful cookie validation
 251         */
 252         function _setCookies() {}
 253 }
 254
 255 /*=====================================================================*\
 256 || ###################################################################
 257 || # $HeadURL$
 258 || # $Id$
 259 || ###################################################################
 260 \*=====================================================================*/
 261 ?>