Authentication plugins

Introduction

This page first gives an overview of the authentication process and then explains how authentication modules can be created using hooks to take over from the native authentication in Moodle.

Overview of Moodle authentication process

The login UI element in Moodle 1.9

The authentication use case in Moodle starts when a user clicks on the Login link in the UI or if they try to access a protected page. There are two broad classes of authentication plugins, the regular type where moodle handles the password and ones where the password is handled by a 3rd party page eg SAML, OpenID etc.

For the regular plugins the following happens (skipping some minor details and rarer scenarios):

The default login page (/login/index.php) is displayed. OR, if a system administrator has set the Alternate Login URL on the "Manage authentication" page, that URL will be displayed.
A user enters their credentials and submits the form.
The handler code in /login/index.php runs:
1. Gets a list of enabled authentication plugins.
2. Runs loginpage_hook() for each plugin, in case any of them needs to intercept the login request.
3. Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
4. Calls authenticate_user_login() in /lib/moodlelib.php, which returns a
```
$user
```
  object. (Details of this code follow this main outline.)
5. Determines whether authentication was successful (by checking whether
```
$user
```
  is a valid object) and, if not, sends them back to the login page with an error message. Otherwise, it figures out where to send the user based on their original page request, whether their password is expired, etc., and redirects them there.

For the 3rd party auth plugins the process could look like this (eg CAS, SAML, OpenID etc):

Access a protected page but isn't logged in, so moodle calls pre_loginpage_hook() on each enabled plugin, which may redirect to the 3rd party login page
Or if they go directly to the login page moodle calls loginpage_hook() on each enabled plugin, which may redirect to the 3rd party login page
The user enters their credentials and authenticates on the 3rd party page
The remote authentication service redirects back to moodle with an assertion, such as a single use token or encrypted response in a query param
The auth plugin now validates the token or decrypts the assertion, does any other checking as required and then logs the user in using complete_user_login($user). If this happens inside pre_loginpage_hook() then the user continues on their way, or if inside loginpage_hook() or another custom page then the plugin should redirect to the wantsurl.

Note that in this scenario above user_login($username, $password) is never called and should probably return false.

History

Authentication plugins exist from 1.9

Example

Google / Facebook / Messenger Oauth2 Authentication plugin

Template

Please see Moodle none authentication plugin (auth/none), it's the perfect plugin template to start with.

Naming convention

File structure

Choose a name for your plugin. We'll use 'sentry' as an example below; change it to whatever name you have chosen.
Under your Moodle installation root, create the directory /auth/sentry. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
Create the file /auth/sentry/auth.php. Within the file, create a class auth_plugin_sentry that extends auth_plugin_base from /lib/authlib.php. (You will need to
```
require_once
```
the authlib file.)
Implement the user_login() function in your auth.php file, and create or override additional functions based on your plugin's requirements.
Log in to your Moodle installation as a site administrator and find, in the site administrator block, the page "Users -> Authentication -> Manage authentication". You will see your plugin in the list, appearing as [[auth_sentrytitle]]. You can enable it and move it up and down in the order. At this point, with the plugin enabled, your plugin is registered and will be used by Moodle in its authentication process.
If you don't like seeing [[auth_sentrytitle]] as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. See String API for details.
If you want to configure your plugin through the Moodle UI, implement config_form() and process_config() in the plugin class. You might find it convenient to use the 'db' plugin as a model for this. The plugin's config settings can then be managed through the Manage authentication page by clicking on the Settings link for that plugin, and the values will be stored in the mdl_config_plugins table in the database.

Interfacing to API's

`authenticate_user_login()`

That's the main outline, but a lot of interesting stuff happens in authenticate_user_login():

