lib/authlib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * Multiple plugin authentication Support library
  20  *
  21  * 2006-08-28  File created, AUTH return values defined.
  22  *
  23  * @package    core
  24  * @subpackage auth
  25  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
  26  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  27  */
  28
  29 defined('MOODLE_INTERNAL') || die();
  30
  31 /**
  32  * Returned when the login was successful.
  33  */
  34 define('AUTH_OK',     0);
  35
  36 /**
  37  * Returned when the login was unsuccessful.
  38  */
  39 define('AUTH_FAIL',   1);
  40
  41 /**
  42  * Returned when the login was denied (a reason for AUTH_FAIL).
  43  */
  44 define('AUTH_DENIED', 2);
  45
  46 /**
  47  * Returned when some error occurred (a reason for AUTH_FAIL).
  48  */
  49 define('AUTH_ERROR',  4);
  50
  51 /**
  52  * Authentication - error codes for user confirm
  53  */
  54 define('AUTH_CONFIRM_FAIL', 0);
  55 define('AUTH_CONFIRM_OK', 1);
  56 define('AUTH_CONFIRM_ALREADY', 2);
  57 define('AUTH_CONFIRM_ERROR', 3);
  58
  59 # MDL-14055
  60 define('AUTH_REMOVEUSER_KEEP', 0);
  61 define('AUTH_REMOVEUSER_SUSPEND', 1);
  62 define('AUTH_REMOVEUSER_FULLDELETE', 2);
  63
  64 /**
  65  * Abstract authentication plugin.
  66  *
  67  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  68  * @package moodlecore
  69  */
  70 class auth_plugin_base {
  71
  72     /**
  73      * The configuration details for the plugin.
  74      * @var object
  75      */
  76     var $config;
  77
  78     /**
  79      * Authentication plugin type - the same as db field.
  80      * @var string
  81      */
  82     var $authtype;
  83     /*
  84      * The fields we can lock and update from/to external authentication backends
  85      * @var array
  86      */
  87     var $userfields = array(
  88         'firstname',
  89         'lastname',
  90         'email',
  91         'city',
  92         'country',
  93         'lang',
  94         'description',
  95         'url',
  96         'idnumber',
  97         'institution',
  98         'department',
  99         'phone1',
 100         'phone2',
 101         'address'
 102     );
 103
 104     /**
 105
 106      * This is the primary method that is used by the authenticate_user_login()
 107      * function in moodlelib.php.
 108      *
 109      * This method should return a boolean indicating
 110      * whether or not the username and password authenticate successfully.
 111      *
 112      * Returns true if the username and password work and false if they are
 113      * wrong or don't exist.
 114      *
 115      * @param string $username The username (with system magic quotes)
 116      * @param string $password The password (with system magic quotes)
 117      *
 118      * @return bool Authentication success or failure.
 119      */
 120     function user_login($username, $password) {
 121         print_error('mustbeoveride', 'debug', '', 'user_login()' );
 122     }
 123
 124     /**
 125      * Returns true if this authentication plugin can change the users'
 126      * password.
 127      *
 128      * @return bool
 129      */
 130     function can_change_password() {
 131         //override if needed
 132         return false;
 133     }
 134
 135     /**
 136      * Returns the URL for changing the users' passwords, or empty if the default
 137      * URL can be used.
 138      *
 139      * This method is used if can_change_password() returns true.
 140      * This method is called only when user is logged in, it may use global $USER.
 141      *
 142      * @return moodle_url url of the profile page or null if standard used
 143      */
 144     function change_password_url() {
 145         //override if needed
 146         return null;
 147     }
 148
 149     /**
 150      * Returns true if this authentication plugin can edit the users'
 151      * profile.
 152      *
 153      * @return bool
 154      */
 155     function can_edit_profile() {
 156         //override if needed
 157         return true;
 158     }
 159
 160     /**
 161      * Returns the URL for editing the users' profile, or empty if the default
 162      * URL can be used.
 163      *
 164      * This method is used if can_edit_profile() returns true.
 165      * This method is called only when user is logged in, it may use global $USER.
 166      *
 167      * @return moodle_url url of the profile page or null if standard used
 168      */
 169     function edit_profile_url() {
 170         //override if needed
 171         return null;
 172     }
 173
 174     /**
 175      * Returns true if this authentication plugin is "internal".
 176      *
 177      * Internal plugins use password hashes from Moodle user table for authentication.
 178      *
 179      * @return bool
 180      */
 181     function is_internal() {
 182         //override if needed
 183         return true;
 184     }
 185
 186     /**
 187      * Indicates if password hashes should be stored in local moodle database.
 188      * @return bool true means md5 password hash stored in user table, false means flag 'not_cached' stored there instead
 189      */
 190     function prevent_local_passwords() {
 191         return !$this->is_internal();
 192     }
 193
 194     /**
 195      * Indicates if moodle should automatically update internal user
 196      * records with data from external sources using the information
 197      * from get_userinfo() method.
 198      *
 199      * @return bool true means automatically copy data from ext to user table
 200      */
 201     function is_synchronised_with_external() {
 202         return !$this->is_internal();
 203     }
 204
 205     /**
 206      * Updates the user's password.
 207      *
 208      * In previous versions of Moodle, the function
 209      * auth_user_update_password accepted a username as the first parameter. The
 210      * revised function expects a user object.
 211      *
 212      * @param  object  $user        User table object
 213      * @param  string  $newpassword Plaintext password
 214      *
 215      * @return bool                  True on success
 216      */
 217     function user_update_password($user, $newpassword) {
 218         //override if needed
 219         return true;
 220     }
 221
 222     /**
 223      * Called when the user record is updated.
 224      * Modifies user in external database. It takes olduser (before changes) and newuser (after changes)
 225      * compares information saved modified information to external db.
 226      *
 227      * @param mixed $olduser     Userobject before modifications    (without system magic quotes)
 228      * @param mixed $newuser     Userobject new modified userobject (without system magic quotes)
 229      * @return boolean true if updated or update ignored; false if error
 230      *
 231      */
 232     function user_update($olduser, $newuser) {
 233         //override if needed
 234         return true;
 235     }
 236
 237     /**
 238      * User delete requested - internal user record is mared as deleted already, username not present anymore.
 239      *
 240      * Do any action in external database.
 241      *
 242      * @param object $user       Userobject before delete    (without system magic quotes)
 243      * @return void
 244      */
 245     function user_delete($olduser) {
 246         //override if needed
 247         return;
 248     }
 249
 250     /**
 251      * Returns true if plugin allows resetting of internal password.
 252      *
 253      * @return bool
 254      */
 255     function can_reset_password() {
 256         //override if needed
 257         return false;
 258     }
 259
 260     /**
 261      * Returns true if plugin allows resetting of internal password.
 262      *
 263      * @return bool
 264      */
 265     function can_signup() {
 266         //override if needed
 267         return false;
 268     }
 269
 270     /**
 271      * Sign up a new user ready for confirmation.
 272      * Password is passed in plaintext.
 273      *
 274      * @param object $user new user object
 275      * @param boolean $notify print notice with link and terminate
 276      */
 277     function user_signup($user, $notify=true) {
 278         //override when can signup
 279         print_error('mustbeoveride', 'debug', '', 'user_signup()' );
 280     }
 281
 282     /**
 283      * Return a form to capture user details for account creation.
 284      * This is used in /login/signup.php.
 285      * @return moodle_form A form which edits a record from the user table.
 286      */
 287     function signup_form() {
 288         global $CFG;
 289
 290         require_once($CFG->dirroot.'/login/signup_form.php');
 291         return new login_signup_form(null, null, 'post', '', array('autocomplete'=>'on'));
 292     }
 293
 294     /**
 295      * Returns true if plugin allows confirming of new users.
 296      *
 297      * @return bool
 298      */
 299     function can_confirm() {
 300         //override if needed
 301         return false;
 302     }
 303
 304     /**
 305      * Confirm the new user as registered.
 306      *
 307      * @param string $username
 308      * @param string $confirmsecret
 309      */
 310     function user_confirm($username, $confirmsecret) {
 311         //override when can confirm
 312         print_error('mustbeoveride', 'debug', '', 'user_confirm()' );
 313     }
 314
 315     /**
 316      * Checks if user exists in external db
 317      *
 318      * @param string $username (with system magic quotes)
 319      * @return bool
 320      */
 321     function user_exists($username) {
 322         //override if needed
 323         return false;
 324     }
 325
 326     /**
 327      * return number of days to user password expires
 328      *
 329      * If userpassword does not expire it should return 0. If password is already expired
 330      * it should return negative value.
 331      *
 332      * @param mixed $username username (with system magic quotes)
 333      * @return integer
 334      */
 335     function password_expire($username) {
 336         return 0;
 337     }
 338     /**
 339      * Sync roles for this user - usually creator
 340      *
 341      * @param $user object user object (without system magic quotes)
 342      */
 343     function sync_roles($user) {
 344         //override if needed
 345     }
 346
 347     /**
 348      * Read user information from external database and returns it as array().
 349      * Function should return all information available. If you are saving
 350      * this information to moodle user-table you should honour synchronisation flags
 351      *
 352      * @param string $username username
 353      *
 354      * @return mixed array with no magic quotes or false on error
 355      */
 356     function get_userinfo($username) {
 357         //override if needed
 358         return array();
 359     }
 360
 361     /**
 362      * Prints a form for configuring this authentication plugin.
 363      *
 364      * This function is called from admin/auth.php, and outputs a full page with
 365      * a form for configuring this plugin.
 366      *
 367      * @param object $config
 368      * @param object $err
 369      * @param array $user_fields
 370      */
 371     function config_form($config, $err, $user_fields) {
 372         //override if needed
 373     }
 374
 375     /**
 376      * A chance to validate form data, and last chance to
 377      * do stuff before it is inserted in config_plugin
 378      * @param object object with submitted configuration settings (without system magic quotes)
 379      * @param array $err array of error messages
 380      */
 381      function validate_form($form, &$err) {
 382         //override if needed
 383     }
 384
 385     /**
 386      * Processes and stores configuration data for this authentication plugin.
 387      *
 388      * @param object object with submitted configuration settings (without system magic quotes)
 389      */
 390     function process_config($config) {
 391         //override if needed
 392         return true;
 393     }
 394
 395     /**
 396      * Hook for overriding behaviour of login page.
 397      * This method is called from login/index.php page for all enabled auth plugins.
 398      *
 399      * @global object
 400      * @global object
 401      */
 402     function loginpage_hook() {
 403         global $frm;  // can be used to override submitted login form
 404         global $user; // can be used to replace authenticate_user_login()
 405
 406         //override if needed
 407     }
 408
 409     /**
 410      * Post authentication hook.
 411      * This method is called from authenticate_user_login() for all enabled auth plugins.
 412      *
 413      * @param object $user user object, later used for $USER
 414      * @param string $username (with system magic quotes)
 415      * @param string $password plain text password (with system magic quotes)
 416      */
 417     function user_authenticated_hook(&$user, $username, $password) {
 418         //override if needed
 419     }
 420
 421     /**
 422      * Pre logout hook.
 423      * This method is called from require_logout() for all enabled auth plugins,
 424      *
 425      * @global object
 426      */
 427     function prelogout_hook() {
 428         global $USER; // use $USER->auth to find the plugin used for login
 429
 430         //override if needed
 431     }
 432
 433     /**
 434      * Hook for overriding behaviour of logout page.
 435      * This method is called from login/logout.php page for all enabled auth plugins.
 436      *
 437      * @global object
 438      * @global string
 439      */
 440     function logoutpage_hook() {
 441         global $USER;     // use $USER->auth to find the plugin used for login
 442         global $redirect; // can be used to override redirect after logout
 443
 444         //override if needed
 445     }
 446
 447     /**
 448      * Hook called before timing out of database session.
 449      * This is useful for SSO and MNET.
 450      *
 451      * @param object $user
 452      * @param string $sid session id
 453      * @param int $timecreated start of session
 454      * @param int $timemodified user last seen
 455      * @return bool true means do not timeout session yet
 456      */
 457     function ignore_timeout_hook($user, $sid, $timecreated, $timemodified) {
 458         return false;
 459     }
 460
 461     /**
 462      * Return the properly translated human-friendly title of this auth plugin
 463      *
 464      * @todo Document this function
 465      */
 466     function get_title() {
 467         return get_string('pluginname', "auth_{$this->authtype}");
 468     }
 469
 470     /**
 471      * Get the auth description (from core or own auth lang files)
 472      *
 473      * @return string The description
 474      */
 475     function get_description() {
 476         $authdescription = get_string("auth_{$this->authtype}description", "auth_{$this->authtype}");
 477         return $authdescription;
 478     }
 479
 480     /**
 481      * Returns whether or not the captcha element is enabled, and the admin settings fulfil its requirements.
 482      *
 483      * @abstract Implement in child classes
 484      * @return bool
 485      */
 486     function is_captcha_enabled() {
 487         return false;
 488     }
 489
 490     /**
 491      * Returns a list of potential IdPs that this authentication plugin supports.
 492      * This is used to provide links on the login page.
 493      *
 494      * @param string $wantsurl the relative url fragment the user wants to get to.  You can use this to compose a returnurl, for example
 495      *
 496      * @return array like:
 497      *              array(
 498      *                  array(
 499      *                      'url' => 'http://someurl',
 500      *                      'icon' => new pix_icon(...),
 501      *                      'name' => get_string('somename', 'auth_yourplugin'),
 502      *                 ),
 503      *             )
 504      */
 505     function loginpage_idp_list($wantsurl) {
 506         return array();
 507     }
 508
 509 }