Merge pull request #111 from MagnusSamuelsson/feature/add-id-auth

Added possibility to sign in users by internal user database id

Author: dmitriim

README.md

@@ -12,9 +12,9 @@ URL to be log in to Moodle without typing username and password.
 
 # Versions and branches
 
-| Moodle Version   | Branch            | 
+| Moodle Version   | Branch            |
 |------------------|-------------------|
-| Moodle 4.5+      | MOODLE_405_STABLE | 
+| Moodle 4.5+      | MOODLE_405_STABLE |
 | Moodle 3.3 - 4.1 | MOODLE_33PLUS     |
 
 Using
@@ -64,6 +64,14 @@ For example XML-RPC (PHP structure) description for different mapping field sett
             [idnumber] => string
             )
 
+***Database Id***
+
+    [user] =>
+        Array
+            (
+            [id] => int
+            )
+
 ***Web service will return following structure or standard Moodle webservice error message.***
 
     Array
@@ -104,21 +112,21 @@ E.g. http://yourmoodle.com/login/index.php?enrolkey_skipsso=1
 
 **Logout URL**
 
-If you need to logout users after they logged out from the external application, you can redirect them 
-to logout script with required parameter "return". 
+If you need to logout users after they logged out from the external application, you can redirect them
+to logout script with required parameter "return".
 
-E.g. http://yourmoodle.com/auth/userkey/logout.php?return=www.google.com 
+E.g. http://yourmoodle.com/auth/userkey/logout.php?return=www.google.com
 
 
-Users will be logged out from Moodle and then redirected to the provided URL. 
-In case when a user session is already expired, the user will be still redirected.  
-  
+Users will be logged out from Moodle and then redirected to the provided URL.
+In case when a user session is already expired, the user will be still redirected.
+
 
 **Example client**
 
 **Note:** the code below is not for production use. It's just a quick and dirty way to test the functionality.
 
-The code below defines a function that can be used to obtain a login url. 
+The code below defines a function that can be used to obtain a login url.
 You will need to add/remove parameters depending on whether you have update/create user enabled and which mapping field you are using.
 
 The required library curl can be obtained from https://github.com/moodlehq/sample-ws-clients
@@ -136,7 +144,7 @@ The required library curl can be obtained from https://github.com/moodlehq/sampl
  */
 function getloginurl($useremail, $firstname, $lastname, $username, $courseid = null, $modname = null, $activityid = null) {
     require_once('curl.php');
-        
+
     $token        = 'YOUR_TOKEN';
     $domainname   = 'http://MOODLE_WWW_ROOT';
     $functionname = 'auth_userkey_request_login_url';
@@ -145,19 +153,19 @@ function getloginurl($useremail, $firstname, $lastname, $username, $courseid = n
         'user' => [
             'firstname' => $firstname, // You will not need this parameter, if you are not creating/updating users
             'lastname'  => $lastname, // You will not need this parameter, if you are not creating/updating users
-            'username'  => $username, 
+            'username'  => $username,
             'email'     => $useremail,
         ]
     ];
 
     $serverurl = $domainname . '/webservice/rest/server.php' . '?wstoken=' . $token . '&wsfunction=' . $functionname . '&moodlewsrestformat=json';
-    $curl = new curl; // The required library curl can be obtained from https://github.com/moodlehq/sample-ws-clients 
+    $curl = new curl; // The required library curl can be obtained from https://github.com/moodlehq/sample-ws-clients
 
     try {
         $resp     = $curl->post($serverurl, $param);
         $resp     = json_decode($resp);
         if ($resp && !empty($resp->loginurl)) {
-            $loginurl = $resp->loginurl;        
+            $loginurl = $resp->loginurl;
         }
     } catch (Exception $ex) {
         return false;
@@ -192,7 +200,7 @@ https://www.catalyst-au.net/
 
 # Contributing and Support
 
-Issues, and pull requests using github are welcome and encouraged! 
+Issues, and pull requests using github are welcome and encouraged!
 
 https://github.com/catalyst/moodle-auth_userkey/issues
 

auth.php

@@ -481,6 +481,7 @@ public function get_allowed_mapping_fields() {
             'username' => get_string('username'),
             'email' => get_string('email'),
             'idnumber' => get_string('idnumber'),
+            'id' => get_string('userid', 'auth_userkey'),
         ];
     }
 
@@ -519,6 +520,15 @@ protected function get_mapping_parameter() {
                     ),
                 ];
                 break;
