Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Authentication plugins: Difference between revisions

From MoodleDocs
No edit summary
(Undo revision 82714 by Wmasterj (talk))
Line 1: Line 1:
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.
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 ==
== 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):
[[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):
Line 35: Line 34:
# Implement the user_login() function in your auth.php file, and create or override additional functions based on your plugin's requirements.
# Implement the user_login() function in your auth.php file, and create or override additional functions based on your plugin's requirements.
# Log in to your Moodle installation as a site administrator and find, in the site administrator block, the page "Users -> Authentication -> Manage authentication".  You will see your plugin in the list, appearing as <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.'''
# 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 /auth/sentry/lang, and under it, a directory for each language that your installation needs to support.  (Example: /auth/sentry/lang/en_us_utf8.)  Within each of these language directories, create a file called auth_sentry.php.  That file should set the desired value for $string['auth_sentrytitle'] for that language.  You can also set the plugin description by setting $string['auth_sentrydescription'], and you can also assign other translatable strings that your plugin uses, in these files.
# 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 /auth/sentry/lang, and under it, a directory for each language that your installation needs to support.  (Example: /auth/sentry/lang/en_us_utf8.)  Within each of these language directories, create a file called auth_sentry.php.  That file should set the desired value for $string['auth_sentrytitle'] for that language.  You can also set the plugin description by setting $string['auth_sentrydescription'], and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en_us_utf8''' 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 my system contained two folders named '''en''' and '''en_utf8'''. I 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 config_form() and process_config() in the plugin class.  You might find it convenient to use the 'db' plugin as a model for this.  The plugin's config settings can then be managed through the Manage authentication page by clicking on the Settings link for that plugin, and the values will be stored in the mdl_config_pluginstable in the database.
# If you want to configure your plugin through the Moodle UI, implement config_form() and process_config() in the plugin class.  You might find it convenient to use the 'db' plugin as a model for this.  The plugin's config settings can then be managed through the Manage authentication page by clicking on the Settings link for that plugin, and the values will be stored in the mdl_config_pluginstable in the database.



Revision as of 06:47, 12 April 2011

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

Overview of Moodle authentication process

The login UI element in Moodle 1.9

The authentication use case in Moodle starts when a user clicks on the Login link in the UI. Then the following happens (skipping some minor details and rarer scenarios):

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

authenticate_user_login()

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

  1. It gets a list of enabled authentication plugins.
  2. 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.)
  3. It creates a user object, which will contain the data from mdl_user if the username is known; if not, it will be an empty object.
  4. It does the following with the authentication plugin (note that for a username unknown to Moodle, it will do these steps for each authenticated plugin until one succeeds or it has tried them all):
    1. Calls the user_login() function provided by that plugin, which returns a boolean value based on whether the credentials authenticate or not. If the result is false (not authenticated), skips the rest of the steps below and continues to the next plugin.
    2. If the plugin authenticates against an external system (not Moodle's user database), its update_user_record() function is called to get the user's name, contact info, etc.
    3. Creates the Moodle user record if it doesn't already exist.
    4. Calls the plugin's sync_roles() function (I am not clear what this is exactly supposed to do).
    5. Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's user_authenticated_hook() function.
  5. It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

Creating an authentication plugin

To create and register an authentication plugin, do the following:

  1. Choose a name for your plugin. We'll use 'sentry' as an example below; change it to whatever name you have chosen.
  2. Under your Moodle installation root, create the directory /auth/sentry. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
  3. Create the file /auth/sentry/auth.php. Within the file, create a class auth_plugin_sentry that extends auth_plugin_base from /lib/authlib.php. (You will need to require_once the authlib file.)
  4. Implement the user_login() function in your auth.php file, and create or override additional functions based on your plugin's requirements.
  5. Log in to your Moodle installation as a site administrator and find, in the site administrator block, the page "Users -> Authentication -> Manage authentication". You will see your plugin in the list, appearing as [[auth_sentrytitle]]. You can enable it and move it up and down in the order. At this point, with the plugin enabled, your plugin is registered and will be used by Moodle in its authentication process.
  6. If you don't like seeing [[auth_sentrytitle]] as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory /auth/sentry/lang, and under it, a directory for each language that your installation needs to support. (Example: /auth/sentry/lang/en_us_utf8.) Within each of these language directories, create a file called auth_sentry.php. That file should set the desired value for $string['auth_sentrytitle'] for that language. You can also set the plugin description by setting $string['auth_sentrydescription'], and you can also assign other translatable strings that your plugin uses, in these files. Note: A folder named like en_us_utf8 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 my system contained two folders named en and en_utf8. I emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. (More info on how Moodle handles language).
  7. If you want to configure your plugin through the Moodle UI, implement config_form() and process_config() in the plugin class. You might find it convenient to use the 'db' plugin as a model for this. The plugin's config settings can then be managed through the Manage authentication page by clicking on the Settings link for that plugin, and the values will be stored in the mdl_config_pluginstable in the database.

See also