lib/authlib.php

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