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