MoodleDocs - User contributions [en]

Talk:Developer FAQ

2014-06-10T04:37:34Z

Rrf5000: Request to fix broken links

The link "the documentation for datalib.php" appears to be broken. I believe that it should link to http://phpdocs.moodle.org/moodlecore/_lib---datalib.php.html instead of http://moodle.sourceforge.net/dhawes-phpdoc/moodlecore/_lib_datalib_php.html I'm not sure though because the file is empty. Hopefully someone else knows now to fix this.

----

Echoing the earlier comment from 2007, the links to documentation on [[Developer_FAQ#How_do_I_insert.2Fretrieve_records_in_the_database.2C_without_creating_my_own_database_connections.3F|inserting and retrieving records in the database]] (datalib.php and dmllib.php) are broken. Can anyone in the know correct the links?
--[[User:Ryan Foster|Ryan Foster]] ([[User talk:Ryan Foster|talk]]) 12:37, 10 June 2014 (WST)

===Is there any information on creating a new module or plugin?===
This section contains a link to the 'Moodle 1.9 Extension Development' book by Jonathan Moore and Michael Churchward. Is this book still relevant to Moodle 2 or does Moodle 2 make it out-of-date? In other words, can you use it to develop modules or plugins for Moodle 2, considering that Moodle 2 is such a big upgrade and so much of the Moodle 2 core code has changed significantly?
--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 11:19, 5 October 2010 (UTC)

: In terms of whether someone is able to write code for Moodle 2.0, we can divide people into various levels:

:# People who cannot program in any computer language.
:# People who can program in at least one computer language.
:# People who can program in PHP
:# People who can write code for at least one version of Moodle.
:# People who can write code for Moodle 2.0.

: I think that the gaps between each level in that hierarchy get smaller with each step you take. In the Moodle 1.9 world, this book was designed to take you from Level 3 to the old equivalent of level 5. With Moodle 2.0, it only takes you from Level 3 to Level 4, but that is significantly more than half way.

: If you know nothing about Moodle development, the fastest way to get started is probably to read the book, and then tread the tutorials here about converting Moodle 1.9 code to Moodle 2.0.

: So, the book is still useful. It would be excellent if (when) the book is updated to Moodle 2.0, but I don't think anyone is working on that yet.--[[User:Tim Hunt|Tim Hunt]] 18:53, 5 October 2010 (UTC)

Talk:version.php

2014-02-10T09:08:47Z

Rrf5000: /* Version string and dependencies */ new section

Anthony, I reverted your changes. They contradict [[Coding_style#Files]].--[[User:Tim Hunt|Tim Hunt]] 16:15, 29 March 2013 (WST)

== Cron ==

To me this seems wrong:

> $plugin->cron = 0;
> Optional - time interval (in seconds) between calls to the plugin's 'cron' function; set to 0 to disable the cron function calls.

I've just noticed a plugin with cron = 0 running after I added a lib.php cron function there - the idea was to develop first then enable the cron, but logs show it runs every time system cron runs. Moodle 2.3.8 but I cannot find if this is a bug or just wrong documentation.
Anyone know which it should be? --[[User:Jason Robinson|Jason Robinson]] ([[User talk:Jason Robinson|talk]]) 17:09, 21 November 2013 (WST)

== Version string and dependencies ==

For the version string ("$plugin->version"), what exactly is the purpose of the "xx" part of the string? Is it meant for if there are multiple releases on a single day (because the author had to fix something urgently that day)? Or is it meant for if there are multiple minor revisions over time based on a major release?

Is "ANY_VERSION" actually a constant in Moodle for dependency checking? This wasn't immediately clear from this page.

Is there a method for setting a maximum version of a dependency?

--[[User:Ryan Foster|Ryan Foster]] ([[User talk:Ryan Foster|talk]]) 17:08, 10 February 2014 (WST)

Authentication plugins

2013-12-19T20:09:05Z

Rrf5000: /* File structure */

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_plugins</tt> table in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

=== <tt>user_login($username, $password)</tt>===
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.

=== <tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
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

=== <tt>prevent_local_passwords()</tt>===
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()

=== <tt>is_synchronised_with_external()</tt>===
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()

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>can_signup()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

=== <tt>can_be_manually_set()</tt> ===
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.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Talk:Authentication plugins

2013-09-23T20:01:40Z

Rrf5000: /* prevent_local_passwords() documentation */

To make the title and description translations of the plugin work, you must also create the class constructor.

== prevent_local_passwords() documentation ==

The current documentation states:

:: Indicates if password hashes should be stored in local moodle database.

The code in auth/none has no comments regarding this method. Am I to assume that using "return false" allows password hashes to be stored in Moodle's database and "return true" ''prevents'' password hashes from being stored in Moodle's database?

--[[User:Ryan Foster|Ryan Foster]] ([[User talk:Ryan Foster|talk]]) 04:21, 18 September 2013 (WST)

: I found that there were comments in lib/authlib.php.

: --[[User:Ryan Foster|Ryan Foster]] ([[User talk:Ryan Foster|talk]]) 04:01, 24 September 2013 (WST)

== Overriding functions ==

It seems there is some ambiguity about which functions should be overridden. For example, I'd imagine that get_title() and get_description() are not meant to be overridden, but there appears to be nothing stopping a developer from doing so. Should this be marked here in the docs, commented in the code, or disallowed by making such functions "final"?

--[[User:Ryan Foster|Ryan Foster]] ([[User talk:Ryan Foster|talk]]) 06:50, 21 September 2013 (WST)

Talk:Authentication plugins

2013-09-20T22:50:16Z

Rrf5000: /* Overriding functions */ new section

To make the title and description translations of the plugin work, you must also create the class constructor.

== prevent_local_passwords() documentation ==

The current documentation states:

:: Indicates if password hashes should be stored in local moodle database.

The code in auth/none has no comments regarding this method. Am I to assume that using "return false" allows password hashes to be stored in Moodle's database and "return true" ''prevents'' password hashes from being stored in Moodle's database?

--[[User:Ryan Foster|Ryan Foster]] ([[User talk:Ryan Foster|talk]]) 04:21, 18 September 2013 (WST)

== Overriding functions ==

It seems there is some ambiguity about which functions should be overridden. For example, I'd imagine that get_title() and get_description() are not meant to be overridden, but there appears to be nothing stopping a developer from doing so. Should this be marked here in the docs, commented in the code, or disallowed by making such functions "final"?

--[[User:Ryan Foster|Ryan Foster]] ([[User talk:Ryan Foster|talk]]) 06:50, 21 September 2013 (WST)

Authentication plugins

2013-09-20T22:32:02Z

Rrf5000: /* can_confirm() */ Adding formatted information about default return value.

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

=== <tt>user_login($username, $password)</tt>===
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.

=== <tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
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

=== <tt>prevent_local_passwords()</tt>===
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()

=== <tt>is_synchronised_with_external()</tt>===
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()

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>can_signup()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Authentication plugins

2013-09-20T22:30:22Z

Rrf5000: /* Interfacing to API's */ Adding can_signup() with formatted information on default return values.

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

=== <tt>user_login($username, $password)</tt>===
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.

=== <tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
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

=== <tt>prevent_local_passwords()</tt>===
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()

=== <tt>is_synchronised_with_external()</tt>===
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()

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>can_signup()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Authentication plugins

2013-09-20T22:28:26Z

Rrf5000: /* can_reset_password() */ Adding formatted information about default return value.

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

=== <tt>user_login($username, $password)</tt>===
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.

=== <tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
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

=== <tt>prevent_local_passwords()</tt>===
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()

=== <tt>is_synchronised_with_external()</tt>===
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()

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Authentication plugins

2013-09-20T22:20:04Z

Rrf5000: /* prevent_local_passwords() */ Adding formatted information on default return values.

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

=== <tt>user_login($username, $password)</tt>===
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.

=== <tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
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

=== <tt>prevent_local_passwords()</tt>===
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()

=== <tt>is_synchronised_with_external()</tt>===
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()

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Authentication plugins

2013-09-20T22:14:24Z

Rrf5000: /* Interfacing to API's */ Adding is_synchronised_with_external() with formatted information on default return values.

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

=== <tt>user_login($username, $password)</tt>===
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.

=== <tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
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

=== <tt>prevent_local_passwords()</tt>===
Indicates if password hashes should be stored in local moodle database.

=== <tt>is_synchronised_with_external()</tt>===
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()

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Authentication plugins

2013-09-20T22:05:32Z

Rrf5000: /* Interfacing to API's */ Adding is_internal() with formatted information on default return values.

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.
=== <tt>user_login($username, $password)</tt>===
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.

===<tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

===<tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
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

=== <tt>prevent_local_passwords()</tt>===
Indicates if password hashes should be stored in local moodle database.

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Authentication plugins

2013-09-20T22:02:36Z

Rrf5000: /* can_edit_profile() */ Adding formatted information about default return value.

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.
=== <tt>user_login($username, $password)</tt>===
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.

===<tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

===<tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>prevent_local_passwords()</tt>===
Indicates if password hashes should be stored in local moodle database.

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Authentication plugins

2013-09-20T21:55:55Z

Rrf5000: /* can_change_password() */

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.
=== <tt>user_login($username, $password)</tt>===
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.

===<tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>prevent_local_passwords()</tt>===
Indicates if password hashes should be stored in local moodle database.

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Authentication plugins

2013-09-20T21:52:05Z

Rrf5000: /* can_change_password() */

==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 ===
[[File:1.9.11_login_element.png|203px||thumb|right|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. Then the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) 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 <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> 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.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 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 <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> 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 <nowiki>[[auth_sentrytitle]]</nowiki>. 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 <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> 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 <tt>mdl_config_pluginstable</tt> in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# 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 <tt>mdl_user</tt> 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):
## Calls the <tt>user_login()</tt> 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.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.
=== <tt>user_login($username, $password)</tt>===
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.

===<tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; Return type : boolean
; Default return value : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>prevent_local_passwords()</tt>===
Indicates if password hashes should be stored in local moodle database.

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
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.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Talk:Authentication plugins

2013-09-17T20:21:56Z

Rrf5000: /* prevent_local_passwords() documentation */ new section