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