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 /** Login attempt successful. */
  65 define('AUTH_LOGIN_OK', 0);
  66
  67 /** Can not login because user does not exist. */
  68 define('AUTH_LOGIN_NOUSER', 1);
  69
  70 /** Can not login because user is suspended. */
  71 define('AUTH_LOGIN_SUSPENDED', 2);
  72
  73 /** Can not login, most probably password did not match. */
  74 define('AUTH_LOGIN_FAILED', 3);
  75
  76 /** Can not login because user is locked out. */
  77 define('AUTH_LOGIN_LOCKOUT', 4);
  78
  79
  80 /**
  81  * Abstract authentication plugin.
  82  *
  83  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  84  * @package moodlecore
  85  */
  86 class auth_plugin_base {
  87
  88     /**
  89      * The configuration details for the plugin.
  90      * @var object
  91      */
  92     var $config;
  93
  94     /**
  95      * Authentication plugin type - the same as db field.
  96      * @var string
  97      */
  98     var $authtype;
  99     /*
 100      * The fields we can lock and update from/to external authentication backends
 101      * @var array
 102      */
 103     var $userfields = array(
 104         'firstname',
 105         'lastname',
 106         'email',
 107         'city',
 108         'country',
 109         'lang',
 110         'description',
 111         'url',
 112         'idnumber',
 113         'institution',
 114         'department',
 115         'phone1',
 116         'phone2',
 117         'address'
 118     );
 119
 120     /**
 121      * Moodle custom fields to sync with.
 122      * @var array()
 123      */
 124     var $customfields = null;
 125
 126     /**
 127
 128      * This is the primary method that is used by the authenticate_user_login()
 129      * function in moodlelib.php.
 130      *
 131      * This method should return a boolean indicating
 132      * whether or not the username and password authenticate successfully.
 133      *
 134      * Returns true if the username and password work and false if they are
 135      * wrong or don't exist.
 136      *
 137      * @param string $username The username (with system magic quotes)
 138      * @param string $password The password (with system magic quotes)
 139      *
 140      * @return bool Authentication success or failure.
 141      */
 142     function user_login($username, $password) {
 143         print_error('mustbeoveride', 'debug', '', 'user_login()' );
 144     }
 145
 146     /**
 147      * Returns true if this authentication plugin can change the users'
 148      * password.
 149      *
 150      * @return bool
 151      */
 152     function can_change_password() {
 153         //override if needed
 154         return false;
 155     }
 156
 157     /**
 158      * Returns the URL for changing the users' passwords, or empty if the default
 159      * URL can be used.
 160      *
 161      * This method is used if can_change_password() returns true.
 162      * This method is called only when user is logged in, it may use global $USER.
 163      *
 164      * @return moodle_url url of the profile page or null if standard used
 165      */
 166     function change_password_url() {
 167         //override if needed
 168         return null;
 169     }
 170
 171     /**
 172      * Returns true if this authentication plugin can edit the users'
 173      * profile.
 174      *
 175      * @return bool
 176      */
 177     function can_edit_profile() {
 178         //override if needed
 179         return true;
 180     }
 181
 182     /**
 183      * Returns the URL for editing the users' profile, or empty if the default
 184      * URL can be used.
 185      *
 186      * This method is used if can_edit_profile() returns true.
 187      * This method is called only when user is logged in, it may use global $USER.
 188      *
 189      * @return moodle_url url of the profile page or null if standard used
 190      */
 191     function edit_profile_url() {
 192         //override if needed
 193         return null;
 194     }
 195
 196     /**
 197      * Returns true if this authentication plugin is "internal".
 198      *
 199      * Internal plugins use password hashes from Moodle user table for authentication.
 200      *
 201      * @return bool
 202      */
 203     function is_internal() {
 204         //override if needed
 205         return true;
 206     }
 207
 208     /**
 209      * Indicates if password hashes should be stored in local moodle database.
 210      * @return bool true means md5 password hash stored in user table, false means flag 'not_cached' stored there instead
 211      */
 212     function prevent_local_passwords() {
 213         return !$this->is_internal();
 214     }
 215
 216     /**
 217      * Indicates if moodle should automatically update internal user
 218      * records with data from external sources using the information
 219      * from get_userinfo() method.
 220      *
 221      * @return bool true means automatically copy data from ext to user table
 222      */
 223     function is_synchronised_with_external() {
 224         return !$this->is_internal();
 225     }
 226
 227     /**
 228      * Updates the user's password.
 229      *
 230      * In previous versions of Moodle, the function
 231      * auth_user_update_password accepted a username as the first parameter. The
 232      * revised function expects a user object.
 233      *
 234      * @param  object  $user        User table object
 235      * @param  string  $newpassword Plaintext password
 236      *
 237      * @return bool                  True on success
 238      */
 239     function user_update_password($user, $newpassword) {
 240         //override if needed
 241         return true;
 242     }
 243
 244     /**
 245      * Called when the user record is updated.
 246      * Modifies user in external database. It takes olduser (before changes) and newuser (after changes)
 247      * compares information saved modified information to external db.
 248      *
 249      * @param mixed $olduser     Userobject before modifications    (without system magic quotes)
 250      * @param mixed $newuser     Userobject new modified userobject (without system magic quotes)
 251      * @return boolean true if updated or update ignored; false if error
 252      *
 253      */
 254     function user_update($olduser, $newuser) {
 255         //override if needed
 256         return true;
 257     }
 258
 259     /**
 260      * User delete requested - internal user record is mared as deleted already, username not present anymore.
 261      *
 262      * Do any action in external database.
 263      *
 264      * @param object $user       Userobject before delete    (without system magic quotes)
 265      * @return void
 266      */
 267     function user_delete($olduser) {
 268         //override if needed
 269         return;
 270     }
 271
 272     /**
 273      * Returns true if plugin allows resetting of internal password.
 274      *
 275      * @return bool
 276      */
 277     function can_reset_password() {
 278         //override if needed
 279         return false;
 280     }
 281
 282     /**
 283      * Returns true if plugin allows resetting of internal password.
 284      *
 285      * @return bool
 286      */
 287     function can_signup() {
 288         //override if needed
 289         return false;
 290     }
 291
 292     /**
 293      * Sign up a new user ready for confirmation.
 294      * Password is passed in plaintext.
 295      *
 296      * @param object $user new user object
 297      * @param boolean $notify print notice with link and terminate
 298      */
 299     function user_signup($user, $notify=true) {
 300         //override when can signup
 301         print_error('mustbeoveride', 'debug', '', 'user_signup()' );
 302     }
 303
 304     /**
 305      * Return a form to capture user details for account creation.
 306      * This is used in /login/signup.php.
 307      * @return moodle_form A form which edits a record from the user table.
 308      */
 309     function signup_form() {
 310         global $CFG;
 311
 312         require_once($CFG->dirroot.'/login/signup_form.php');
 313         return new login_signup_form(null, null, 'post', '', array('autocomplete'=>'on'));
 314     }
 315
 316     /**
 317      * Returns true if plugin allows confirming of new users.
 318      *
 319      * @return bool
 320      */
 321     function can_confirm() {
 322         //override if needed
 323         return false;
 324     }
 325
 326     /**
 327      * Confirm the new user as registered.
 328      *
 329      * @param string $username
 330      * @param string $confirmsecret
 331      */
 332     function user_confirm($username, $confirmsecret) {
 333         //override when can confirm
 334         print_error('mustbeoveride', 'debug', '', 'user_confirm()' );
 335     }
 336
 337     /**
 338      * Checks if user exists in external db
 339      *
 340      * @param string $username (with system magic quotes)
 341      * @return bool
 342      */
 343     function user_exists($username) {
 344         //override if needed
 345         return false;
 346     }
 347
 348     /**
 349      * return number of days to user password expires
 350      *
 351      * If userpassword does not expire it should return 0. If password is already expired
 352      * it should return negative value.
 353      *
 354      * @param mixed $username username (with system magic quotes)
 355      * @return integer
 356      */
 357     function password_expire($username) {
 358         return 0;
 359     }
 360     /**
 361      * Sync roles for this user - usually creator
 362      *
 363      * @param $user object user object (without system magic quotes)
 364      */
 365     function sync_roles($user) {
 366         //override if needed
 367     }
 368
 369     /**
 370      * Read user information from external database and returns it as array().
 371      * Function should return all information available. If you are saving
 372      * this information to moodle user-table you should honour synchronisation flags
 373      *
 374      * @param string $username username
 375      *
 376      * @return mixed array with no magic quotes or false on error
 377      */
 378     function get_userinfo($username) {
 379         //override if needed
 380         return array();
 381     }
 382
 383     /**
 384      * Prints a form for configuring this authentication plugin.
 385      *
 386      * This function is called from admin/auth.php, and outputs a full page with
 387      * a form for configuring this plugin.
 388      *
 389      * @param object $config
 390      * @param object $err
 391      * @param array $user_fields
 392      */
 393     function config_form($config, $err, $user_fields) {
 394         //override if needed
 395     }
 396
 397     /**
 398      * A chance to validate form data, and last chance to
 399      * do stuff before it is inserted in config_plugin
 400      * @param object object with submitted configuration settings (without system magic quotes)
 401      * @param array $err array of error messages
 402      */
 403      function validate_form($form, &$err) {
 404         //override if needed
 405     }
 406
 407     /**
 408      * Processes and stores configuration data for this authentication plugin.
 409      *
 410      * @param object object with submitted configuration settings (without system magic quotes)
 411      */
 412     function process_config($config) {
 413         //override if needed
 414         return true;
 415     }
 416
 417     /**
 418      * Hook for overriding behaviour of login page.
 419      * This method is called from login/index.php page for all enabled auth plugins.
 420      *
 421      * @global object
 422      * @global object
 423      */
 424     function loginpage_hook() {
 425         global $frm;  // can be used to override submitted login form
 426         global $user; // can be used to replace authenticate_user_login()
 427
 428         //override if needed
 429     }
 430
 431     /**
 432      * Post authentication hook.
 433      * This method is called from authenticate_user_login() for all enabled auth plugins.
 434      *
 435      * @param object $user user object, later used for $USER
 436      * @param string $username (with system magic quotes)
 437      * @param string $password plain text password (with system magic quotes)
 438      */
 439     function user_authenticated_hook(&$user, $username, $password) {
 440         //override if needed
 441     }
 442
 443     /**
 444      * Pre logout hook.
 445      * This method is called from require_logout() for all enabled auth plugins,
 446      *
 447      * @global object
 448      */
 449     function prelogout_hook() {
 450         global $USER; // use $USER->auth to find the plugin used for login
 451
 452         //override if needed
 453     }
 454
 455     /**
 456      * Hook for overriding behaviour of logout page.
 457      * This method is called from login/logout.php page for all enabled auth plugins.
 458      *
 459      * @global object
 460      * @global string
 461      */
 462     function logoutpage_hook() {
 463         global $USER;     // use $USER->auth to find the plugin used for login
 464         global $redirect; // can be used to override redirect after logout
 465
 466         //override if needed
 467     }
 468
 469     /**
 470      * Hook called before timing out of database session.
 471      * This is useful for SSO and MNET.
 472      *
 473      * @param object $user
 474      * @param string $sid session id
 475      * @param int $timecreated start of session
 476      * @param int $timemodified user last seen
 477      * @return bool true means do not timeout session yet
 478      */
 479     function ignore_timeout_hook($user, $sid, $timecreated, $timemodified) {
 480         return false;
 481     }
 482
 483     /**
 484      * Return the properly translated human-friendly title of this auth plugin
 485      *
 486      * @todo Document this function
 487      */
 488     function get_title() {
 489         return get_string('pluginname', "auth_{$this->authtype}");
 490     }
 491
 492     /**
 493      * Get the auth description (from core or own auth lang files)
 494      *
 495      * @return string The description
 496      */
 497     function get_description() {
 498         $authdescription = get_string("auth_{$this->authtype}description", "auth_{$this->authtype}");
 499         return $authdescription;
 500     }
 501
 502     /**
 503      * Returns whether or not the captcha element is enabled, and the admin settings fulfil its requirements.
 504      *
 505      * @abstract Implement in child classes
 506      * @return bool
 507      */
 508     function is_captcha_enabled() {
 509         return false;
 510     }
 511
 512     /**
 513      * Returns a list of potential IdPs that this authentication plugin supports.
 514      * This is used to provide links on the login page.
 515      *
 516      * @param string $wantsurl the relative url fragment the user wants to get to.  You can use this to compose a returnurl, for example
 517      *
 518      * @return array like:
 519      *              array(
 520      *                  array(
 521      *                      'url' => 'http://someurl',
 522      *                      'icon' => new pix_icon(...),
 523      *                      'name' => get_string('somename', 'auth_yourplugin'),
 524      *                 ),
 525      *             )
 526      */
 527     function loginpage_idp_list($wantsurl) {
 528         return array();
 529     }
 530
 531     /**
 532      * Return custom user profile fields.
 533      *
 534      * @return array list of custom fields.
 535      */
 536     public function get_custom_user_profile_fields() {
 537         global $DB;
 538         // If already retrieved then return.
 539         if (!is_null($this->customfields)) {
 540             return $this->customfields;
 541         }
 542
 543         $this->customfields = array();
 544         if ($proffields = $DB->get_records('user_info_field')) {
 545             foreach ($proffields as $proffield) {
 546                 $this->customfields[] = 'profile_field_'.$proffield->shortname;
 547             }
 548         }
 549         unset($proffields);
 550
 551         return $this->customfields;
 552     }
 553
 554 }
 555
 556 /**
 557  * Verify if user is locked out.
 558  *
 559  * @param stdClass $user
 560  * @return bool true if user locked out
 561  */
 562 function login_is_lockedout($user) {
 563     global $CFG;
 564
 565     if ($user->mnethostid != $CFG->mnet_localhost_id) {
 566         return false;
 567     }
 568     if (isguestuser($user)) {
 569         return false;
 570     }
 571
 572     if (empty($CFG->lockoutthreshold)) {
 573         // Lockout not enabled.
 574         return false;
 575     }
 576
 577     if (get_user_preferences('login_lockout_ignored', 0, $user)) {
 578         // This preference may be used for accounts that must not be locked out.
 579         return false;
 580     }
 581
 582     $locked = get_user_preferences('login_lockout', 0, $user);
 583     if (!$locked) {
 584         return false;
 585     }
 586
 587     if (empty($CFG->lockoutduration)) {
 588         // Locked out forever.
 589         return true;
 590     }
 591
 592     if (time() - $locked < $CFG->lockoutduration) {
 593         return true;
 594     }
 595
 596     login_unlock_account($user);
 597
 598     return false;
 599 }
 600
 601 /**
 602  * To be called after valid user login.
 603  * @param stdClass $user
 604  */
 605 function login_attempt_valid($user) {
 606     global $CFG;
 607
 608     if ($user->mnethostid != $CFG->mnet_localhost_id) {
 609         return;
 610     }
 611     if (isguestuser($user)) {
 612         return;
 613     }
 614
 615     // Always unlock here, there might be some race conditions or leftovers when switching threshold.
 616     login_unlock_account($user);
 617 }
 618
 619 /**
 620  * To be called after failed user login.
 621  * @param stdClass $user
 622  */
 623 function login_attempt_failed($user) {
 624     global $CFG;
 625
 626     if ($user->mnethostid != $CFG->mnet_localhost_id) {
 627         return;
 628     }
 629     if (isguestuser($user)) {
 630         return;
 631     }
 632
 633     if (empty($CFG->lockoutthreshold)) {
 634         // No threshold means no lockout.
 635         // Always unlock here, there might be some race conditions or leftovers when switching threshold.
 636         login_unlock_account($user);
 637         return;
 638     }
 639
 640     $count = get_user_preferences('login_failed_count', 0, $user);
 641     $last = get_user_preferences('login_failed_last', 0, $user);
 642
 643     if (!empty($CFG->lockoutwindow) and time() - $last > $CFG->lockoutwindow) {
 644         $count = 0;
 645     }
 646
 647     $count = $count+1;
 648
 649     set_user_preference('login_failed_count', $count, $user);
 650     set_user_preference('login_failed_last', time(), $user);
 651
 652     if ($count >= $CFG->lockoutthreshold) {
 653         login_lock_account($user);
 654     }
 655 }
 656
 657 /**
 658  * Lockout user and send notification email.
 659  *
 660  * @param stdClass $user
 661  */
 662 function login_lock_account($user) {
 663     global $CFG, $SESSION;
 664
 665     if ($user->mnethostid != $CFG->mnet_localhost_id) {
 666         return;
 667     }
 668     if (isguestuser($user)) {
 669         return;
 670     }
 671
 672     if (get_user_preferences('login_lockout_ignored', 0, $user)) {
 673         // This user can not be locked out.
 674         return;
 675     }
 676
 677     $alreadylockedout = get_user_preferences('login_lockout', 0, $user);
 678
 679     set_user_preference('login_lockout', time(), $user);
 680
 681     if ($alreadylockedout == 0) {
 682         $secret = random_string(15);
 683         set_user_preference('login_lockout_secret', $secret, $user);
 684
 685         // Some nasty hackery to get strings and dates localised for target user.
 686         $sessionlang = isset($SESSION->lang) ? $SESSION->lang : null;
 687         if (get_string_manager()->translation_exists($user->lang, false)) {
 688             $SESSION->lang = $user->lang;
 689             moodle_setlocale();
 690         }
 691
 692         $site = get_site();
 693         $supportuser = generate_email_supportuser();
 694
 695         $data = new stdClass();
 696         $data->firstname = $user->firstname;
 697         $data->lastname  = $user->lastname;
 698         $data->username  = $user->username;
 699         $data->sitename  = format_string($site->fullname);
 700         $data->link      = $CFG->wwwroot.'/login/unlock_account.php?u='.$user->id.'&s='.$secret;
 701         $data->admin     = generate_email_signoff();
 702
 703         $message = get_string('lockoutemailbody', 'admin', $data);
 704         $subject = get_string('lockoutemailsubject', 'admin', format_string($site->fullname));
 705
 706         if ($message) {
 707             // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
 708             email_to_user($user, $supportuser, $subject, $message);
 709         }
 710
 711         if ($SESSION->lang !== $sessionlang) {
 712             $SESSION->lang = $sessionlang;
 713             moodle_setlocale();
 714         }
 715     }
 716 }
 717
 718 /**
 719  * Unlock user account and reset timers.
 720  *
 721  * @param stdClass $user
 722  */
 723 function login_unlock_account($user) {
 724     unset_user_preference('login_lockout', $user);
 725     unset_user_preference('login_failed_count', $user);
 726     unset_user_preference('login_failed_last', $user);
 727
 728     // Note: do not clear the lockout secret because user might click on the link repeatedly.
 729 }