[Summary view] [Print] [Text view]

   1  <?php  // $Id: authlib.php,v 1.8.2.6 2008/05/28 07:39:52 dongsheng Exp $
   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       * Updates the user's password. In previous versions of Moodle, the function
 135       * auth_user_update_password accepted a username as the first parameter. The
 136       * revised function expects a user object.
 137       *
 138       * @param  object  $user        User table object  (with system magic quotes)
 139       * @param  string  $newpassword Plaintext password (with system magic quotes)
 140       *
 141       * @return bool                  True on success
 142       */
 143      function user_update_password($user, $newpassword) {
 144          //override if needed
 145          return true;
 146      }
 147  
 148      /**
 149       * Called when the user record is updated.
 150       * Modifies user in external database. It takes olduser (before changes) and newuser (after changes)
 151       * conpares information saved modified information to external db.
 152       *
 153       * @param mixed $olduser     Userobject before modifications    (without system magic quotes)
 154       * @param mixed $newuser     Userobject new modified userobject (without system magic quotes)
 155       * @return boolean true if updated or update ignored; false if error
 156       *
 157       */
 158      function user_update($olduser, $newuser) {
 159          //override if needed
 160          return true;
 161      }
 162  
 163      /**
 164       * User delete requested - internal user record is mared as deleted already, username not present anymore.
 165       * Do any action in external database.
 166       * @param object $user       Userobject before delete    (without system magic quotes)
 167       */
 168      function user_delete($olduser) {
 169          //override if needed
 170          return;
 171      }
 172  
 173      /**
 174       * Returns true if plugin allows resetting of internal password.
 175       *
 176       * @return bool
 177       */
 178      function can_reset_password() {
 179          //override if needed
 180          return false;
 181      }
 182  
 183      /**
 184       * Returns true if plugin allows resetting of internal password.
 185       *
 186       * @return bool
 187       */
 188      function can_signup() {
 189          //override if needed
 190          return false;
 191      }
 192  
 193      /**
 194       * Sign up a new user ready for confirmation.
 195       * Password is passed in plaintext.
 196       *
 197       * @param object $user new user object (with system magic quotes)
 198       * @param boolean $notify print notice with link and terminate
 199       */
 200      function user_signup($user, $notify=true) {
 201          //override when can signup
 202          error('user_signup method must be overriden if signup enabled');
 203      }
 204  
 205      /**
 206       * Returns true if plugin allows confirming of new users.
 207       *
 208       * @return bool
 209       */
 210      function can_confirm() {
 211          //override if needed
 212          return false;
 213      }
 214  
 215      /**
 216       * Confirm the new user as registered.
 217       *
 218       * @param string $username (with system magic quotes)
 219       * @param string $confirmsecret (with system magic quotes)
 220       */
 221      function user_confirm($username, $confirmsecret) {
 222          //override when can confirm
 223          error('user_confirm method must be overriden if confirm enabled');
 224      }
 225  
 226      /**
 227       * Checks if user exists in external db
 228       *
 229       * @param string $username (with system magic quotes)
 230       * @return bool
 231       */
 232      function user_exists() {
 233          //override if needed
 234          return false;
 235      }
 236  
 237      /**
 238       * return number of days to user password expires
 239       *
 240       * If userpassword does not expire it should return 0. If password is already expired
 241       * it should return negative value.
 242       *
 243       * @param mixed $username username (with system magic quotes)
 244       * @return integer
 245       */
 246      function password_expire($username) {
 247          return 0;
 248      }
 249      /**
 250       * Sync roles for this user - usually creator
 251       *
 252       * @param $user object user object (without system magic quotes)
 253       */
 254      function sync_roles($user) {
 255          //override if needed
 256      }
 257  
 258      /**
 259       * Read user information from external database and returns it as array().
 260       * Function should return all information available. If you are saving
 261       * this information to moodle user-table you should honor syncronization flags
 262       *
 263       * @param string $username username (with system magic quotes)
 264       *
 265       * @return mixed array with no magic quotes or false on error
 266       */
 267      function get_userinfo($username) {
 268          //override if needed
 269          return array();
 270      }
 271  
 272      /**
 273       * Prints a form for configuring this authentication plugin.
 274       *
 275       * This function is called from admin/auth.php, and outputs a full page with
 276       * a form for configuring this plugin.
 277       */
 278      function config_form($config, $err, $user_fields) {
 279          //override if needed
 280      }
 281  
 282      /**
 283       * A chance to validate form data, and last chance to
 284       * do stuff before it is inserted in config_plugin
 285       * @param object object with submitted configuration settings (without system magic quotes)
 286       * @param array $err array of error messages
 287       */
 288       function validate_form(&$form, &$err) {
 289          //override if needed
 290      }
 291  
 292      /**
 293       * Processes and stores configuration data for this authentication plugin.
 294       *
 295       * @param object object with submitted configuration settings (without system magic quotes)
 296       */
 297      function process_config($config) {
 298          //override if needed
 299          return true;
 300      }
 301  
 302      /**
 303       * Hook for overriding behavior of login page.
 304       * This method is called from login/index.php page for all enabled auth plugins.
 305       */
 306      function loginpage_hook() {
 307          global $frm;  // can be used to override submitted login form
 308          global $user; // can be used to replace authenticate_user_login()
 309  
 310          //override if needed
 311      }
 312  
 313      /**
 314       * Post authentication hook.
 315       * This method is called from authenticate_user_login() for all enabled auth plugins.
 316       *
 317       * @param object $user user object, later used for $USER
 318       * @param string $username (with system magic quotes)
 319       * @param string $password plain text password (with system magic quotes)
 320       */
 321      function user_authenticated_hook(&$user, $username, $password) {
 322          //override if needed
 323      }
 324  
 325      /**
 326       * Pre logout hook.
 327       * This method is called from require_logout() for all enabled auth plugins,
 328       */
 329      function prelogout_hook() {
 330          global $USER; // use $USER->auth to find the plugin used for login
 331  
 332          //override if needed
 333      }
 334  
 335      /**
 336       * Hook for overriding behavior of logout page.
 337       * This method is called from login/logout.php page for all enabled auth plugins.
 338       */
 339      function logoutpage_hook() {
 340          global $USER;     // use $USER->auth to find the plugin used for login
 341          global $redirect; // can be used to override redirect after logout
 342  
 343          //override if needed
 344      }
 345  
 346      /**
 347       * Return the properly translated human-friendly title of this auth plugin
 348       */
 349      function get_title() {
 350          $authtitle = get_string("auth_{$this->authtype}title", "auth");
 351          if ($authtitle == "[[auth_{$this->authtype}title]]") {
 352              $authtitle = get_string("auth_{$this->authtype}title", "auth_{$this->authtype}");
 353          }
 354          return $authtitle;
 355      }
 356  
 357      /**
 358       *  Get the auth description (from core or own auth lang files)
 359       */
 360      function get_description() {
 361          $authdescription = get_string("auth_{$this->authtype}description", "auth");
 362          if ($authdescription == "[[auth_{$this->authtype}description]]") {
 363              $authdescription = get_string("auth_{$this->authtype}description", "auth_{$this->authtype}");
 364          }
 365          return $authdescription;
 366      }
 367      
 368      /**
 369       * Returns whether or not the captcha element is enabled, and the admin settings fulfil its requirements.
 370       * @abstract Implement in child classes
 371       * @return bool
 372       */
 373      function is_captcha_enabled() {
 374          return false;
 375      }
 376  
 377  
 378  }
 379  
 380  ?>