MDL-53306 auth: Add hook for auth plugins to access user object.

Add a hook for auth plugins to be able to modify or check a user, before
raising any authentication errors.

The auth plugin needs to add a public function like this:

/**
 * Pre user_login hook.
 * This method is called from authenticate_user_login() right after the user
 * object is generated. This gives the auth plugins an option to make adjustments
 * before the verification process starts.
 *
 * @param object $user user object, later used for $USER
*/
public function pre_user_login_hook(&$user) {
    // Override if needed.
}

auth/upgrade.txt

@@ -1,6 +1,11 @@
 This files describes API changes in /auth/* - plugins,
 information provided here is intended especially for developers.
 
+=== 3.2 ===
+
+* New auth hook - pre_user_login_hook() - available, triggered right after the user object is created.
+  This can be used to modify the user object before any authentication errors are raised.
+
 === 3.0 ===
 
 * login_signup_form::signup_captcha_enabled() now calls is_captcha_enabled() from the current auth plugin instead of from auth_email

lib/authlib.php

@@ -464,6 +464,18 @@ function pre_loginpage_hook() {
         // complete_user_login($user);
     }
 
+    /**
+     * Pre user_login hook.
+     * This method is called from authenticate_user_login() right after the user
+     * object is generated. This gives the auth plugins an option to make adjustments
+     * before the verification process starts.
+     *
+     * @param object $user user object, later used for $USER
+     */
+    public function pre_user_login_hook(&$user) {
+        // Override if needed.
+    }
+
     /**
      * Post authentication hook.
      * This method is called from authenticate_user_login() for all enabled auth plugins.

lib/moodlelib.php

@@ -4123,6 +4123,12 @@ function authenticate_user_login($username, $password, $ignorelockout=false, &$f
     if ($user) {
         // Use manual if auth not set.
         $auth = empty($user->auth) ? 'manual' : $user->auth;
+
+        if (in_array($user->auth, $authsenabled)) {
+            $authplugin = get_auth_plugin($user->auth);
+            $authplugin->pre_user_login_hook($user);
+        }
+
         if (!empty($user->suspended)) {
             $failurereason = AUTH_LOGIN_SUSPENDED;