+            case 'id':
+                $parameter = [
+                    'id' => new external_value(
+                        PARAM_INT,
+                        'Database ID of the user'
+                    ),
+                ];
+                break;
+
 
             default:
                 $parameter = [];

lang/en/auth_userkey.php

@@ -52,4 +52,5 @@
 $string['ssourl_desc'] = 'URL of the SSO host to redirect users to. If defined users will be redirected here on login instead of the Moodle Login page';
 $string['updateuser'] = 'Update user?';
 $string['updateuser_desc'] = 'If enabled, users will be updated with the properties supplied when the webservice is called.';
+$string['userid'] = 'User ID';
 $string['userkey:generatekey'] = 'Generate login user key';

tests/auth_plugin_test.php

@@ -231,6 +231,20 @@ public function test_throwing_exception_if_mapping_field_idnumber_is_not_provide
         $actual = $this->auth->get_login_url($user);
     }
 
+    /**
+     * Test that auth plugin throws correct exception if id mapping field is not provided, but set in configs.
+     */
+    public function test_throwing_exception_if_mapping_field_id_is_not_provided(): void {
+        $user = [];
+        set_config('mappingfield', 'id', 'auth_userkey');
+        $this->auth = new auth_plugin_userkey();
+
+        $this->expectException(invalid_parameter_exception::class);
+        $this->expectExceptionMessage('Invalid parameter value detected (Required field "id" is not set or empty.)');
+
+        $actual = $this->auth->get_login_url($user);
+    }
+
     /**
      * Test that auth plugin throws correct exception if we trying to request not existing user.
      */
@@ -572,6 +586,7 @@ public function test_get_allowed_mapping_fields_list(): void {
             'username' => 'Username',
             'email' => 'Email address',
             'idnumber' => 'ID number',
+            'id' => 'User ID',
         ];
 
         $actual = $this->auth->get_allowed_mapping_fields();
@@ -622,6 +637,20 @@ public function test_get_request_login_url_user_parameters_based_on_plugin_confi
         $actual = $this->auth->get_request_login_url_user_parameters();
         $this->assertEquals($expected, $actual);
 
+        // Check user id.
+        set_config('mappingfield', 'id', 'auth_userkey');
+        $this->auth = new auth_plugin_userkey();
+
+        $expected = [
+            'id' => new external_value(
+                PARAM_INT,
+                'Database ID of the user'
+            ),
+        ];
+
+        $actual = $this->auth->get_request_login_url_user_parameters();
+        $this->assertEquals($expected, $actual);
+
         // Check some junk field name.
         set_config('mappingfield', 'junkfield', 'auth_userkey');
         $this->auth = new auth_plugin_userkey();

tests/externallib_test.php

@@ -138,6 +138,23 @@ public function test_successful_webservice_calls(): void {
         $this->assertTrue(key_exists('loginurl', $result));
         $this->assertEquals($expectedurl, $result['loginurl']);
 
+        // Database Id.
+        set_config('mappingfield', 'id', 'auth_userkey');
+        $params = [
+            'id' => $this->user->id,
+        ];
+
+        // Simulate the web service server.
+        $result = auth_userkey_external::request_login_url($params);
+        $result = external_api::clean_returnvalue(auth_userkey_external::request_login_url_returns(), $result);
+
+        $actualkey = $DB->get_record('user_private_key', ['userid' => $this->user->id]);
+        $expectedurl = $CFG->wwwroot . '/auth/userkey/login.php?key=' . $actualkey->value;
+
+        $this->assertTrue(is_array($result));
+        $this->assertTrue(key_exists('loginurl', $result));
+        $this->assertEquals($expectedurl, $result['loginurl']);
+
         // IP restriction.
         set_config('iprestriction', true, 'auth_userkey');
         set_config('mappingfield', 'idnumber', 'auth_userkey');

version.php

@@ -24,8 +24,8 @@
 
 defined('MOODLE_INTERNAL') || die;
 
-$plugin->version   = 2022081902;        // The current plugin version (Date: YYYYMMDDXX).
-$plugin->release   = 2022081902;        // Match release exactly to version.
+$plugin->version   = 2025120300;        // The current plugin version (Date: YYYYMMDDXX).
+$plugin->release   = 2025120300;        // Match release exactly to version.
 $plugin->requires  = 2017051500;        // Requires Moodle 3.3 version.
 $plugin->component = 'auth_userkey';    // Full name of the plugin (used for diagnostics).
 $plugin->maturity  = MATURITY_STABLE;