lib/authlib.php

   1 <?php  // $Id$
   2 /**
   3  * @author Martin Dougiamas
   4  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
   5  * @package moodle multiauth
   6  *
   7  * Multiple plugin authentication
   8  * Support library
   9  *
  10  * 2006-08-28  File created, AUTH return values defined.
  11  */
  12
  13 /**
  14  * Returned when the login was successful.
  15  */
  16 define('AUTH_OK',     0);
  17
  18 /**
  19  * Returned when the login was unsuccessful.
  20  */
  21 define('AUTH_FAIL',   1);
  22
  23 /**
  24  * Returned when the login was denied (a reason for AUTH_FAIL).
  25  */
  26 define('AUTH_DENIED', 2);
  27
  28 /**
  29  * Returned when some error occurred (a reason for AUTH_FAIL).
  30  */
  31 define('AUTH_ERROR',  4);
  32
  33 /**
  34  * Authentication - error codes for user confirm
  35  */
  36 define('AUTH_CONFIRM_FAIL', 0);
  37 define('AUTH_CONFIRM_OK', 1);
  38 define('AUTH_CONFIRM_ALREADY', 2);
  39 define('AUTH_CONFIRM_ERROR', 3);
  40
  41 # MDL-14055
  42 define('AUTH_REMOVEUSER_KEEP', 0);
  43 define('AUTH_REMOVEUSER_SUSPEND', 1);
  44 define('AUTH_REMOVEUSER_FULLDELETE', 2);
  45
  46 /**
  47  * Abstract authentication plugin.
  48  */
  49 class auth_plugin_base {
  50
  51     /**
  52      * The configuration details for the plugin.
  53      */
  54     var $config;
  55
  56     /**
  57      * Authentication plugin type - the same as db field.
  58      */
  59     var $authtype;
  60     /*
  61      * The fields we can lock and update from/to external authentication backends
  62      */
  63     var $userfields = array(
  64         'firstname',
  65         'lastname',
  66         'email',
  67         'city',
  68         'country',
  69         'lang',
  70         'description',
  71         'url',
  72         'idnumber',
  73         'institution',
  74         'department',
  75         'phone1',
  76         'phone2',
  77         'address'
  78     );
  79
  80     /**
  81
  82      * This is the primary method that is used by the authenticate_user_login()
  83      * function in moodlelib.php. This method should return a boolean indicating
  84      * whether or not the username and password authenticate successfully.
  85      *
  86      * Returns true if the username and password work and false if they are
  87      * wrong or don't exist.
  88      *
  89      * @param string $username The username (with system magic quotes)
  90      * @param string $password The password (with system magic quotes)
  91      *
  92      * @return bool Authentication success or failure.
  93      */
  94     function user_login($username, $password) {
  95         error('Abstract user_login() method must be overriden.');
  96     }
  97
  98     /**
  99      * Returns true if this authentication plugin can change the users'
 100      * password.
 101      *
 102      * @return bool
 103      */
 104     function can_change_password() {
 105         //override if needed
 106         return false;
 107     }
 108
 109     /**
 110      * Returns the URL for changing the users' passwords, or empty if the default
 111      * URL can be used. This method is used if can_change_password() returns true.
 112      * This method is called only when user is logged in, it may use global $USER.
 113      *
 114      * @return string
 115      */
 116     function change_password_url() {
 117         //override if needed
 118         return '';
 119     }
 120
 121     /**
 122      * Returns true if this authentication plugin is "internal" (which means that
 123      * Moodle stores the users' passwords and other details in the local Moodle
 124      * database).
 125      *
 126      * @return bool
 127      */
 128     function is_internal() {
 129         //override if needed
 130         return true;
 131     }
 132
 133     /**
 134      * Indicates if password hashes should be stored in local moodle database.
 135      * @return bool true means md5 password hash stored in user table, false means flag 'not_cached' stored there instead
 136      */
 137     function prevent_local_passwords() {
 138         // NOTE: this will be changed to true in 2.0
 139         return false;
 140     }
 141
 142     /**
 143      * Updates the user's password. In previous versions of Moodle, the function
 144      * auth_user_update_password accepted a username as the first parameter. The
 145      * revised function expects a user object.
 146      *
 147      * @param  object  $user        User table object  (with system magic quotes)
 148      * @param  string  $newpassword Plaintext password (with system magic quotes)
 149      *
 150      * @return bool                  True on success
 151      */
 152     function user_update_password($user, $newpassword) {
 153         //override if needed
 154         return true;
 155     }
 156
 157     /**
 158      * Called when the user record is updated.
 159      * Modifies user in external database. It takes olduser (before changes) and newuser (after changes)
 160      * conpares information saved modified information to external db.
 161      *
 162      * @param mixed $olduser     Userobject before modifications    (without system magic quotes)
 163      * @param mixed $newuser     Userobject new modified userobject (without system magic quotes)
 164      * @return boolean true if updated or update ignored; false if error
 165      *
 166      */
 167     function user_update($olduser, $newuser) {
 168         //override if needed
 169         return true;
 170     }
 171
 172     /**
 173      * User delete requested - internal user record is mared as deleted already, username not present anymore.
 174      * Do any action in external database.
 175      * @param object $user       Userobject before delete    (without system magic quotes)
 176      */
 177     function user_delete($olduser) {
 178         //override if needed
 179         return;
 180     }
 181
 182     /**
 183      * Returns true if plugin allows resetting of internal password.
 184      *
 185      * @return bool
 186      */
 187     function can_reset_password() {
 188         //override if needed
 189         return false;
 190     }
 191
 192     /**
 193      * Returns true if plugin allows resetting of internal password.
 194      *
 195      * @return bool
 196      */
 197     function can_signup() {
 198         //override if needed
 199         return false;
 200     }
 201
 202     /**
 203      * Sign up a new user ready for confirmation.
 204      * Password is passed in plaintext.
 205      *
 206      * @param object $user new user object (with system magic quotes)
 207      * @param boolean $notify print notice with link and terminate
 208      */
 209     function user_signup($user, $notify=true) {
 210         //override when can signup
 211         error('user_signup method must be overriden if signup enabled');
 212     }
 213
 214     /**
 215      * Returns true if plugin allows confirming of new users.
 216      *
 217      * @return bool
 218      */
 219     function can_confirm() {
 220         //override if needed
 221         return false;
 222     }
 223
 224     /**
 225      * Confirm the new user as registered.
 226      *
 227      * @param string $username (with system magic quotes)
 228      * @param string $confirmsecret (with system magic quotes)
 229      */
 230     function user_confirm($username, $confirmsecret) {
 231         //override when can confirm
 232         error('user_confirm method must be overriden if confirm enabled');
 233     }
 234
 235     /**
 236      * Checks if user exists in external db
 237      *
 238      * @param string $username (with system magic quotes)
 239      * @return bool
 240      */
 241     function user_exists() {
 242         //override if needed
 243         return false;
 244     }
 245
 246     /**
 247      * return number of days to user password expires
 248      *
 249      * If userpassword does not expire it should return 0. If password is already expired
 250      * it should return negative value.
 251      *
 252      * @param mixed $username username (with system magic quotes)
 253      * @return integer
 254      */
 255     function password_expire($username) {
 256         return 0;
 257     }
 258     /**
 259      * Sync roles for this user - usually creator
 260      *
 261      * @param $user object user object (without system magic quotes)
 262      */
 263     function sync_roles($user) {
 264         //override if needed
 265     }
 266
 267     /**
 268      * Read user information from external database and returns it as array().
 269      * Function should return all information available. If you are saving
 270      * this information to moodle user-table you should honor syncronization flags
 271      *
 272      * @param string $username username (with system magic quotes)
 273      *
 274      * @return mixed array with no magic quotes or false on error
 275      */
 276     function get_userinfo($username) {
 277         //override if needed
 278         return array();
 279     }
 280
 281     /**
 282      * Prints a form for configuring this authentication plugin.
 283      *
 284      * This function is called from admin/auth.php, and outputs a full page with
 285      * a form for configuring this plugin.
 286      */
 287     function config_form($config, $err, $user_fields) {
 288         //override if needed
 289     }
 290
 291     /**
 292      * A chance to validate form data, and last chance to
 293      * do stuff before it is inserted in config_plugin
 294      * @param object object with submitted configuration settings (without system magic quotes)
 295      * @param array $err array of error messages
 296      */
 297      function validate_form(&$form, &$err) {
 298         //override if needed
 299     }
 300
 301     /**
 302      * Processes and stores configuration data for this authentication plugin.
 303      *
 304      * @param object object with submitted configuration settings (without system magic quotes)
 305      */
 306     function process_config($config) {
 307         //override if needed
 308         return true;
 309     }
 310
 311     /**
 312      * Hook for overriding behavior of login page.
 313      * This method is called from login/index.php page for all enabled auth plugins.
 314      */
 315     function loginpage_hook() {
 316         global $frm;  // can be used to override submitted login form
 317         global $user; // can be used to replace authenticate_user_login()
 318
 319         //override if needed
 320     }
 321
 322     /**
 323      * Post authentication hook.
 324      * This method is called from authenticate_user_login() for all enabled auth plugins.
 325      *
 326      * @param object $user user object, later used for $USER
 327      * @param string $username (with system magic quotes)
 328      * @param string $password plain text password (with system magic quotes)
 329      */
 330     function user_authenticated_hook(&$user, $username, $password) {
 331         //override if needed
 332     }
 333
 334     /**
 335      * Pre logout hook.
 336      * This method is called from require_logout() for all enabled auth plugins,
 337      */
 338     function prelogout_hook() {
 339         global $USER; // use $USER->auth to find the plugin used for login
 340
 341         //override if needed
 342     }
 343
 344     /**
 345      * Hook for overriding behavior of logout page.
 346      * This method is called from login/logout.php page for all enabled auth plugins.
 347      */
 348     function logoutpage_hook() {
 349         global $USER;     // use $USER->auth to find the plugin used for login
 350         global $redirect; // can be used to override redirect after logout
 351
 352         //override if needed
 353     }
 354
 355     /**
 356      * Return the properly translated human-friendly title of this auth plugin
 357      */
 358     function get_title() {
 359         return auth_get_plugin_title($this->authtype);
 360     }
 361
 362     /**
 363      *  Get the auth description (from core or own auth lang files)
 364      */
 365     function get_description() {
 366         $authdescription = get_string("auth_{$this->authtype}description", "auth");
 367         if ($authdescription == "[[auth_{$this->authtype}description]]") {
 368             $authdescription = get_string("auth_{$this->authtype}description", "auth_{$this->authtype}");
 369         }
 370         return $authdescription;
 371     }
 372
 373     /**
 374      * Returns whether or not the captcha element is enabled, and the admin settings fulfil its requirements.
 375      * @abstract Implement in child classes
 376      * @return bool
 377      */
 378     function is_captcha_enabled() {
 379         return false;
 380     }
 381
 382
 383 }
 384
 385 ?>