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(true);
 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. Also
 187         * determines if the cookies are sticky ("rememember me" login)
 188         */
 189         function authenticateLogin($string, $password, $sticky = false)
 190         {
 191                 $this->authUser = $this->_fetchUserWithIdentifier($string);
 192
 193                 if (!$this->authUser)
 194                 {
 195                         $this->authUser = null;
 196                         return false;
 197                 }
 198
 199                 if ($this->_verifyLoginUser($password))
 200                 {
 201                         $this->_setCookies($sticky);
 202                         $this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
 203                         return true;
 204                 }
 205                 else
 206                 {
 207                         $this->authUser = null;
 208                         return false;
 209                 }
 210         }
 211
 212         // ###################################################################
 213         /**
 214         * Returns the BUGDAR user array from the data in the AUTHENTICATION user
 215         * array. If the Bugdar user does not exist, call _createBugdarUser()
 216         * to add the user into the Bugdar database. This is necessary so Bugdar options
 217         * can be saved in the Bugdar database (and not in the auth one), however
 218         * authentication details will NOT be stored in the Bugdar database.
 219         */
 220         function _fetchBugdarUserFromAuthUser() {}
 221
 222         // ###################################################################
 223         /**
 224         * Creates a Bugdar user with the authentication details specified in
 225         * the auth array and returns it. You need to call this in
 226         * _fetchBugdarUserFromAuthUser() and use the UserAPI to create the user.
 227         * Example for this function is this (all of these fields are required):
 228         *
 229         * $user = new UserAPI($this->registry); // do not change this
 230         * $user->set('email', $this->authUser['email']);
 231         * $user->set('displayname', $this->authUser['name']);
 232         * $user->set('password', $this->authUser['password']); // some random value that won't be used for authentication
 233         * $user->set('usergroupid', 2); // default "Registered Users" group
 234         * $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
 235         * $user->insert(); // saves the user
 236         *
 237         * return $user->values; // returns the newly created user array
 238         */
 239         function _createBugdarUser() {}
 240
 241         // ###################################################################
 242         /**
 243         * Responsible for unsetting all authentication cookies because they
 244         * are invalid
 245         */
 246         function _clearCookies() {}
 247
 248         // ###################################################################
 249         /**
 250         * Sets the authentication cookies; this is done both at login and
 251         * for renewing the cookies upon successful cookie validation. The
 252         * option it takes determines whether the cookies are sticky or not.
 253         */
 254         function _setCookies($permanent = false) {}
 255 }
 256
 257 /*=====================================================================*\
 258 || ###################################################################
 259 || # $HeadURL$
 260 || # $Id$
 261 || ###################################################################
 262 \*=====================================================================*/
 263 ?>