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