It gets a list of enabled authentication plugins.
It looks up the username in the mdl_user table to see if they are allowed to log in, and which authentication plugin handles their login requests. (This will be the plugin that handled their first-ever login request.)
It creates a user object, which will contain the data from mdl_user if the username is known; if not, it will be an empty object.
It does the following with the authentication plugin (note that for a username unknown to Moodle, it will do these steps for each authenticated plugin until one succeeds or it has tried them all):
1. Calls the user_login() function provided by that plugin, which returns a boolean value based on whether the credentials authenticate or not. If the result is false (not authenticated), skips the rest of the steps below and continues to the next plugin.
2. If the plugin authenticates against an external system (not Moodle's user database), its update_user_record() function is called to get the user's name, contact info, etc.
3. Creates the Moodle user record if it doesn't already exist.
4. Calls the plugin's sync_roles() function.
5. Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's user_authenticated_hook() function.
It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

`user_login($username, $password)`

This must be rewritten by plugin to return boolean value, returns true if the username and password work and false if they are wrong or don't exist.

`can_change_password()`

Returns true if this authentication plugin can change users' password.

Return type: boolean
Default return value: false

`change_password_url()`

Returns the URL for changing the users' passwords, or empty if the default URL can be used.

`can_edit_profile()`

Returns true if this authentication plugin can edit the users' profile.

Return type: boolean
Default return value: true

`edit_profile_url()`

Returns the URL for editing users' profile, or empty if the defaults URL can be used.

`is_internal()`

Returns true if this authentication plugin is "internal". Internal plugins use password hashes from Moodle user table for authentication.

Return type: boolean
Default return value: true

`is_configured()`

Returns false if this plugin is enabled but not configured.

Return type: boolean
Default return value: false

`prevent_local_passwords()`

Indicates if password hashes should be stored in local moodle database. This function automatically returns the opposite boolean of what is_internal() returns. Returning true means MD5 password hashes will be stored in the user table. Returning false means flag 'not_cached' will be stored there instead.

Return type: boolean
Default return value: !$this->is_internal()

`is_synchronised_with_external()`

Indicates if moodle should automatically update internal user records with data from external sources using the information from get_userinfo() method. This function automatically returns the opposite boolean of what is_internal() returns.

Return type: boolean
Default return value: !$this->is_internal()

`user_update_password($user, $newpassword)`

Update the user's password.

How passwords are stored in the DB (mdl_user.password): forum discussion

`user_update($olduser, $newuser)`

Called when the user record is updated. It will modify the user information in external database.

`user_delete($olduser)`

User delete requested. Internal user record had been deleted.

`can_reset_password()`

Returns true if plugin allows resetting of internal password.

Return type: boolean
Default return value: false

`can_signup()`

Returns true if plugin allows resetting of internal password.

Return type: boolean
Default return value: false

`user_signup($user, $notify=true)`

Sign up a new user ready for confirmation, password is passed in plaintext.

`can_confirm()`

Returns true if plugin allows confirming of new users.

Return type: boolean
Default return value: false

`user_confirm($username, $confirmsecret)`

Confirm the new user as registered.

`user_exists($username)`

Checks if user exists in external db.

`password_expire($username)`

Returns number of days to user password expires.

`sync_roles()`

Sync roles for this user - usually creator

`get_userinfo($username)`

Read user information from external database and returns it as array.

`config_form($config, $err, $user_fields)`

Prints a form for configuring this authentication plugin. It's called from admin/auth.php, and outputs a full page with a form for configuring this plugin. This function has been deprecated in Moodle 3.3. You should use the Admin_settings API instead. For more information see [1]

`validate_form($form, $err)`

Validate form data. This function has been deprecated in Moodle 3.3. You should use the Admin_settings API instead. For more information see [2]

`process_config($config)`

Processes and stores configuration data for this authentication plugin. This function has been deprecated in Moodle 3.3. You should use the Admin_settings API instead. For more information see [3]

`loginpage_hook()`

Hook for overriding behaviour of login page.

`pre_loginpage_hook()`

Hook for overriding behaviour of prior to redirecting to the login page, eg redirecting to an external login url for SAML or OpenID authentication. If you implement this you should also implement loginpage_hook as the user may go directly to the login page.

`user_authenticated_hook($user, $username, $password)`

Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

`prelogout_hook()`

Pre logout hook.

`postlogout_hook()`

This method replace the prelogout_hook method to avoid authentication plugins redirects before the user logout event being triggered. At the moment the only authentication plugin using this method is CAS (SSO).

`logoutpage_hook()`

Hook for overriding behaviour of logout page.

`can_be_manually_set()`

This function was introduced in the base class and returns false by default. If overriden by an authentication plugin to return true, the authentication plugin will be able to be manually set for users. For example, when bulk uploading users you will be able to select it as the authentication method they use.

`loginpage_idp_list()`

Override this method and return a list of Identification Providers (IDPs) that your authentication plugin supports. An array of associative arrays containing url, icon and name for the IDP. These will be displayed on the login page and in the login block.

`pre_user_login_hook(&$user)`

This method is called from authenticate_user_login() right after the user object is generated. This gives the auth plugin an option to make modification to the user object before the verification process starts.

`test_settings()`

(From 3.3 onwards) If this method exists, the "manage authentication plugins" page will show a "test settings" link. The method should output notifications to let the user know whether the settings are correct, and what to do to rectify them if not.

Documentation

Authentication plugins

Introduction

Overview of Moodle authentication process

History

Example

Template

Naming convention

File structure

Interfacing to API's

authenticate_user_login()

user_login($username, $password)

can_change_password()

change_password_url()

can_edit_profile()

edit_profile_url()

is_internal()

is_configured()

prevent_local_passwords()

is_synchronised_with_external()

user_update_password($user, $newpassword)

user_update($olduser, $newuser)

user_delete($olduser)

can_reset_password()

can_signup()

user_signup($user, $notify=true)

can_confirm()

user_confirm($username, $confirmsecret)

user_exists($username)

password_expire($username)

sync_roles()

get_userinfo($username)

config_form($config, $err, $user_fields)

validate_form($form, $err)

process_config($config)

loginpage_hook()

pre_loginpage_hook()

user_authenticated_hook($user, $username, $password)

prelogout_hook()

postlogout_hook()

logoutpage_hook()

can_be_manually_set()

loginpage_idp_list()

pre_user_login_hook(&$user)

test_settings()

See also