MDL-11728 finally defining the exact meaning of is_internal() in auth plugins
[moodle.git] / lib / authlib.php
CommitLineData
72dbdcea 1<?php
2
117bd748
PS
3// This file is part of Moodle - http://moodle.org/
4//
72dbdcea 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.
117bd748 14//
72dbdcea 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/>.
17
6bc1e5d5 18/**
72dbdcea 19 * Multiple plugin authentication Support library
6bc1e5d5 20 *
21 * 2006-08-28 File created, AUTH return values defined.
117bd748 22 *
78bfb562
PS
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
6bc1e5d5 27 */
28
78bfb562
PS
29defined('MOODLE_INTERNAL') || die();
30
6bc1e5d5 31/**
32 * Returned when the login was successful.
33 */
34define('AUTH_OK', 0);
35
36/**
37 * Returned when the login was unsuccessful.
38 */
39define('AUTH_FAIL', 1);
40
41/**
42 * Returned when the login was denied (a reason for AUTH_FAIL).
43 */
44define('AUTH_DENIED', 2);
45
46/**
47 * Returned when some error occurred (a reason for AUTH_FAIL).
48 */
49define('AUTH_ERROR', 4);
50
51/**
52 * Authentication - error codes for user confirm
53 */
54define('AUTH_CONFIRM_FAIL', 0);
55define('AUTH_CONFIRM_OK', 1);
56define('AUTH_CONFIRM_ALREADY', 2);
57define('AUTH_CONFIRM_ERROR', 3);
58
6f87ef52 59# MDL-14055
60define('AUTH_REMOVEUSER_KEEP', 0);
61define('AUTH_REMOVEUSER_SUSPEND', 1);
62define('AUTH_REMOVEUSER_FULLDELETE', 2);
6bc1e5d5 63
64/**
65 * Abstract authentication plugin.
72dbdcea 66 *
67 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
68 * @package moodlecore
6bc1e5d5 69 */
70class auth_plugin_base {
71
72 /**
73 * The configuration details for the plugin.
72dbdcea 74 * @var object
6bc1e5d5 75 */
76 var $config;
77
78 /**
79 * Authentication plugin type - the same as db field.
72dbdcea 80 * @var string
6bc1e5d5 81 */
82 var $authtype;
4105caff 83 /*
84 * The fields we can lock and update from/to external authentication backends
72dbdcea 85 * @var array
4105caff 86 */
5891220d 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 );
6bc1e5d5 103
104 /**
f5fd4347 105
106 * This is the primary method that is used by the authenticate_user_login()
117bd748 107 * function in moodlelib.php.
72dbdcea 108 *
109 * This method should return a boolean indicating
f5fd4347 110 * whether or not the username and password authenticate successfully.
111 *
6bc1e5d5 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) {
2f137aa1 121 print_error('mustbeoveride', 'debug', '', 'user_login()' );
6bc1e5d5 122 }
123
124 /**
f5fd4347 125 * Returns true if this authentication plugin can change the users'
6bc1e5d5 126 * password.
127 *
128 * @return bool
129 */
130 function can_change_password() {
131 //override if needed
132 return false;
133 }
134
135 /**
f5fd4347 136 * Returns the URL for changing the users' passwords, or empty if the default
117bd748 137 * URL can be used.
72dbdcea 138 *
139 * This method is used if can_change_password() returns true.
80274abf 140 * This method is called only when user is logged in, it may use global $USER.
6bc1e5d5 141 *
99f9f85f 142 * @return moodle_url url of the profile page or null if standard used
6bc1e5d5 143 */
144 function change_password_url() {
145 //override if needed
99f9f85f
PS
146 return null;
147 }
148
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 }
159
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;
6bc1e5d5 172 }
173
174 /**
7415aed1
PS
175 * Returns true if this authentication plugin is "internal".
176 *
177 * Internal plugins use password hashes from Moodle user table for authentication.
6bc1e5d5 178 *
179 * @return bool
180 */
181 function is_internal() {
182 //override if needed
183 return true;
184 }
185
edb5da83
PS
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() {
7415aed1
PS
191 return !$this->is_internal();
192 }
193
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();
edb5da83
PS
203 }
204
6bc1e5d5 205 /**
117bd748 206 * Updates the user's password.
72dbdcea 207 *
208 * In previous versions of Moodle, the function
f5fd4347 209 * auth_user_update_password accepted a username as the first parameter. The
210 * revised function expects a user object.
6bc1e5d5 211 *
ae040d4b 212 * @param object $user User table object
213 * @param string $newpassword Plaintext password
6bc1e5d5 214 *
215 * @return bool True on success
216 */
217 function user_update_password($user, $newpassword) {
218 //override if needed
219 return true;
220 }
221
222 /**
223 * Called when the user record is updated.
224 * Modifies user in external database. It takes olduser (before changes) and newuser (after changes)
640df5d0 225 * compares information saved modified information to external db.
6bc1e5d5 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 }
236
90afcf32 237 /**
238 * User delete requested - internal user record is mared as deleted already, username not present anymore.
72dbdcea 239 *
90afcf32 240 * Do any action in external database.
72dbdcea 241 *
90afcf32 242 * @param object $user Userobject before delete (without system magic quotes)
72dbdcea 243 * @return void
90afcf32 244 */
245 function user_delete($olduser) {
246 //override if needed
247 return;
248 }
249
6bc1e5d5 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 }
259
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 }
269
270 /**
271 * Sign up a new user ready for confirmation.
272 * Password is passed in plaintext.
273 *
5d910388 274 * @param object $user new user object
6bc1e5d5 275 * @param boolean $notify print notice with link and terminate
276 */
277 function user_signup($user, $notify=true) {
278 //override when can signup
2f137aa1 279 print_error('mustbeoveride', 'debug', '', 'user_signup()' );
6bc1e5d5 280 }
281
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 }
291
292 /**
293 * Confirm the new user as registered.
294 *
b9a66360 295 * @param string $username
296 * @param string $confirmsecret
6bc1e5d5 297 */
298 function user_confirm($username, $confirmsecret) {
299 //override when can confirm
2f137aa1 300 print_error('mustbeoveride', 'debug', '', 'user_confirm()' );
6bc1e5d5 301 }
302
303 /**
304 * Checks if user exists in external db
305 *
306 * @param string $username (with system magic quotes)
03cedd62 307 * @return bool
6bc1e5d5 308 */
d61ffb0f 309 function user_exists($username) {
6bc1e5d5 310 //override if needed
311 return false;
312 }
313
6bc1e5d5 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 }
334
335 /**
336 * Read user information from external database and returns it as array().
337 * Function should return all information available. If you are saving
640df5d0 338 * this information to moodle user-table you should honour synchronisation flags
6bc1e5d5 339 *
be544ec3 340 * @param string $username username
6bc1e5d5 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 }
348
f5fd4347 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.
72dbdcea 354 *
355 * @param object $config
356 * @param object $err
357 * @param array $user_fields
f5fd4347 358 */
359 function config_form($config, $err, $user_fields) {
360 //override if needed
361 }
362
6bc1e5d5 363 /**
364 * A chance to validate form data, and last chance to
365 * do stuff before it is inserted in config_plugin
f4f2b8fb 366 * @param object object with submitted configuration settings (without system magic quotes)
367 * @param array $err array of error messages
6bc1e5d5 368 */
369 function validate_form(&$form, &$err) {
370 //override if needed
371 }
372
373 /**
f5fd4347 374 * Processes and stores configuration data for this authentication plugin.
f4f2b8fb 375 *
376 * @param object object with submitted configuration settings (without system magic quotes)
6bc1e5d5 377 */
f5fd4347 378 function process_config($config) {
379 //override if needed
380 return true;
381 }
382
383 /**
640df5d0 384 * Hook for overriding behaviour of login page.
f5fd4347 385 * This method is called from login/index.php page for all enabled auth plugins.
72dbdcea 386 *
387 * @global object
388 * @global object
f5fd4347 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()
393
6bc1e5d5 394 //override if needed
395 }
396
397 /**
398 * Post authentication hook.
f5fd4347 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)
6bc1e5d5 404 */
f5fd4347 405 function user_authenticated_hook(&$user, $username, $password) {
406 //override if needed
6bc1e5d5 407 }
408
409 /**
f5fd4347 410 * Pre logout hook.
411 * This method is called from require_logout() for all enabled auth plugins,
72dbdcea 412 *
413 * @global object
6bc1e5d5 414 */
415 function prelogout_hook() {
f5fd4347 416 global $USER; // use $USER->auth to find the plugin used for login
417
418 //override if needed
419 }
420
421 /**
640df5d0 422 * Hook for overriding behaviour of logout page.
f5fd4347 423 * This method is called from login/logout.php page for all enabled auth plugins.
72dbdcea 424 *
425 * @global object
426 * @global string
f5fd4347 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
431
6bc1e5d5 432 //override if needed
433 }
2a5f4a88 434
e8656bef 435 /**
436 * Hook called before timing out of database session.
640df5d0 437 * This is useful for SSO and MNET.
72dbdcea 438 *
e8656bef 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) {
88fdd846 446 return false;
447 }
448
2a5f4a88 449 /**
450 * Return the properly translated human-friendly title of this auth plugin
72dbdcea 451 *
452 * @todo Document this function
2a5f4a88 453 */
454 function get_title() {
370f10b7 455 return get_string('pluginname', "auth_{$this->authtype}");
2a5f4a88 456 }
457
458 /**
72dbdcea 459 * Get the auth description (from core or own auth lang files)
460 *
461 * @return string The description
2a5f4a88 462 */
463 function get_description() {
37f005b1 464 $authdescription = get_string("auth_{$this->authtype}description", "auth_{$this->authtype}");
2a5f4a88 465 return $authdescription;
466 }
117bd748 467
9b5f87d2 468 /**
469 * Returns whether or not the captcha element is enabled, and the admin settings fulfil its requirements.
72dbdcea 470 *
9b5f87d2 471 * @abstract Implement in child classes
472 * @return bool
473 */
474 function is_captcha_enabled() {
475 return false;
476 }
477
b257d7c4
PL
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 }
9b5f87d2 496
6bc1e5d5 497}