Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/lib/ -> authlib.php (source)

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

Multiple plugin authentication Support library 2006-08-28  File created, AUTH return values defined.

Copyright: 1999 onwards Martin Dougiamas http://dougiamas.com
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1292 lines (44 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class


Class: auth_plugin_base  - X-Ref

Abstract authentication plugin.

user_login($username, $password)   X-Ref
This is the primary method that is used by the authenticate_user_login()
function in moodlelib.php.

This method should return a boolean indicating
whether or not the username and password authenticate successfully.

Returns true if the username and password work and false if they are
wrong or don't exist.

param: string $username The username (with system magic quotes)
param: string $password The password (with system magic quotes)
return: bool Authentication success or failure.

can_change_password()   X-Ref
Returns true if this authentication plugin can change the users'
password.

return: bool

change_password_url()   X-Ref
Returns the URL for changing the users' passwords, or empty if the default
URL can be used.

This method is used if can_change_password() returns true.
This method is called only when user is logged in, it may use global $USER.
If you are using a plugin config variable in this method, please make sure it is set before using it,
as this method can be called even if the plugin is disabled, in which case the config values won't be set.

return: moodle_url url of the profile page or null if standard used

can_edit_profile()   X-Ref
Returns true if this authentication plugin can edit the users'
profile.

return: bool

edit_profile_url()   X-Ref
Returns the URL for editing the users' profile, or empty if the default
URL can be used.

This method is used if can_edit_profile() returns true.
This method is called only when user is logged in, it may use global $USER.

return: moodle_url url of the profile page or null if standard used

is_internal()   X-Ref
Returns true if this authentication plugin is "internal".

Internal plugins use password hashes from Moodle user table for authentication.

return: bool

is_configured()   X-Ref
Returns false if this plugin is enabled but not configured.

return: bool

prevent_local_passwords()   X-Ref
Indicates if password hashes should be stored in local moodle database.

return: bool true means md5 password hash stored in user table, false means flag 'not_cached' stored there instead

is_synchronised_with_external()   X-Ref
Indicates if moodle should automatically update internal user
records with data from external sources using the information
from get_userinfo() method.

return: bool true means automatically copy data from ext to user table

user_update_password($user, $newpassword)   X-Ref
Updates the user's password.

In previous versions of Moodle, the function
auth_user_update_password accepted a username as the first parameter. The
revised function expects a user object.

param: object  $user        User table object
param: string  $newpassword Plaintext password
return: bool                  True on success

user_update($olduser, $newuser)   X-Ref
Called when the user record is updated.
Modifies user in external database. It takes olduser (before changes) and newuser (after changes)
compares information saved modified information to external db.

param: mixed $olduser     Userobject before modifications    (without system magic quotes)
param: mixed $newuser     Userobject new modified userobject (without system magic quotes)
return: boolean true if updated or update ignored; false if error

user_delete($olduser)   X-Ref
User delete requested - internal user record is mared as deleted already, username not present anymore.

Do any action in external database.

param: object $user       Userobject before delete    (without system magic quotes)
return: void

can_reset_password()   X-Ref
Returns true if plugin allows resetting of internal password.

return: bool

can_signup()   X-Ref
Returns true if plugin allows resetting of internal password.

return: bool

user_signup($user, $notify=true)   X-Ref
Sign up a new user ready for confirmation.
Password is passed in plaintext.

param: object $user new user object
param: boolean $notify print notice with link and terminate

signup_form()   X-Ref
Return a form to capture user details for account creation.
This is used in /login/signup.php.

return: moodle_form A form which edits a record from the user table.

can_confirm()   X-Ref
Returns true if plugin allows confirming of new users.

return: bool

user_confirm($username, $confirmsecret)   X-Ref
Confirm the new user as registered.

param: string $username
param: string $confirmsecret

user_exists($username)   X-Ref
Checks if user exists in external db

param: string $username (with system magic quotes)
return: bool

password_expire($username)   X-Ref
return number of days to user password expires

If userpassword does not expire it should return 0. If password is already expired
it should return negative value.

param: mixed $username username (with system magic quotes)
return: integer

sync_roles($user)   X-Ref
Sync roles for this user - usually creator

param: $user object user object (without system magic quotes)

get_userinfo($username)   X-Ref
Read user information from external database and returns it as array().
Function should return all information available. If you are saving
this information to moodle user-table you should honour synchronisation flags

param: string $username username
return: mixed array with no magic quotes or false on error

config_form($config, $err, $user_fields)   X-Ref
Prints a form for configuring this authentication plugin.

This function is called from admin/auth.php, and outputs a full page with
a form for configuring this plugin.

param: object $config
param: object $err
param: array $user_fields

validate_form($form, &$err)   X-Ref
A chance to validate form data, and last chance to
do stuff before it is inserted in config_plugin

param: object object with submitted configuration settings (without system magic quotes)
param: array $err array of error messages

process_config($config)   X-Ref
Processes and stores configuration data for this authentication plugin.

param: object object with submitted configuration settings (without system magic quotes)

loginpage_hook()   X-Ref
Hook for overriding behaviour of login page.
This method is called from login/index.php page for all enabled auth plugins.


pre_loginpage_hook()   X-Ref
Hook for overriding behaviour before going to the login page.

This method is called from require_login from potentially any page for
all enabled auth plugins and gives each plugin a chance to redirect
directly to an external login page, or to instantly login a user where
possible.

If an auth plugin implements this hook, it must not rely on ONLY this
hook in order to work, as there are many ways a user can browse directly
to the standard login page. As a general rule in this case you should
also implement the loginpage_hook as well.


pre_user_login_hook(&$user)   X-Ref
Pre user_login hook.
This method is called from authenticate_user_login() right after the user
object is generated. This gives the auth plugins an option to make adjustments
before the verification process starts.

param: object $user user object, later used for $USER

user_authenticated_hook(&$user, $username, $password)   X-Ref
Post authentication hook.
This method is called from authenticate_user_login() for all enabled auth plugins.

param: object $user user object, later used for $USER
param: string $username (with system magic quotes)
param: string $password plain text password (with system magic quotes)

prelogout_hook()   X-Ref
Pre logout hook.
This method is called from require_logout() for all enabled auth plugins,


logoutpage_hook()   X-Ref
Hook for overriding behaviour of logout page.
This method is called from login/logout.php page for all enabled auth plugins.


ignore_timeout_hook($user, $sid, $timecreated, $timemodified)   X-Ref
Hook called before timing out of database session.
This is useful for SSO and MNET.

param: object $user
param: string $sid session id
param: int $timecreated start of session
param: int $timemodified user last seen
return: bool true means do not timeout session yet

get_title()   X-Ref
Return the properly translated human-friendly title of this auth plugin


get_description()   X-Ref
Get the auth description (from core or own auth lang files)

return: string The description

is_captcha_enabled()   X-Ref
Returns whether or not the captcha element is enabled.

return: bool

can_be_manually_set()   X-Ref
Returns whether or not this authentication plugin can be manually set
for users, for example, when bulk uploading users.

This should be overriden by authentication plugins where setting the
authentication method manually is allowed.

return: bool

loginpage_idp_list($wantsurl)   X-Ref
Returns a list of potential IdPs that this authentication plugin supports.

This is used to provide links on the login page and the login block.

The parameter $wantsurl is typically used by the plugin to implement a
return-url feature.

The returned value is expected to be a list of associative arrays with
string keys:

- url => (moodle_url|string) URL of the page to send the user to for authentication
- name => (string) Human readable name of the IdP
- iconurl => (moodle_url|string) URL of the icon representing the IdP (since Moodle 3.3)

For legacy reasons, pre-3.3 plugins can provide the icon via the key:

- icon => (pix_icon) Icon representing the IdP

param: string $wantsurl The relative url fragment the user wants to get to.
return: array List of associative arrays with keys url, name, iconurl|icon

get_custom_user_profile_fields()   X-Ref
Return custom user profile fields.

return: array list of custom fields.

postlogout_hook($user)   X-Ref
Post logout hook.

This method is used after moodle logout by auth classes to execute server logout.

param: stdClass $user clone of USER object before the user session was terminated

update_user_record($username, $updatekeys = false, $triggerevent = false, $suspenduser = false)   X-Ref
Update a local user record from an external source.
This is a lighter version of the one in moodlelib -- won't do
expensive ops such as enrolment.

param: string $username username
param: array $updatekeys fields to update, false updates all fields.
param: bool $triggerevent set false if user_updated event should not be triggered.
param: bool $suspenduser Should the user be suspended?
return: stdClass|bool updated user record or false if there is no new info to update.

get_identity_providers($authsequence)   X-Ref
Return the list of enabled identity providers.

Each identity provider data contains the keys url, name and iconurl (or
icon). See the documentation of {@link auth_plugin_base::loginpage_idp_list()}
for detailed description of the returned structure.

param: array $authsequence site's auth sequence (list of auth plugins ordered)
return: array List of arrays describing the identity providers

prepare_identity_providers_for_output($identityproviders, renderer_base $output)   X-Ref
Prepare a list of identity providers for output.

param: array $identityproviders as returned by {@link self::get_identity_providers()}
param: renderer_base $output
return: array the identity providers ready for output

get_password_change_info(stdClass $user)   X-Ref
Returns information on how the specified user can change their password.

param: stdClass $user A user object
return: string[] An array of strings with keys subject and message

set_extrauserinfo(array $values)   X-Ref
Set extra user information.

param: array $values Any Key value pair.
return: void

get_extrauserinfo()   X-Ref
Returns extra user information.

return: array An array of keys and values

login_is_lockedout($user)   X-Ref
Verify if user is locked out.

param: stdClass $user
return: bool true if user locked out

login_attempt_valid($user)   X-Ref
To be called after valid user login.

param: stdClass $user

login_attempt_failed($user)   X-Ref
To be called after failed user login.

param: stdClass $user

login_lock_account($user)   X-Ref
Lockout user and send notification email.

param: stdClass $user

login_unlock_account($user)   X-Ref
Unlock user account and reset timers.

param: stdClass $user

signup_captcha_enabled()   X-Ref
Returns whether or not the captcha element is enabled, and the admin settings fulfil its requirements.

return: bool

signup_validate_data($data, $files)   X-Ref
Validates the standard sign-up data (except recaptcha that is validated by the form element).

param: array $data  the sign-up data
param: array $files files among the data
return: array list of errors, being the key the data element name and the value the error itself

signup_setup_new_user($user)   X-Ref
Add the missing fields to a user that is going to be created

param: stdClass $user the new user object
return: stdClass the user filled

signup_get_user_confirmation_authplugin()   X-Ref
Check if user confirmation is enabled on this site and return the auth plugin handling registration if enabled.

return: stdClass the current auth plugin handling user registration or false if registration not enabled

signup_is_enabled()   X-Ref
Check if sign-up is enabled in the site. If is enabled, the function will return the authplugin instance.

return: mixed false if sign-up is not enabled, the authplugin instance otherwise.

display_auth_lock_options($settings, $auth, $userfields, $helptext, $mapremotefields, $updateremotefields, $customfields = array()   X-Ref
Helper function used to print locking for auth plugins on admin pages.

param: stdclass $settings Moodle admin settings instance
param: string $auth authentication plugin shortname
param: array $userfields user profile fields
param: string $helptext help text to be displayed at top of form
param: boolean $mapremotefields Map fields or lock only.
param: boolean $updateremotefields Allow remote updates
param: array $customfields list of custom profile fields