MDL-8973 auth hooks final cleanup; merged from MOODLE_18_STABLE

auth/README

@@ -125,8 +125,7 @@ When creating new plugins you can either extend the abstract auth_plugin_base cl
 auth_plugin_base.
 
 The new plugin architecture allows creating of more advanced types such as custom SSO
-without the need to patch login and logout pages (see prelogin_hook() and prelogout_hook()
-methods in existing plugins).
+without the need to patch login and logout pages (see *_hook() methods in existing plugins).
 
 Configuration
 -----------------

auth/cas/auth.php

@@ -220,7 +220,7 @@ function can_change_password() {
         return !empty($this->config->changepasswordurl);
     }
 
-    function prelogin_hook() {
+    function loginpage_hook() {
         // Load alternative login screens if necessary
         // TODO: fix the cas login screen
         return;
@@ -230,6 +230,11 @@ function prelogin_hook() {
         }
     }
 
+    function prelogout_hook() {
+        global $CFG;
+
+        require($CFG->dirroot.'/auth/cas/logout.php');
+    }
 
     /**
      * Prints a form for configuring this authentication plugin.

auth/mnet/auth.php

@@ -1003,8 +1003,12 @@ function cron() {
      *
      * @return   void
      */
-    function logout() {
+    function prelogout_hook() {
         global $MNET, $CFG, $USER;
+        if ($USER->auth != 'mnet') {
+            return;
+        }
+
         require_once $CFG->dirroot.'/mnet/xmlrpc/client.php';
 
         // If the user is local to this Moodle:
@@ -1334,7 +1338,7 @@ function can_login_remotely($username, $mnethostid) {
         return $accessctrl == 'allow';
     }
 
-    function prelogout_hook() {
+    function logoutpage_hook() {
         global $USER, $CFG, $redirect;
 
         if (!empty($USER->mnethostid) and $USER->mnethostid != $CFG->mnet_localhost_id) {

auth/shibboleth/auth.php

@@ -146,7 +146,7 @@ function can_change_password() {
         return false;
     }
 
-    function prelogin_hook() {
+    function loginpage_hook() {
         global $SESSION, $CFG;
 
         //TODO: fix the code

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 @@ function user_login($username, $password) {
     }
 
     /**
-     * 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 @@ function can_change_password() {
     }
 
     /**
-     * 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 @@ function change_password_url() {
     }
 
     /**
-     * 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 @@ function is_internal() {
     }
 
     /**
-     * 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 @@ function get_userinfo($username) {
         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
@@ -246,34 +265,54 @@ function validate_form(&$form, &$err) {
     }
 
     /**
-     * Prelogin actions.
+     * Processes and stores configuration data for this authentication plugin.
      */
-    function prelogin_hook() {
+    function process_config($config) {
+        //override if needed
+        return true;
+    }
+
+    /**
+     * Hook for overriding behavior of login page.
+     * This method is called from login/index.php page for all enabled auth plugins.
+     */
+    function loginpage_hook() {
+        global $frm;  // can be used to override submitted login form
+        global $user; // can be used to replace authenticate_user_login()
+
         //override if needed
     }
 
     /**
      * Post authentication hook.
+     * This method is called from authenticate_user_login() for all enabled auth plugins.
+     *
+     * @param object $user user object, later used for $USER
+     * @param string $username (with system magic quotes)
+     * @param string $password plain text password (with system magic quotes)
      */
-    function user_authenticated_hook($user, $username, $password) {
-    /// TODO: review following code - looks hackish :-( mnet should obsole this, right?
-    /// Log in to a second system if necessary
-        global $CFG;
-
-        if (!empty($CFG->sso)) {
-            include_once($CFG->dirroot .'/sso/'. $CFG->sso .'/lib.php');
-            if (function_exists('sso_user_login')) {
-                if (!sso_user_login($username, $password)) {   // Perform the signon process
-                    notify('Second sign-on failed');
-                }
-            }
-        }
+    function user_authenticated_hook(&$user, $username, $password) {
+        //override if needed
     }
 
     /**
-     * Prelogout actions.
+     * Pre logout hook.
+     * This method is called from require_logout() for all enabled auth plugins,
      */
     function prelogout_hook() {
+        global $USER; // use $USER->auth to find the plugin used for login
+
+        //override if needed
+    }
+
+    /**
+     * Hook for overriding behavior of logout page.
+     * This method is called from login/logout.php page for all enabled auth plugins.
+     */
+    function logoutpage_hook() {
+        global $USER;     // use $USER->auth to find the plugin used for login
+        global $redirect; // can be used to override redirect after logout
+
         //override if needed
     }
 }

lib/moodlelib.php

@@ -1828,16 +1828,10 @@ function require_logout() {
     if (isloggedin()) {
         add_to_log(SITEID, "user", "logout", "view.php?id=$USER->id&course=".SITEID, $USER->id, 0, $USER->id);
 
-        //TODO: move following 2 ifs into auth plugins - add new logout hook
-        $authsequence = get_enabled_auth_plugins();
-
-        if (in_array('cas', $authsequence) and $USER->auth == 'cas' and !empty($CFG->cas_enabled)) {
-            require($CFG->dirroot.'/auth/cas/logout.php');
-        }
-
-        if (in_array('mnet', $authsequence) and $USER->auth == 'mnet') {
-            $authplugin = get_auth_plugin('mnet');;
-            $authplugin->logout();
+        $authsequence = get_enabled_auth_plugins(); // auths, in sequence
+        foreach($authsequence as $authname) {
+            $authplugin = get_auth_plugin($authname);
+            $authplugin->prelogout_hook();
         }
     }
 
@@ -2613,8 +2607,8 @@ function guest_user() {
  * Uses auth_ functions from the currently active auth module
  *
  * @uses $CFG
- * @param string $username  User's username
- * @param string $password  User's password
+ * @param string $username  User's username (with system magic quotes)
+ * @param string $password  User's password (with system magic quotes)
  * @return user|flase A {@link $USER} object or false if error
  */
 function authenticate_user_login($username, $password) {
@@ -2670,7 +2664,21 @@ function authenticate_user_login($username, $password) {
 
         $authplugin->sync_roles($user);
 
-        $authplugin->user_authenticated_hook($user, $username, $password);
+        foreach ($authsenabled as $hau) {
+            $hauth = get_auth_plugin($hau);
+            $hauth->user_authenticated_hook($user, $username, $password);
+        }
+
+    /// Log in to a second system if necessary
+    /// NOTICE: /sso/ will be moved to auth and deprecated soon; use user_authenticated_hook() instead
+        if (!empty($CFG->sso)) {
+            include_once($CFG->dirroot .'/sso/'. $CFG->sso .'/lib.php');
+            if (function_exists('sso_user_login')) {
+                if (!sso_user_login($username, $password)) {   // Perform the signon process
+                    notify('Second sign-on failed');
+                }
+            }
+        }
 
         return $user;
 

login/index.php

@@ -58,7 +58,7 @@
 $authsequence = get_enabled_auth_plugins(true); // auths, in sequence
 foreach($authsequence as $authname) {
     $authplugin = get_auth_plugin($authname);
-    $authplugin->prelogin_hook();
+    $authplugin->loginpage_hook();
 }
 
 //HTTPS is potentially required in this page

login/logout.php

@@ -18,7 +18,7 @@
     $authsequence = get_enabled_auth_plugins(); // auths, in sequence
     foreach($authsequence as $authname) {
         $authplugin = get_auth_plugin($authname);
-        $authplugin->prelogout_hook();
+        $authplugin->logoutpage_hook();
     }
 
     require_logout();

sso/README.txt

@@ -0,0 +1,2 @@
+NOTICE:
+/sso/ will be moved to /auth/ and deprecated; use user_authenticated_hook() instead