From 19f417f6c330108edfa1480b9c5f0459f2b8d4f5 Mon Sep 17 00:00:00 2001 From: skodak Date: Thu, 22 Mar 2007 13:28:41 +0000 Subject: [PATCH] (MDL-8973) Fix OOP model of new multi auth plugins - updated docs --- auth/README | 174 +++++------------------------------------- auth/README2 | 91 ---------------------- auth/nologin/auth.php | 32 +++----- lib/authlib.php | 37 +++++++-- 4 files changed, 63 insertions(+), 271 deletions(-) delete mode 100644 auth/README2 diff --git a/auth/README b/auth/README index ac074c2b234..a771a112512 100644 --- a/auth/README +++ b/auth/README @@ -10,6 +10,7 @@ Even when external forms of authentication are being used, Moodle still maintains the internal "user" table with all the associated information about that user such as name, email address and so on. + Multiauthentication in Moodle 1.8 ------------------------------------- @@ -36,6 +37,12 @@ none - no authentication at all .. very insecure!! - when user tries to access a course they are forced to set up their account details + +nologin - user can not log in, login as is possible + + - this plugin can be used to prevent normal user login + + manual - internal authentication only - user logs in using username and password @@ -94,6 +101,9 @@ db - Uses an external database to check username/password Authentication API ------------------ + +AUTHENTICATION PLUGINS +---------------------- Each authentication plugin is now contained in a subfolder as a class definition in the auth.php file. For instance, the LDAP authentication plugin is the class called auth_plugin_ldap defined in: @@ -105,13 +115,11 @@ get_auth_plugin() that does the work for you: $ldapauth = get_auth_plugin('ldap'); -If an auth is not specified, get_auth_plugin() will return you the auth plugin -defined in the $CFG->auth variable. +Auth plugin classes are pretty basic and should be extending auth_plugin_base class. +They contain the same functions that were previously in each plugin's lib.php file, +but refactored to become class methods, and tweaked to reference the plugin's instantiated config +to get at the settings, rather than the global $CFG variable. -Auth plugin classes are pretty basic. They contain the same functions that were -previously in each plugin's lib.php file, but refactored to become class -methods, and tweaked to reference the plugin's instantiated config to get at the -settings, rather than the global $CFG variable. Configuration ----------------- @@ -130,12 +138,6 @@ is now accessed as Authentication settings have been moved to the config_plugins database table, with the plugin field set to "auth/foo" (for instance, "auth/ldap"). -Upgrading from Moodle 1.7 ------------------------------ - -Moodle will upgrade the old auth settings (in $CFG->auth_foobar where foo is the -auth plugin and bar is the setting) to the new style in the config_plugin -database table. Method Names ----------------- @@ -153,147 +155,13 @@ this also avoids having to worry about which auth/lib file to include since Moodle takes care of it for you when you create an instance with get_auth_plugin(). -Code Usage ------------------ - -Code calling auth plugins can use method_exists() to determine plugin -functionality, much in the same way that function_exists() was used until now. -In addition, auth plugins provide some methods by default that can be called: - -user_login($username, $password) - This is the primary method that is used by the authenticate_user_login() - function in moodlelib.php. This method should return a boolean indicating - whether or not the username and password authenticate successfully. - -is_internal() - Returns true if this authentication plugin is "internal" (which means that - Moodle stores the users' passwords and other details in the local Moodle - database). - -can_change_password() - Returns true if the plugin can change the users' passwords. - -change_password_url() - Returns the URL for changing the users' passwords, or false if the default - URL can be used. - -user_update_password($user, $newpassword) - Updates the user's password. In previous versions of Moodle, the function - auth_user_update_password accepted a username as the first parameter. The - revised function expects a user object. - -config_form() - Displays the configuration form for the auth plugin, for use in the admin - pages. - -process_config() - Saves the auth plugin's configuration to the database. - -Other Methods ------------------- - -Most of functions are from ldap-authentication module and are not implemented -(yet?) on other modules. Please feel free to extend other modules to support -same features or roll your own module. - -Some of the new functions are still to be tested and are not documented here -yet. - -AUTHENTICATION - -Basic fuctions to authenticate users with external db. - -Mandatory: - - auth_plugin_foo() - - Constructor. At the least, it populates config member variable with settings - from the Moodle database. It makes sense to put other startup code here. - - user_login($username, $password) - - Authenticate username, password with userdatabase. - - Returns: - true if the username and password work - and false if they don't - -Optional: - - get_userinfo($username) - - Query other userinformation from database. - - Returns: - Userinformation in array ( name => value, .... - or false in case of error +The basic class defines all applicable methods that moodle uses, you can find +more information in lib/authlib.php file. - validate_form(&$form, &$err) - - Validate form data. - - Returns: - Bool. Manipulates $form and $err arrays in place - - -COURSE CREATING - - iscreator($username) - - should user have rights to create courses - - Returns: - True if user have rights to crete cources otherwise false - - -USER CREATION - -Functions that enable usercreation, activation and deactivation -from moodle to external database - - - user_exists ($username) - - Checks if given username exist on external db - - Returns: - true if given usernname exist or false - - - user_create ($userobject,$plainpass) - - Creates new user to external db. User should be created - in inactive stage until confirmed by email. - - Returns: - True on success otherwise false - - - user_activate ($username) - - activate new user after email-address is confirmed - - Returns: - True on success otherwise false - - - user_disable ($username) { - - deactivate user in external db. - - Returns: - True on success otherwise false - - - -USER INFORMATION AND SYNCRONIZATION - - get_userlist () - - Get list of usernames in external db. - - Returns: - All usernames in array or false on error. - +Upgrading from Moodle 1.7 +----------------------------- +Moodle will upgrade the old auth settings (in $CFG->auth_foobar where foo is the +auth plugin and bar is the setting) to the new style in the config_plugin +database table. diff --git a/auth/README2 b/auth/README2 deleted file mode 100644 index 2934800fa14..00000000000 --- a/auth/README2 +++ /dev/null @@ -1,91 +0,0 @@ -AUTHENTICATION PLUGINS ----------------------- -Each authentication plugin is now contained in a subfolder as a class definition -in the auth.php file. For instance, the LDAP authentication plugin is the class -called auth_plugin_ldap defined in: - - /auth/ldap/auth.php - -To instantiate the class, there is a function in lib/moodlelib called -get_auth_plugin() that does the work for you: - - $ldapauth = get_auth_plugin('ldap'); - -Auth plugin classes are pretty basic. They contain the same functions that were -previously in each plugin's lib.php file, but refactored to become class -methods, and tweaked to reference the plugin's instantiated config to get at the -settings, rather than the global $CFG variable. - -Configuration ------------------ - -All auth plugins must have a config property that contains the name value pairs -from the config_plugins table. This is populated using the get_config() function -in the constructor. The settings keys have also had the "auth_" prefix, as well -as the auth plugin name, trimmed. For instance, what used to be - - echo $CFG->auth_ldapversion; - -is now accessed as - - echo $ldapauth->config->version; - -Authentication settings have been moved to the config_plugins database table, -with the plugin field set to "auth/foo" (for instance, "auth/ldap"). - -Method Names ------------------ - -When the functions from lib.php were ported to methods in auth.php, the "auth_" -prefix was dropped. For instance, calls to - - auth_user_login($user, $pass); - -now become - - $ldapauth->user_login($user, $pass); - -this also avoids having to worry about which auth/lib file to include since -Moodle takes care of it for you when you create an instance with -get_auth_plugin(). - -Code Use ------------------ - -Code calling auth plugins can use method_exists() to determine plugin -functionality, much in the same way that function_exists() was used until now. -In addition, auth plugins provide some methods by default that can be called: - -user_login($username, $password) - This is the primary method that is used by the authenticate_user_login() - function in moodlelib.php. This method should return a boolean indicating - whether or not the username and password authenticate successfully. - Both parameter must have magic quotes applied. - -is_internal() - Returns true if this authentication plugin is "internal" (which means that - Moodle stores the users' passwords and other details in the local Moodle - database). - -can_change_password() - Returns true if the plugin can change the users' passwords. - -change_password_url() - Returns the URL for changing the users' passwords, or false if the default - URL can be used. - -Other Methods ------------------ - -get_userinfo($username) - This method should return an array of fields from the authentication source - for the given username. Username parameter must have magic quotes applied. - The returned array does not have magic quotes applied. - -Upgrading from Moodle 1.7 ------------------------------ - -Moodle will upgrade the old auth settings (in $CFG->auth_foobar where foo is the -auth plugin and bar is the setting) to the new style in the config_plugin -database table. - diff --git a/auth/nologin/auth.php b/auth/nologin/auth.php index f91ec9c8a7f..91070593673 100644 --- a/auth/nologin/auth.php +++ b/auth/nologin/auth.php @@ -1,7 +1,7 @@ libdir.'/authlib.php'); /** - * Plugin for no authentication. + * Plugin for no authentication - disabled user. */ class auth_plugin_nologin extends auth_plugin_base { @@ -32,10 +32,10 @@ class auth_plugin_nologin extends auth_plugin_base { } /** - * Do not allow any login + * Do not allow any login. * */ - function user_login ($username, $password) { + function user_login($username, $password) { return false; } @@ -47,18 +47,17 @@ class auth_plugin_nologin extends auth_plugin_base { } /** - * Returns true if this authentication plugin is 'internal'. + * No external data sync. * * @return bool */ function is_internal() { //we do not know if it was internal or external originally - return false; + return true; } /** - * Returns true if this authentication plugin can change the user's - * password. + * No changing of password. * * @return bool */ @@ -67,21 +66,10 @@ class auth_plugin_nologin extends auth_plugin_base { } /** - * Prints a form for configuring this authentication plugin. - * - * This function is called from admin/auth.php, and outputs a full page with - * a form for configuring this plugin. - * - * @param array $page An object containing all the data for this page. + * No password resetting. */ - function config_form($config, $err, $user_fields) { - } - - /** - * Processes and stores configuration data for this authentication plugin. - */ - function process_config($config) { - return true; + function can_reset_password() { + return false; } } diff --git a/lib/authlib.php b/lib/authlib.php index d701a2d2646..67fbd13b673 100644 --- a/lib/authlib.php +++ b/lib/authlib.php @@ -56,6 +56,11 @@ class auth_plugin_base { var $authtype; /** + + * This is the primary method that is used by the authenticate_user_login() + * function in moodlelib.php. This method should return a boolean indicating + * whether or not the username and password authenticate successfully. + * * Returns true if the username and password work and false if they are * wrong or don't exist. * @@ -69,7 +74,7 @@ class auth_plugin_base { } /** - * Returns true if this authentication plugin can change the user's + * Returns true if this authentication plugin can change the users' * password. * * @return bool @@ -80,8 +85,8 @@ class auth_plugin_base { } /** - * Returns the URL for changing the user's pw, or empty if the default can - * be used. + * Returns the URL for changing the users' passwords, or empty if the default + * URL can be used. This method is used if can_change_password() returns true. * * @return string */ @@ -91,7 +96,9 @@ class auth_plugin_base { } /** - * Returns true if this authentication plugin is 'internal'. + * Returns true if this authentication plugin is "internal" (which means that + * Moodle stores the users' passwords and other details in the local Moodle + * database). * * @return bool */ @@ -101,7 +108,9 @@ class auth_plugin_base { } /** - * Change a user's password + * Updates the user's password. In previous versions of Moodle, the function + * auth_user_update_password accepted a username as the first parameter. The + * revised function expects a user object. * * @param object $user User table object (with system magic quotes) * @param string $newpassword Plaintext password (with system magic quotes) @@ -237,6 +246,16 @@ class auth_plugin_base { return array(); } + /** + * Prints a form for configuring this authentication plugin. + * + * This function is called from admin/auth.php, and outputs a full page with + * a form for configuring this plugin. + */ + function config_form($config, $err, $user_fields) { + //override if needed + } + /** * A chance to validate form data, and last chance to * do stuff before it is inserted in config_plugin @@ -245,6 +264,14 @@ class auth_plugin_base { //override if needed } + /** + * Processes and stores configuration data for this authentication plugin. + */ + function process_config($config) { + //override if needed + return true; + } + /** * Prelogin actions. */