MDL-22061 removing unnecessary [[ tests
[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 *
72dbdcea 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
6bc1e5d5 26 */
27
28/**
29 * Returned when the login was successful.
30 */
31define('AUTH_OK', 0);
32
33/**
34 * Returned when the login was unsuccessful.
35 */
36define('AUTH_FAIL', 1);
37
38/**
39 * Returned when the login was denied (a reason for AUTH_FAIL).
40 */
41define('AUTH_DENIED', 2);
42
43/**
44 * Returned when some error occurred (a reason for AUTH_FAIL).
45 */
46define('AUTH_ERROR', 4);
47
48/**
49 * Authentication - error codes for user confirm
50 */
51define('AUTH_CONFIRM_FAIL', 0);
52define('AUTH_CONFIRM_OK', 1);
53define('AUTH_CONFIRM_ALREADY', 2);
54define('AUTH_CONFIRM_ERROR', 3);
55
6f87ef52 56# MDL-14055
57define('AUTH_REMOVEUSER_KEEP', 0);
58define('AUTH_REMOVEUSER_SUSPEND', 1);
59define('AUTH_REMOVEUSER_FULLDELETE', 2);
6bc1e5d5 60
61/**
62 * Abstract authentication plugin.
72dbdcea 63 *
64 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
65 * @package moodlecore
6bc1e5d5 66 */
67class auth_plugin_base {
68
69 /**
70 * The configuration details for the plugin.
72dbdcea 71 * @var object
6bc1e5d5 72 */
73 var $config;
74
75 /**
76 * Authentication plugin type - the same as db field.
72dbdcea 77 * @var string
6bc1e5d5 78 */
79 var $authtype;
4105caff 80 /*
81 * The fields we can lock and update from/to external authentication backends
72dbdcea 82 * @var array
4105caff 83 */
5891220d 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 );
6bc1e5d5 100
101 /**
f5fd4347 102
103 * This is the primary method that is used by the authenticate_user_login()
117bd748 104 * function in moodlelib.php.
72dbdcea 105 *
106 * This method should return a boolean indicating
f5fd4347 107 * whether or not the username and password authenticate successfully.
108 *
6bc1e5d5 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) {
2f137aa1 118 print_error('mustbeoveride', 'debug', '', 'user_login()' );
6bc1e5d5 119 }
120
121 /**
f5fd4347 122 * Returns true if this authentication plugin can change the users'
6bc1e5d5 123 * password.
124 *
125 * @return bool
126 */
127 function can_change_password() {
128 //override if needed
129 return false;
130 }
131
132 /**
f5fd4347 133 * Returns the URL for changing the users' passwords, or empty if the default
117bd748 134 * URL can be used.
72dbdcea 135 *
136 * This method is used if can_change_password() returns true.
80274abf 137 * This method is called only when user is logged in, it may use global $USER.
6bc1e5d5 138 *
139 * @return string
140 */
141 function change_password_url() {
142 //override if needed
143 return '';
144 }
145
146 /**
f5fd4347 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).
6bc1e5d5 150 *
151 * @return bool
152 */
153 function is_internal() {
154 //override if needed
155 return true;
156 }
157
edb5da83
PS
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 }
166
6bc1e5d5 167 /**
117bd748 168 * Updates the user's password.
72dbdcea 169 *
170 * In previous versions of Moodle, the function
f5fd4347 171 * auth_user_update_password accepted a username as the first parameter. The
172 * revised function expects a user object.
6bc1e5d5 173 *
ae040d4b 174 * @param object $user User table object
175 * @param string $newpassword Plaintext password
6bc1e5d5 176 *
177 * @return bool True on success
178 */
179 function user_update_password($user, $newpassword) {
180 //override if needed
181 return true;
182 }
183
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 }
198
90afcf32 199 /**
200 * User delete requested - internal user record is mared as deleted already, username not present anymore.
72dbdcea 201 *
90afcf32 202 * Do any action in external database.
72dbdcea 203 *
90afcf32 204 * @param object $user Userobject before delete (without system magic quotes)
72dbdcea 205 * @return void
90afcf32 206 */
207 function user_delete($olduser) {
208 //override if needed
209 return;
210 }
211
6bc1e5d5 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 }
221
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 }
231
232 /**
233 * Sign up a new user ready for confirmation.
234 * Password is passed in plaintext.
235 *
5d910388 236 * @param object $user new user object
6bc1e5d5 237 * @param boolean $notify print notice with link and terminate
238 */
239 function user_signup($user, $notify=true) {
240 //override when can signup
2f137aa1 241 print_error('mustbeoveride', 'debug', '', 'user_signup()' );
6bc1e5d5 242 }
243
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 }
253
254 /**
255 * Confirm the new user as registered.
256 *
b9a66360 257 * @param string $username
258 * @param string $confirmsecret
6bc1e5d5 259 */
260 function user_confirm($username, $confirmsecret) {
261 //override when can confirm
2f137aa1 262 print_error('mustbeoveride', 'debug', '', 'user_confirm()' );
6bc1e5d5 263 }
264
265 /**
266 * Checks if user exists in external db
267 *
268 * @param string $username (with system magic quotes)
03cedd62 269 * @return bool
6bc1e5d5 270 */
d61ffb0f 271 function user_exists($username) {
6bc1e5d5 272 //override if needed
273 return false;
274 }
275
6bc1e5d5 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 }
296
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 *
be544ec3 302 * @param string $username username
6bc1e5d5 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 }
310
f5fd4347 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.
72dbdcea 316 *
317 * @param object $config
318 * @param object $err
319 * @param array $user_fields
f5fd4347 320 */
321 function config_form($config, $err, $user_fields) {
322 //override if needed
323 }
324
6bc1e5d5 325 /**
326 * A chance to validate form data, and last chance to
327 * do stuff before it is inserted in config_plugin
f4f2b8fb 328 * @param object object with submitted configuration settings (without system magic quotes)
329 * @param array $err array of error messages
6bc1e5d5 330 */
331 function validate_form(&$form, &$err) {
332 //override if needed
333 }
334
335 /**
f5fd4347 336 * Processes and stores configuration data for this authentication plugin.
f4f2b8fb 337 *
338 * @param object object with submitted configuration settings (without system magic quotes)
6bc1e5d5 339 */
f5fd4347 340 function process_config($config) {
341 //override if needed
342 return true;
343 }
344
345 /**
346 * Hook for overriding behavior of login page.
347 * This method is called from login/index.php page for all enabled auth plugins.
72dbdcea 348 *
349 * @global object
350 * @global object
f5fd4347 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()
355
6bc1e5d5 356 //override if needed
357 }
358
359 /**
360 * Post authentication hook.
f5fd4347 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)
6bc1e5d5 366 */
f5fd4347 367 function user_authenticated_hook(&$user, $username, $password) {
368 //override if needed
6bc1e5d5 369 }
370
371 /**
f5fd4347 372 * Pre logout hook.
373 * This method is called from require_logout() for all enabled auth plugins,
72dbdcea 374 *
375 * @global object
6bc1e5d5 376 */
377 function prelogout_hook() {
f5fd4347 378 global $USER; // use $USER->auth to find the plugin used for login
379
380 //override if needed
381 }
382
383 /**
384 * Hook for overriding behavior of logout page.
385 * This method is called from login/logout.php page for all enabled auth plugins.
72dbdcea 386 *
387 * @global object
388 * @global string
f5fd4347 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
393
6bc1e5d5 394 //override if needed
395 }
2a5f4a88 396
e8656bef 397 /**
398 * Hook called before timing out of database session.
399 * This is usueful for SSO and MNET.
72dbdcea 400 *
e8656bef 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) {
88fdd846 408 return false;
409 }
410
2a5f4a88 411 /**
412 * Return the properly translated human-friendly title of this auth plugin
72dbdcea 413 *
414 * @todo Document this function
2a5f4a88 415 */
416 function get_title() {
2a274f2a 417 return auth_get_plugin_title($this->authtype);
2a5f4a88 418 }
419
420 /**
72dbdcea 421 * Get the auth description (from core or own auth lang files)
422 *
423 * @return string The description
2a5f4a88 424 */
425 function get_description() {
37f005b1 426 $authdescription = get_string("auth_{$this->authtype}description", "auth_{$this->authtype}");
2a5f4a88 427 return $authdescription;
428 }
117bd748 429
9b5f87d2 430 /**
431 * Returns whether or not the captcha element is enabled, and the admin settings fulfil its requirements.
72dbdcea 432 *
9b5f87d2 433 * @abstract Implement in child classes
434 * @return bool
435 */
436 function is_captcha_enabled() {
437 return false;
438 }
439
b257d7c4
PL
440 /**
441 * Returns a list of potential IdPs that this authentication plugin supports.
442 * This is used to provide links on the login page.
443 *
444 * @param string $wantsurl the relative url fragment the user wants to get to. You can use this to compose a returnurl, for example
445 *
446 * @return array like:
447 * array(
448 * array(
449 * 'url' => 'http://someurl',
450 * 'icon' => new pix_icon(...),
451 * 'name' => get_string('somename', 'auth_yourplugin'),
452 * ),
453 * )
454 */
455 function loginpage_idp_list($wantsurl) {
456 return array();
457 }
9b5f87d2 458
6bc1e5d5 459}