9b9c9b4dae3bb70a6391671f763a0a2ee4257790
[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    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  */
29 defined('MOODLE_INTERNAL') || die();
31 /**
32  * Returned when the login was successful.
33  */
34 define('AUTH_OK',     0);
36 /**
37  * Returned when the login was unsuccessful.
38  */
39 define('AUTH_FAIL',   1);
41 /**
42  * Returned when the login was denied (a reason for AUTH_FAIL).
43  */
44 define('AUTH_DENIED', 2);
46 /**
47  * Returned when some error occurred (a reason for AUTH_FAIL).
48  */
49 define('AUTH_ERROR',  4);
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);
59 # MDL-14055
60 define('AUTH_REMOVEUSER_KEEP', 0);
61 define('AUTH_REMOVEUSER_SUSPEND', 1);
62 define('AUTH_REMOVEUSER_FULLDELETE', 2);
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 {
72     /**
73      * The configuration details for the plugin.
74      * @var object
75      */
76     var $config;
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     );
104     /**
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     }
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     }
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     }
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     }
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     }
174     /**
175      * Returns true if this authentication plugin is "internal" (which means that
176      * Moodle stores the users' passwords and other details in the local Moodle
177      * database).
178      *
179      * @return bool
180      */
181     function is_internal() {
182         //override if needed
183         return true;
184     }
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         // NOTE: this will be changed to true in 2.0
192         return false;
193     }
195     /**
196      * Updates the user's password.
197      *
198      * In previous versions of Moodle, the function
199      * auth_user_update_password accepted a username as the first parameter. The
200      * revised function expects a user object.
201      *
202      * @param  object  $user        User table object
203      * @param  string  $newpassword Plaintext password
204      *
205      * @return bool                  True on success
206      */
207     function user_update_password($user, $newpassword) {
208         //override if needed
209         return true;
210     }
212     /**
213      * Called when the user record is updated.
214      * Modifies user in external database. It takes olduser (before changes) and newuser (after changes)
215      * compares information saved modified information to external db.
216      *
217      * @param mixed $olduser     Userobject before modifications    (without system magic quotes)
218      * @param mixed $newuser     Userobject new modified userobject (without system magic quotes)
219      * @return boolean true if updated or update ignored; false if error
220      *
221      */
222     function user_update($olduser, $newuser) {
223         //override if needed
224         return true;
225     }
227     /**
228      * User delete requested - internal user record is mared as deleted already, username not present anymore.
229      *
230      * Do any action in external database.
231      *
232      * @param object $user       Userobject before delete    (without system magic quotes)
233      * @return void
234      */
235     function user_delete($olduser) {
236         //override if needed
237         return;
238     }
240     /**
241      * Returns true if plugin allows resetting of internal password.
242      *
243      * @return bool
244      */
245     function can_reset_password() {
246         //override if needed
247         return false;
248     }
250     /**
251      * Returns true if plugin allows resetting of internal password.
252      *
253      * @return bool
254      */
255     function can_signup() {
256         //override if needed
257         return false;
258     }
260     /**
261      * Sign up a new user ready for confirmation.
262      * Password is passed in plaintext.
263      *
264      * @param object $user new user object
265      * @param boolean $notify print notice with link and terminate
266      */
267     function user_signup($user, $notify=true) {
268         //override when can signup
269         print_error('mustbeoveride', 'debug', '', 'user_signup()' );
270     }
272     /**
273      * Returns true if plugin allows confirming of new users.
274      *
275      * @return bool
276      */
277     function can_confirm() {
278         //override if needed
279         return false;
280     }
282     /**
283      * Confirm the new user as registered.
284      *
285      * @param string $username
286      * @param string $confirmsecret
287      */
288     function user_confirm($username, $confirmsecret) {
289         //override when can confirm
290         print_error('mustbeoveride', 'debug', '', 'user_confirm()' );
291     }
293     /**
294      * Checks if user exists in external db
295      *
296      * @param string $username (with system magic quotes)
297      * @return bool
298      */
299     function user_exists($username) {
300         //override if needed
301         return false;
302     }
304     /**
305      * return number of days to user password expires
306      *
307      * If userpassword does not expire it should return 0. If password is already expired
308      * it should return negative value.
309      *
310      * @param mixed $username username (with system magic quotes)
311      * @return integer
312      */
313     function password_expire($username) {
314         return 0;
315     }
316     /**
317      * Sync roles for this user - usually creator
318      *
319      * @param $user object user object (without system magic quotes)
320      */
321     function sync_roles($user) {
322         //override if needed
323     }
325     /**
326      * Read user information from external database and returns it as array().
327      * Function should return all information available. If you are saving
328      * this information to moodle user-table you should honour synchronisation flags
329      *
330      * @param string $username username
331      *
332      * @return mixed array with no magic quotes or false on error
333      */
334     function get_userinfo($username) {
335         //override if needed
336         return array();
337     }
339     /**
340      * Prints a form for configuring this authentication plugin.
341      *
342      * This function is called from admin/auth.php, and outputs a full page with
343      * a form for configuring this plugin.
344      *
345      * @param object $config
346      * @param object $err
347      * @param array $user_fields
348      */
349     function config_form($config, $err, $user_fields) {
350         //override if needed
351     }
353     /**
354      * A chance to validate form data, and last chance to
355      * do stuff before it is inserted in config_plugin
356      * @param object object with submitted configuration settings (without system magic quotes)
357      * @param array $err array of error messages
358      */
359      function validate_form(&$form, &$err) {
360         //override if needed
361     }
363     /**
364      * Processes and stores configuration data for this authentication plugin.
365      *
366      * @param object object with submitted configuration settings (without system magic quotes)
367      */
368     function process_config($config) {
369         //override if needed
370         return true;
371     }
373     /**
374      * Hook for overriding behaviour of login page.
375      * This method is called from login/index.php page for all enabled auth plugins.
376      *
377      * @global object
378      * @global object
379      */
380     function loginpage_hook() {
381         global $frm;  // can be used to override submitted login form
382         global $user; // can be used to replace authenticate_user_login()
384         //override if needed
385     }
387     /**
388      * Post authentication hook.
389      * This method is called from authenticate_user_login() for all enabled auth plugins.
390      *
391      * @param object $user user object, later used for $USER
392      * @param string $username (with system magic quotes)
393      * @param string $password plain text password (with system magic quotes)
394      */
395     function user_authenticated_hook(&$user, $username, $password) {
396         //override if needed
397     }
399     /**
400      * Pre logout hook.
401      * This method is called from require_logout() for all enabled auth plugins,
402      *
403      * @global object
404      */
405     function prelogout_hook() {
406         global $USER; // use $USER->auth to find the plugin used for login
408         //override if needed
409     }
411     /**
412      * Hook for overriding behaviour of logout page.
413      * This method is called from login/logout.php page for all enabled auth plugins.
414      *
415      * @global object
416      * @global string
417      */
418     function logoutpage_hook() {
419         global $USER;     // use $USER->auth to find the plugin used for login
420         global $redirect; // can be used to override redirect after logout
422         //override if needed
423     }
425     /**
426      * Hook called before timing out of database session.
427      * This is useful for SSO and MNET.
428      *
429      * @param object $user
430      * @param string $sid session id
431      * @param int $timecreated start of session
432      * @param int $timemodified user last seen
433      * @return bool true means do not timeout session yet
434      */
435     function ignore_timeout_hook($user, $sid, $timecreated, $timemodified) {
436         return false;
437     }
439     /**
440      * Return the properly translated human-friendly title of this auth plugin
441      *
442      * @todo Document this function
443      */
444     function get_title() {
445         return get_string('pluginname', "auth_{$this->authtype}");
446     }
448     /**
449      * Get the auth description (from core or own auth lang files)
450      *
451      * @return string The description
452      */
453     function get_description() {
454         $authdescription = get_string("auth_{$this->authtype}description", "auth_{$this->authtype}");
455         return $authdescription;
456     }
458     /**
459      * Returns whether or not the captcha element is enabled, and the admin settings fulfil its requirements.
460      *
461      * @abstract Implement in child classes
462      * @return bool
463      */
464     function is_captcha_enabled() {
465         return false;
466     }
468     /**
469      * Returns a list of potential IdPs that this authentication plugin supports.
470      * This is used to provide links on the login page.
471      *
472      * @param string $wantsurl the relative url fragment the user wants to get to.  You can use this to compose a returnurl, for example
473      *
474      * @return array like:
475      *              array(
476      *                  array(
477      *                      'url' => 'http://someurl',
478      *                      'icon' => new pix_icon(...),
479      *                      'name' => get_string('somename', 'auth_yourplugin'),
480      *                 ),
481      *             )
482      */
483     function loginpage_idp_list($wantsurl) {
484         return array();
485     }