webservice/lib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17
  18 /**
  19  * Web services utility functions and classes
  20  *
  21  * @package    core_webservice
  22  * @copyright  2009 Jerome Mouneyrac <jerome@moodle.com>
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 use core_external\external_api;
  27 use core_external\external_multiple_structure;
  28 use core_external\external_settings;
  29 use core_external\external_single_structure;
  30 use core_external\external_value;
  31
  32 /**
  33  * WEBSERVICE_AUTHMETHOD_USERNAME - username/password authentication (also called simple authentication)
  34  */
  35 define('WEBSERVICE_AUTHMETHOD_USERNAME', 0);
  36
  37 /**
  38  * WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN - most common token authentication (external app, mobile app...)
  39  */
  40 define('WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN', 1);
  41
  42 /**
  43  * WEBSERVICE_AUTHMETHOD_SESSION_TOKEN - token for embedded application (requires Moodle session)
  44  */
  45 define('WEBSERVICE_AUTHMETHOD_SESSION_TOKEN', 2);
  46
  47 /**
  48  * General web service library
  49  *
  50  * @package    core_webservice
  51  * @copyright  2010 Jerome Mouneyrac <jerome@moodle.com>
  52  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  53  */
  54 class webservice {
  55     /**
  56      * Only update token last access once per this many seconds. (This constant controls update of
  57      * the external tokens last access field. There is a similar define LASTACCESS_UPDATE_SECS
  58      * which controls update of the web site last access fields.)
  59      *
  60      * @var int
  61      */
  62     const TOKEN_LASTACCESS_UPDATE_SECS = 60;
  63
  64     /**
  65      * Authenticate user (used by download/upload file scripts)
  66      *
  67      * @param string $token
  68      * @return array - contains the authenticated user, token and service objects
  69      */
  70     public function authenticate_user($token) {
  71         global $DB, $CFG;
  72
  73         // web service must be enabled to use this script
  74         if (!$CFG->enablewebservices) {
  75             throw new webservice_access_exception('Web services are not enabled in Advanced features.');
  76         }
  77
  78         // Obtain token record
  79         if (!$token = $DB->get_record('external_tokens', array('token' => $token))) {
  80             //client may want to display login form => moodle_exception
  81             throw new moodle_exception('invalidtoken', 'webservice');
  82         }
  83
  84         $loginfaileddefaultparams = array(
  85             'other' => array(
  86                 'method' => WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN,
  87                 'reason' => null,
  88                 'tokenid' => $token->id
  89             )
  90         );
  91
  92         // Validate token date
  93         if ($token->validuntil and $token->validuntil < time()) {
  94             $params = $loginfaileddefaultparams;
  95             $params['other']['reason'] = 'token_expired';
  96             $event = \core\event\webservice_login_failed::create($params);
  97             $event->add_record_snapshot('external_tokens', $token);
  98             $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '',
  99                 get_string('invalidtimedtoken', 'webservice'), 0));
 100             $event->trigger();
 101             $DB->delete_records('external_tokens', array('token' => $token->token));
 102             throw new webservice_access_exception('Invalid token - token expired - check validuntil time for the token');
 103         }
 104
 105         // Check ip
 106         if ($token->iprestriction and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {
 107             $params = $loginfaileddefaultparams;
 108             $params['other']['reason'] = 'ip_restricted';
 109             $event = \core\event\webservice_login_failed::create($params);
 110             $event->add_record_snapshot('external_tokens', $token);
 111             $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '',
 112                 get_string('failedtolog', 'webservice') . ": " . getremoteaddr(), 0));
 113             $event->trigger();
 114             throw new webservice_access_exception('Invalid token - IP:' . getremoteaddr()
 115                     . ' is not supported');
 116         }
 117
 118         //retrieve user link to the token
 119         $user = $DB->get_record('user', array('id' => $token->userid, 'deleted' => 0), '*', MUST_EXIST);
 120
 121         // let enrol plugins deal with new enrolments if necessary
 122         enrol_check_plugins($user, false);
 123
 124         // setup user session to check capability
 125         \core\session\manager::set_user($user);
 126         set_login_session_preferences();
 127
 128         //assumes that if sid is set then there must be a valid associated session no matter the token type
 129         if ($token->sid) {
 130             if (!\core\session\manager::session_exists($token->sid)) {
 131                 $DB->delete_records('external_tokens', array('sid' => $token->sid));
 132                 throw new webservice_access_exception('Invalid session based token - session not found or expired');
 133             }
 134         }
 135
 136         // Cannot authenticate unless maintenance access is granted.
 137         $hasmaintenanceaccess = has_capability('moodle/site:maintenanceaccess', context_system::instance(), $user);
 138         if (!empty($CFG->maintenance_enabled) and !$hasmaintenanceaccess) {
 139             //this is usually temporary, client want to implement code logic  => moodle_exception
 140             throw new moodle_exception('sitemaintenance', 'admin');
 141         }
 142
 143         //retrieve web service record
 144         $service = $DB->get_record('external_services', array('id' => $token->externalserviceid, 'enabled' => 1));
 145         if (empty($service)) {
 146             // will throw exception if no token found
 147             throw new webservice_access_exception('Web service is not available (it doesn\'t exist or might be disabled)');
 148         }
 149
 150         //check if there is any required system capability
 151         if ($service->requiredcapability and !has_capability($service->requiredcapability, context_system::instance(), $user)) {
 152             throw new webservice_access_exception('The capability ' . $service->requiredcapability . ' is required.');
 153         }
 154
 155         //specific checks related to user restricted service
 156         if ($service->restrictedusers) {
 157             $authoriseduser = $DB->get_record('external_services_users', array('externalserviceid' => $service->id, 'userid' => $user->id));
 158
 159             if (empty($authoriseduser)) {
 160                 throw new webservice_access_exception(
 161                         'The user is not allowed for this service. First you need to allow this user on the '
 162                         . $service->name . '\'s allowed users administration page.');
 163             }
 164
 165             if (!empty($authoriseduser->validuntil) and $authoriseduser->validuntil < time()) {
 166                 throw new webservice_access_exception('Invalid service - service expired - check validuntil time for this allowed user');
 167             }
 168
 169             if (!empty($authoriseduser->iprestriction) and !address_in_subnet(getremoteaddr(), $authoriseduser->iprestriction)) {
 170                 throw new webservice_access_exception('Invalid service - IP:' . getremoteaddr()
 171                     . ' is not supported - check this allowed user');
 172             }
 173         }
 174
 175         //only confirmed user should be able to call web service
 176         if (empty($user->confirmed)) {
 177             $params = $loginfaileddefaultparams;
 178             $params['other']['reason'] = 'user_unconfirmed';
 179             $event = \core\event\webservice_login_failed::create($params);
 180             $event->add_record_snapshot('external_tokens', $token);
 181             $event->set_legacy_logdata(array(SITEID, 'webservice', 'user unconfirmed', '', $user->username));
 182             $event->trigger();
 183             throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
 184         }
 185
 186         //check the user is suspended
 187         if (!empty($user->suspended)) {
 188             $params = $loginfaileddefaultparams;
 189             $params['other']['reason'] = 'user_suspended';
 190             $event = \core\event\webservice_login_failed::create($params);
 191             $event->add_record_snapshot('external_tokens', $token);
 192             $event->set_legacy_logdata(array(SITEID, 'webservice', 'user suspended', '', $user->username));
 193             $event->trigger();
 194             throw new moodle_exception('wsaccessusersuspended', 'moodle', '', $user->username);
 195         }
 196
 197         //check if the auth method is nologin (in this case refuse connection)
 198         if ($user->auth == 'nologin') {
 199             $params = $loginfaileddefaultparams;
 200             $params['other']['reason'] = 'nologin';
 201             $event = \core\event\webservice_login_failed::create($params);
 202             $event->add_record_snapshot('external_tokens', $token);
 203             $event->set_legacy_logdata(array(SITEID, 'webservice', 'nologin auth attempt with web service', '', $user->username));
 204             $event->trigger();
 205             throw new moodle_exception('wsaccessusernologin', 'moodle', '', $user->username);
 206         }
 207
 208         //Check if the user password is expired
 209         $auth = get_auth_plugin($user->auth);
 210         if (!empty($auth->config->expiration) and $auth->config->expiration == 1) {
 211             $days2expire = $auth->password_expire($user->username);
 212             if (intval($days2expire) < 0) {
 213                 $params = $loginfaileddefaultparams;
 214                 $params['other']['reason'] = 'password_expired';
 215                 $event = \core\event\webservice_login_failed::create($params);
 216                 $event->add_record_snapshot('external_tokens', $token);
 217                 $event->set_legacy_logdata(array(SITEID, 'webservice', 'expired password', '', $user->username));
 218                 $event->trigger();
 219                 throw new moodle_exception('passwordisexpired', 'webservice');
 220             }
 221         }
 222
 223         // log token access
 224         self::update_token_lastaccess($token);
 225
 226         return array('user' => $user, 'token' => $token, 'service' => $service);
 227     }
 228
 229     /**
 230      * Updates the last access time for a token.
 231      *
 232      * @param \stdClass $token Token object (must include id, lastaccess fields)
 233      * @param int $time Time of access (0 = use current time)
 234      * @throws dml_exception If database error
 235      */
 236     public static function update_token_lastaccess($token, int $time = 0) {
 237         global $DB;
 238
 239         if (!$time) {
 240             $time = time();
 241         }
 242
 243         // Only update the field if it is a different time from previous request,
 244         // so as not to waste database effort.
 245         if ($time >= $token->lastaccess + self::TOKEN_LASTACCESS_UPDATE_SECS) {
 246             $DB->set_field('external_tokens', 'lastaccess', $time, array('id' => $token->id));
 247         }
 248     }
 249
 250     /**
 251      * Allow user to call a service
 252      *
 253      * @param stdClass $user a user
 254      */
 255     public function add_ws_authorised_user($user) {
 256         global $DB;
 257         $user->timecreated = time();
 258         $DB->insert_record('external_services_users', $user);
 259     }
 260
 261     /**
 262      * Disallow a user to call a service
 263      *
 264      * @param stdClass $user a user
 265      * @param int $serviceid
 266      */
 267     public function remove_ws_authorised_user($user, $serviceid) {
 268         global $DB;
 269         $DB->delete_records('external_services_users',
 270                 array('externalserviceid' => $serviceid, 'userid' => $user->id));
 271     }
 272
 273     /**
 274      * Update allowed user settings (ip restriction, valid until...)
 275      *
 276      * @param stdClass $user
 277      */
 278     public function update_ws_authorised_user($user) {
 279         global $DB;
 280         $DB->update_record('external_services_users', $user);
 281     }
 282
 283     /**
 284      * Return list of allowed users with their options (ip/timecreated / validuntil...)
 285      * for a given service
 286      *
 287      * @param int $serviceid the service id to search against
 288      * @return array $users
 289      */
 290     public function get_ws_authorised_users($serviceid) {
 291         global $DB, $CFG;
 292
 293         $params = array($CFG->siteguest, $serviceid);
 294
 295         $userfields = \core_user\fields::for_identity(context_system::instance())->with_name()->excluding('id');
 296         $fieldsql = $userfields->get_sql('u');
 297
 298         $sql = " SELECT u.id as id, esu.id as serviceuserid {$fieldsql->selects},
 299                         esu.iprestriction as iprestriction, esu.validuntil as validuntil,
 300                         esu.timecreated as timecreated
 301                    FROM {user} u
 302                    JOIN {external_services_users} esu ON esu.userid = u.id
 303                         {$fieldsql->joins}
 304                   WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1
 305                         AND esu.externalserviceid = ?";
 306
 307         $users = $DB->get_records_sql($sql, array_merge($fieldsql->params, $params));
 308
 309         return $users;
 310     }
 311
 312     /**
 313      * Return an authorised user with their options (ip/timecreated / validuntil...)
 314      *
 315      * @param int $serviceid the service id to search against
 316      * @param int $userid the user to search against
 317      * @return stdClass
 318      */
 319     public function get_ws_authorised_user($serviceid, $userid) {
 320         global $DB, $CFG;
 321         $params = array($CFG->siteguest, $serviceid, $userid);
 322         $sql = " SELECT u.id as id, esu.id as serviceuserid, u.email as email, u.firstname as firstname,
 323                         u.lastname as lastname,
 324                         esu.iprestriction as iprestriction, esu.validuntil as validuntil,
 325                         esu.timecreated as timecreated
 326                    FROM {user} u, {external_services_users} esu
 327                   WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1
 328                         AND esu.userid = u.id
 329                         AND esu.externalserviceid = ?
 330                         AND u.id = ?";
 331         $user = $DB->get_record_sql($sql, $params);
 332         return $user;
 333     }
 334
 335     /**
 336      * Generate all tokens of a specific user
 337      *
 338      * @param int $userid user id
 339      */
 340     public function generate_user_ws_tokens($userid) {
 341         global $CFG, $DB;
 342
 343         // generate a token for non admin if web service are enable and the user has the capability to create a token
 344         if (!is_siteadmin() && has_capability('moodle/webservice:createtoken', context_system::instance(), $userid) && !empty($CFG->enablewebservices)) {
 345             // for every service than the user is authorised on, create a token (if it doesn't already exist)
 346
 347             // get all services which are set to all user (no restricted to specific users)
 348             $norestrictedservices = $DB->get_records('external_services', array('restrictedusers' => 0));
 349             $serviceidlist = array();
 350             foreach ($norestrictedservices as $service) {
 351                 $serviceidlist[] = $service->id;
 352             }
 353
 354             // get all services which are set to the current user (the current user is specified in the restricted user list)
 355             $servicesusers = $DB->get_records('external_services_users', array('userid' => $userid));
 356             foreach ($servicesusers as $serviceuser) {
 357                 if (!in_array($serviceuser->externalserviceid,$serviceidlist)) {
 358                      $serviceidlist[] = $serviceuser->externalserviceid;
 359                 }
 360             }
 361
 362             // get all services which already have a token set for the current user
 363             $usertokens = $DB->get_records('external_tokens', array('userid' => $userid, 'tokentype' => EXTERNAL_TOKEN_PERMANENT));
 364             $tokenizedservice = array();
 365             foreach ($usertokens as $token) {
 366                     $tokenizedservice[]  = $token->externalserviceid;
 367             }
 368
 369             // create a token for the service which have no token already
 370             foreach ($serviceidlist as $serviceid) {
 371                 if (!in_array($serviceid, $tokenizedservice)) {
 372                     // create the token for this service
 373                     $newtoken = new stdClass();
 374                     $newtoken->token = md5(uniqid(rand(),1));
 375                     // check that the user has capability on this service
 376                     $newtoken->tokentype = EXTERNAL_TOKEN_PERMANENT;
 377                     $newtoken->userid = $userid;
 378                     $newtoken->externalserviceid = $serviceid;
 379                     // TODO MDL-31190 find a way to get the context - UPDATE FOLLOWING LINE
 380                     $newtoken->contextid = context_system::instance()->id;
 381                     $newtoken->creatorid = $userid;
 382                     $newtoken->timecreated = time();
 383                     // Generate the private token, it must be transmitted only via https.
 384                     $newtoken->privatetoken = random_string(64);
 385
 386                     $DB->insert_record('external_tokens', $newtoken);
 387                 }
 388             }
 389
 390
 391         }
 392     }
 393
 394     /**
 395      * Return all tokens of a specific user
 396      * + the service state (enabled/disabled)
 397      * + the authorised user mode (restricted/not restricted)
 398      *
 399      * @param int $userid user id
 400      * @return array
 401      */
 402     public function get_user_ws_tokens($userid) {
 403         global $DB;
 404         //here retrieve token list (including linked users firstname/lastname and linked services name)
 405         $sql = "SELECT
 406                     t.id, t.creatorid, t.token, u.firstname, u.lastname, s.id as wsid, s.name, s.enabled, s.restrictedusers, t.validuntil
 407                 FROM
 408                     {external_tokens} t, {user} u, {external_services} s
 409                 WHERE
 410                     t.userid=? AND t.tokentype = ".EXTERNAL_TOKEN_PERMANENT." AND s.id = t.externalserviceid AND t.userid = u.id";
 411         $tokens = $DB->get_records_sql($sql, array( $userid));
 412         return $tokens;
 413     }
 414
 415     /**
 416      * Return a token that has been created by the user (i.e. to created by an admin)
 417      * If no tokens exist an exception is thrown
 418      *
 419      * The returned value is a stdClass:
 420      * ->id token id
 421      * ->token
 422      * ->firstname user firstname
 423      * ->lastname
 424      * ->name service name
 425      *
 426      * @param int $userid user id
 427      * @param int $tokenid token id
 428      * @return stdClass
 429      */
 430     public function get_created_by_user_ws_token($userid, $tokenid) {
 431         global $DB;
 432         $sql = "SELECT
 433                         t.id, t.token, u.firstname, u.lastname, s.name
 434                     FROM
 435                         {external_tokens} t, {user} u, {external_services} s
 436                     WHERE
 437                         t.creatorid=? AND t.id=? AND t.tokentype = "
 438                 . EXTERNAL_TOKEN_PERMANENT
 439                 . " AND s.id = t.externalserviceid AND t.userid = u.id";
 440         //must be the token creator
 441         $token = $DB->get_record_sql($sql, array($userid, $tokenid), MUST_EXIST);
 442         return $token;
 443     }
 444
 445     /**
 446      * Return a token of an arbitrary user by tokenid, including details of the associated user and the service name.
 447      * If no tokens exist an exception is thrown
 448      *
 449      * The returned value is a stdClass:
 450      * ->id token id
 451      * ->token
 452      * ->firstname user firstname
 453      * ->lastname
 454      * ->name service name
 455      *
 456      * @param int $tokenid token id
 457      * @return stdClass
 458      */
 459     public function get_token_by_id_with_details($tokenid) {
 460         global $DB;
 461         $sql = "SELECT t.id, t.token, u.id AS userid, u.firstname, u.lastname, s.name, t.creatorid
 462                 FROM {external_tokens} t, {user} u, {external_services} s
 463                 WHERE t.id=? AND t.tokentype = ? AND s.id = t.externalserviceid AND t.userid = u.id";
 464         $token = $DB->get_record_sql($sql, array($tokenid, EXTERNAL_TOKEN_PERMANENT), MUST_EXIST);
 465         return $token;
 466     }
 467
 468     /**
 469      * Return a database token record for a token id
 470      *
 471      * @param int $tokenid token id
 472      * @return object token
 473      */
 474     public function get_token_by_id($tokenid) {
 475         global $DB;
 476         return $DB->get_record('external_tokens', array('id' => $tokenid));
 477     }
 478
 479     /**
 480      * Delete a token
 481      *
 482      * @param int $tokenid token id
 483      */
 484     public function delete_user_ws_token($tokenid) {
 485         global $DB;
 486         $DB->delete_records('external_tokens', array('id'=>$tokenid));
 487     }
 488
 489     /**
 490      * Delete all the tokens belonging to a user.
 491      *
 492      * @param int $userid the user id whose tokens must be deleted
 493      */
 494     public static function delete_user_ws_tokens($userid) {
 495         global $DB;
 496         $DB->delete_records('external_tokens', array('userid' => $userid));
 497     }
 498
 499     /**
 500      * Delete a service
 501      * Also delete function references and authorised user references.
 502      *
 503      * @param int $serviceid service id
 504      */
 505     public function delete_service($serviceid) {
 506         global $DB;
 507         $DB->delete_records('external_services_users', array('externalserviceid' => $serviceid));
 508         $DB->delete_records('external_services_functions', array('externalserviceid' => $serviceid));
 509         $DB->delete_records('external_tokens', array('externalserviceid' => $serviceid));
 510         $DB->delete_records('external_services', array('id' => $serviceid));
 511     }
 512
 513     /**
 514      * Get a full database token record for a given token value
 515      *
 516      * @param string $token
 517      * @throws moodle_exception if there is multiple result
 518      */
 519     public function get_user_ws_token($token) {
 520         global $DB;
 521         return $DB->get_record('external_tokens', array('token'=>$token), '*', MUST_EXIST);
 522     }
 523
 524     /**
 525      * Get the functions list of a service list (by id)
 526      *
 527      * @param array $serviceids service ids
 528      * @return array of functions
 529      */
 530     public function get_external_functions($serviceids) {
 531         global $DB;
 532         if (!empty($serviceids)) {
 533             list($serviceids, $params) = $DB->get_in_or_equal($serviceids);
 534             $sql = "SELECT f.*
 535                       FROM {external_functions} f
 536                      WHERE f.name IN (SELECT sf.functionname
 537                                         FROM {external_services_functions} sf
 538                                        WHERE sf.externalserviceid $serviceids)
 539                      ORDER BY f.name ASC";
 540             $functions = $DB->get_records_sql($sql, $params);
 541         } else {
 542             $functions = array();
 543         }
 544         return $functions;
 545     }
 546
 547     /**
 548      * Get the functions of a service list (by shortname). It can return only enabled functions if required.
 549      *
 550      * @param array $serviceshortnames service shortnames
 551      * @param bool $enabledonly if true then only return functions for services that have been enabled
 552      * @return array functions
 553      */
 554     public function get_external_functions_by_enabled_services($serviceshortnames, $enabledonly = true) {
 555         global $DB;
 556         if (!empty($serviceshortnames)) {
 557             $enabledonlysql = $enabledonly?' AND s.enabled = 1 ':'';
 558             list($serviceshortnames, $params) = $DB->get_in_or_equal($serviceshortnames);
 559             $sql = "SELECT f.*
 560                       FROM {external_functions} f
 561                      WHERE f.name IN (SELECT sf.functionname
 562                                         FROM {external_services_functions} sf, {external_services} s
 563                                        WHERE s.shortname $serviceshortnames
 564                                              AND sf.externalserviceid = s.id
 565                                              " . $enabledonlysql . ")";
 566             $functions = $DB->get_records_sql($sql, $params);
 567         } else {
 568             $functions = array();
 569         }
 570         return $functions;
 571     }
 572
 573     /**
 574      * Get functions not included in a service
 575      *
 576      * @param int $serviceid service id
 577      * @return array functions
 578      */
 579     public function get_not_associated_external_functions($serviceid) {
 580         global $DB;
 581         $select = "name NOT IN (SELECT s.functionname
 582                                   FROM {external_services_functions} s
 583                                  WHERE s.externalserviceid = :sid
 584                                )";
 585
 586         $functions = $DB->get_records_select('external_functions',
 587                         $select, array('sid' => $serviceid), 'name');
 588
 589         return $functions;
 590     }
 591
 592     /**
 593      * Get list of required capabilities of a service, sorted by functions
 594      * Example of returned value:
 595      *  Array
 596      *  (
 597      *    [core_group_create_groups] => Array
 598      *    (
 599      *       [0] => moodle/course:managegroups
 600      *    )
 601      *
 602      *    [core_enrol_get_enrolled_users] => Array
 603      *    (
 604      *       [0] => moodle/user:viewdetails
 605      *       [1] => moodle/user:viewhiddendetails
 606      *       [2] => moodle/course:useremail
 607      *       [3] => moodle/user:update
 608      *       [4] => moodle/site:accessallgroups
 609      *    )
 610      *  )
 611      * @param int $serviceid service id
 612      * @return array
 613      */
 614     public function get_service_required_capabilities($serviceid) {
 615         $functions = $this->get_external_functions(array($serviceid));
 616         $requiredusercaps = array();
 617         foreach ($functions as $function) {
 618             $functioncaps = explode(',', $function->capabilities);
 619             if (!empty($functioncaps) and !empty($functioncaps[0])) {
 620                 foreach ($functioncaps as $functioncap) {
 621                     $requiredusercaps[$function->name][] = trim($functioncap);
 622                 }
 623             }
 624         }
 625         return $requiredusercaps;
 626     }
 627
 628     /**
 629      * Get user capabilities (with context)
 630      * Only useful for documentation purpose
 631      * WARNING: do not use this "broken" function. It was created in the goal to display some capabilities
 632      * required by users. In theory we should not need to display this kind of information
 633      * as the front end does not display it itself. In pratice,
 634      * admins would like the info, for more info you can follow: MDL-29962
 635      *
 636      * @deprecated since Moodle 3.11 in MDL-67748 without a replacement.
 637      * @todo MDL-70187 Please delete this method completely in Moodle 4.3, thank you.
 638      * @param int $userid user id
 639      * @return array
 640      */
 641     public function get_user_capabilities($userid) {
 642         global $DB;
 643
 644         debugging('webservice::get_user_capabilities() has been deprecated.', DEBUG_DEVELOPER);
 645
 646         //retrieve the user capabilities
 647         $sql = "SELECT DISTINCT rc.id, rc.capability FROM {role_capabilities} rc, {role_assignments} ra
 648             WHERE rc.roleid=ra.roleid AND ra.userid= ? AND rc.permission = ?";
 649         $dbusercaps = $DB->get_records_sql($sql, array($userid, CAP_ALLOW));
 650         $usercaps = array();
 651         foreach ($dbusercaps as $usercap) {
 652             $usercaps[$usercap->capability] = true;
 653         }
 654         return $usercaps;
 655     }
 656
 657     /**
 658      * Get missing user capabilities for the given service's functions.
 659      *
 660      * Every external function can declare some required capabilities to allow for easier setup of the web services.
 661      * However, that is supposed to be used for informational admin report only. There is no automatic evaluation of
 662      * the declared capabilities and the context of the capability evaluation is ignored. Also, actual capability
 663      * evaluation is much more complex as it allows for overrides etc.
 664      *
 665      * Returned are capabilities that the given users do not seem to have assigned anywhere at the site and that should
 666      * be checked by the admin.
 667      *
 668      * Do not use this method for anything else, particularly not for any security related checks. See MDL-29962 for the
 669      * background of why we have this - there are arguments for dropping this feature completely.
 670      *
 671      * @param array $users List of users to check, consisting of objects, arrays or integer ids.
 672      * @param int $serviceid The id of the external service to check.
 673      * @return array List of missing capabilities: (int)userid => array of (string)capabilitynames
 674      */
 675     public function get_missing_capabilities_by_users(array $users, int $serviceid): array {
 676         global $DB;
 677
 678         // The following are default capabilities for all authenticated users and we will assume them granted.
 679         $commoncaps = get_default_capabilities('user');
 680
 681         // Get the list of additional capabilities required by the service.
 682         $servicecaps = [];
 683         foreach ($this->get_service_required_capabilities($serviceid) as $service => $caps) {
 684             foreach ($caps as $cap) {
 685                 if (empty($commoncaps[$cap])) {
 686                     $servicecaps[$cap] = true;
 687                 }
 688             }
 689         }
 690
 691         // Bail out early if there's nothing to process.
 692         if (empty($users) || empty($servicecaps)) {
 693             return [];
 694         }
 695
 696         // Prepare a list of user ids we want to check.
 697         $userids = [];
 698         foreach ($users as $user) {
 699             if (is_object($user) && isset($user->id)) {
 700                 $userids[$user->id] = true;
 701             } else if (is_array($user) && isset($user['id'])) {
 702                 $userids[$user['id']] = true;
 703             } else {
 704                 throw new coding_exception('Unexpected format of users list in webservice::get_missing_capabilities_by_users().');
 705             }
 706         }
 707
 708         // Prepare a matrix of missing capabilities x users - consider them all missing by default.
 709         foreach (array_keys($userids) as $userid) {
 710             foreach (array_keys($servicecaps) as $capname) {
 711                 $matrix[$userid][$capname] = true;
 712             }
 713         }
 714
 715         list($capsql, $capparams) = $DB->get_in_or_equal(array_keys($servicecaps), SQL_PARAMS_NAMED, 'paramcap');
 716         list($usersql, $userparams) = $DB->get_in_or_equal(array_keys($userids), SQL_PARAMS_NAMED, 'paramuser');
 717
 718         $sql = "SELECT c.name AS capability, u.id AS userid
 719                   FROM {capabilities} c
 720                   JOIN {role_capabilities} rc ON c.name = rc.capability
 721                   JOIN {role_assignments} ra ON ra.roleid = rc.roleid
 722                   JOIN {user} u ON ra.userid = u.id
 723                  WHERE rc.permission = :capallow
 724                    AND c.name {$capsql}
 725                    AND u.id {$usersql}";
 726
 727         $params = $capparams + $userparams + [
 728             'capallow' => CAP_ALLOW,
 729         ];
 730
 731         $rs = $DB->get_recordset_sql($sql, $params);
 732
 733         foreach ($rs as $record) {
 734             // If there was a potential role assignment found that might grant the user the given capability,
 735             // remove it from the matrix. Again, we ignore all the contexts, prohibits, prevents and other details
 736             // of the permissions evaluations. See the function docblock for details.
 737             unset($matrix[$record->userid][$record->capability]);
 738         }
 739
 740         $rs->close();
 741
 742         foreach ($matrix as $userid => $caps) {
 743             $matrix[$userid] = array_keys($caps);
 744             if (empty($matrix[$userid])) {
 745                 unset($matrix[$userid]);
 746             }
 747         }
 748
 749         return $matrix;
 750     }
 751
 752     /**
 753      * Get an external service for a given service id
 754      *
 755      * @param int $serviceid service id
 756      * @param int $strictness IGNORE_MISSING, MUST_EXIST...
 757      * @return stdClass external service
 758      */
 759     public function get_external_service_by_id($serviceid, $strictness=IGNORE_MISSING) {
 760         global $DB;
 761         $service = $DB->get_record('external_services',
 762                         array('id' => $serviceid), '*', $strictness);
 763         return $service;
 764     }
 765
 766     /**
 767      * Get an external service for a given shortname
 768      *
 769      * @param string $shortname service shortname
 770      * @param int $strictness IGNORE_MISSING, MUST_EXIST...
 771      * @return stdClass external service
 772      */
 773     public function get_external_service_by_shortname($shortname, $strictness=IGNORE_MISSING) {
 774         global $DB;
 775         $service = $DB->get_record('external_services',
 776                         array('shortname' => $shortname), '*', $strictness);
 777         return $service;
 778     }
 779
 780     /**
 781      * Get an external function for a given function id
 782      *
 783      * @param int $functionid function id
 784      * @param int $strictness IGNORE_MISSING, MUST_EXIST...
 785      * @return stdClass external function
 786      */
 787     public function get_external_function_by_id($functionid, $strictness=IGNORE_MISSING) {
 788         global $DB;
 789         $function = $DB->get_record('external_functions',
 790                             array('id' => $functionid), '*', $strictness);
 791         return $function;
 792     }
 793
 794     /**
 795      * Add a function to a service
 796      *
 797      * @param string $functionname function name
 798      * @param int $serviceid service id
 799      */
 800     public function add_external_function_to_service($functionname, $serviceid) {
 801         global $DB;
 802         $addedfunction = new stdClass();
 803         $addedfunction->externalserviceid = $serviceid;
 804         $addedfunction->functionname = $functionname;
 805         $DB->insert_record('external_services_functions', $addedfunction);
 806     }
 807
 808     /**
 809      * Add a service
 810      * It generates the timecreated field automatically.
 811      *
 812      * @param stdClass $service
 813      * @return serviceid integer
 814      */
 815     public function add_external_service($service) {
 816         global $DB;
 817         $service->timecreated = time();
 818         $serviceid = $DB->insert_record('external_services', $service);
 819         return $serviceid;
 820     }
 821
 822     /**
 823      * Update a service
 824      * It modifies the timemodified automatically.
 825      *
 826      * @param stdClass $service
 827      */
 828     public function update_external_service($service) {
 829         global $DB;
 830         $service->timemodified = time();
 831         $DB->update_record('external_services', $service);
 832     }
 833
 834     /**
 835      * Test whether an external function is already linked to a service
 836      *
 837      * @param string $functionname function name
 838      * @param int $serviceid service id
 839      * @return bool true if a matching function exists for the service, else false.
 840      * @throws dml_exception if error
 841      */
 842     public function service_function_exists($functionname, $serviceid) {
 843         global $DB;
 844         return $DB->record_exists('external_services_functions',
 845                             array('externalserviceid' => $serviceid,
 846                                 'functionname' => $functionname));
 847     }
 848
 849     /**
 850      * Remove a function from a service
 851      *
 852      * @param string $functionname function name
 853      * @param int $serviceid service id
 854      */
 855     public function remove_external_function_from_service($functionname, $serviceid) {
 856         global $DB;
 857         $DB->delete_records('external_services_functions',
 858                     array('externalserviceid' => $serviceid, 'functionname' => $functionname));
 859
 860     }
 861
 862     /**
 863      * Return a list with all the valid user tokens for the given user, it only excludes expired tokens.
 864      *
 865      * @param  string $userid user id to retrieve tokens from
 866      * @return array array of token entries
 867      * @since Moodle 3.2
 868      */
 869     public static function get_active_tokens($userid) {
 870         global $DB;
 871
 872         $sql = 'SELECT t.*, s.name as servicename FROM {external_tokens} t JOIN
 873                 {external_services} s ON t.externalserviceid = s.id WHERE
 874                 t.userid = :userid AND (COALESCE(t.validuntil, 0) = 0 OR t.validuntil > :now)';
 875         $params = array('userid' => $userid, 'now' => time());
 876         return $DB->get_records_sql($sql, $params);
 877     }
 878 }
 879
 880 /**
 881  * Exception indicating access control problem in web service call
 882  * This exception should return general errors about web service setup.
 883  * Errors related to the user like wrong username/password should not use it,
 884  * you should not use this exception if you want to let the client implement
 885  * some code logic against an access error.
 886  *
 887  * @package    core_webservice
 888  * @copyright  2009 Petr Skodak
 889  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 890  */
 891 class webservice_access_exception extends moodle_exception {
 892
 893     /**
 894      * Constructor
 895      *
 896      * @param string $debuginfo the debug info
 897      */
 898     function __construct($debuginfo) {
 899         parent::__construct('accessexception', 'webservice', '', null, $debuginfo);
 900     }
 901 }
 902
 903 /**
 904  * Check if a protocol is enabled
 905  *
 906  * @param string $protocol name of WS protocol ('rest', 'soap', ...)
 907  * @return bool true if the protocol is enabled
 908  */
 909 function webservice_protocol_is_enabled($protocol) {
 910     global $CFG;
 911
 912     if (empty($CFG->enablewebservices) || empty($CFG->webserviceprotocols)) {
 913         return false;
 914     }
 915
 916     $active = explode(',', $CFG->webserviceprotocols);
 917
 918     return(in_array($protocol, $active));
 919 }
 920
 921 /**
 922  * Mandatory interface for all test client classes.
 923  *
 924  * @package    core_webservice
 925  * @copyright  2009 Petr Skodak
 926  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 927  */
 928 interface webservice_test_client_interface {
 929
 930     /**
 931      * Execute test client WS request
 932      *
 933      * @param string $serverurl server url (including the token param)
 934      * @param string $function web service function name
 935      * @param array $params parameters of the web service function
 936      * @return mixed
 937      */
 938     public function simpletest($serverurl, $function, $params);
 939 }
 940
 941 /**
 942  * Mandatory interface for all web service protocol classes
 943  *
 944  * @package    core_webservice
 945  * @copyright  2009 Petr Skodak
 946  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 947  */
 948 interface webservice_server_interface {
 949
 950     /**
 951      * Process request from client.
 952      */
 953     public function run();
 954 }
 955
 956 /**
 957  * Abstract web service base class.
 958  *
 959  * @package    core_webservice
 960  * @copyright  2009 Petr Skodak
 961  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 962  */
 963 abstract class webservice_server implements webservice_server_interface {
 964
 965     /** @var string Name of the web server plugin */
 966     protected $wsname = null;
 967
 968     /** @var string Name of local user */
 969     protected $username = null;
 970
 971     /** @var string Password of the local user */
 972     protected $password = null;
 973
 974     /** @var int The local user */
 975     protected $userid = null;
 976
 977     /** @var integer Authentication method one of WEBSERVICE_AUTHMETHOD_* */
 978     protected $authmethod;
 979
 980     /** @var string Authentication token*/
 981     protected $token = null;
 982
 983     /** @var stdClass Restricted context */
 984     protected $restricted_context;
 985
 986     /** @var int Restrict call to one service id*/
 987     protected $restricted_serviceid = null;
 988
 989     /**
 990      * Constructor
 991      *
 992      * @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_*
 993      */
 994     public function __construct($authmethod) {
 995         $this->authmethod = $authmethod;
 996     }
 997
 998
 999     /**
1000      * Authenticate user using username+password or token.
1001      * This function sets up $USER global.
1002      * It is safe to use has_capability() after this.
1003      * This method also verifies user is allowed to use this
1004      * server.
1005      */
1006     protected function authenticate_user() {
1007         global $CFG, $DB;
1008
1009         if (!NO_MOODLE_COOKIES) {
1010             throw new coding_exception('Cookies must be disabled in WS servers!');
1011         }
1012
1013         $loginfaileddefaultparams = array(
1014             'other' => array(
1015                 'method' => $this->authmethod,
1016                 'reason' => null
1017             )
1018         );
1019
1020         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1021
1022             //we check that authentication plugin is enabled
1023             //it is only required by simple authentication
1024             if (!is_enabled_auth('webservice')) {
1025                 throw new webservice_access_exception('The web service authentication plugin is disabled.');
1026             }
1027
1028             if (!$auth = get_auth_plugin('webservice')) {
1029                 throw new webservice_access_exception('The web service authentication plugin is missing.');
1030             }
1031
1032             $this->restricted_context = context_system::instance();
1033
1034             if (!$this->username) {
1035                 throw new moodle_exception('missingusername', 'webservice');
1036             }
1037
1038             if (!$this->password) {
1039                 throw new moodle_exception('missingpassword', 'webservice');
1040             }
1041
1042             if (!$auth->user_login_webservice($this->username, $this->password)) {
1043
1044                 // Log failed login attempts.
1045                 $params = $loginfaileddefaultparams;
1046                 $params['other']['reason'] = 'password';
1047                 $params['other']['username'] = $this->username;
1048                 $event = \core\event\webservice_login_failed::create($params);
1049                 $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('simpleauthlog', 'webservice'), '' ,
1050                     get_string('failedtolog', 'webservice').": ".$this->username."/".$this->password." - ".getremoteaddr() , 0));
1051                 $event->trigger();
1052
1053                 throw new moodle_exception('wrongusernamepassword', 'webservice');
1054             }
1055
1056             $user = $DB->get_record('user', array('username'=>$this->username, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
1057
1058         } else if ($this->authmethod == WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN){
1059             $user = $this->authenticate_by_token(EXTERNAL_TOKEN_PERMANENT);
1060         } else {
1061             $user = $this->authenticate_by_token(EXTERNAL_TOKEN_EMBEDDED);
1062         }
1063
1064         // Cannot authenticate unless maintenance access is granted.
1065         $hasmaintenanceaccess = has_capability('moodle/site:maintenanceaccess', context_system::instance(), $user);
1066         if (!empty($CFG->maintenance_enabled) and !$hasmaintenanceaccess) {
1067             throw new moodle_exception('sitemaintenance', 'admin');
1068         }
1069
1070         //only confirmed user should be able to call web service
1071         if (!empty($user->deleted)) {
1072             $params = $loginfaileddefaultparams;
1073             $params['other']['reason'] = 'user_deleted';
1074             $params['other']['username'] = $user->username;
1075             $event = \core\event\webservice_login_failed::create($params);
1076             $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessuserdeleted', 'webservice',
1077                 $user->username) . " - ".getremoteaddr(), 0, $user->id));
1078             $event->trigger();
1079             throw new moodle_exception('wsaccessuserdeleted', 'webservice', '', $user->username);
1080         }
1081
1082         //only confirmed user should be able to call web service
1083         if (empty($user->confirmed)) {
1084             $params = $loginfaileddefaultparams;
1085             $params['other']['reason'] = 'user_unconfirmed';
1086             $params['other']['username'] = $user->username;
1087             $event = \core\event\webservice_login_failed::create($params);
1088             $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessuserunconfirmed', 'webservice',
1089                 $user->username) . " - ".getremoteaddr(), 0, $user->id));
1090             $event->trigger();
1091             throw new moodle_exception('wsaccessuserunconfirmed', 'webservice', '', $user->username);
1092         }
1093
1094         //check the user is suspended
1095         if (!empty($user->suspended)) {
1096             $params = $loginfaileddefaultparams;
1097             $params['other']['reason'] = 'user_unconfirmed';
1098             $params['other']['username'] = $user->username;
1099             $event = \core\event\webservice_login_failed::create($params);
1100             $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessusersuspended', 'webservice',
1101                 $user->username) . " - ".getremoteaddr(), 0, $user->id));
1102             $event->trigger();
1103             throw new moodle_exception('wsaccessusersuspended', 'webservice', '', $user->username);
1104         }
1105
1106         //retrieve the authentication plugin if no previously done
1107         if (empty($auth)) {
1108           $auth  = get_auth_plugin($user->auth);
1109         }
1110
1111         // check if credentials have expired
1112         if (!empty($auth->config->expiration) and $auth->config->expiration == 1) {
1113             $days2expire = $auth->password_expire($user->username);
1114             if (intval($days2expire) < 0 ) {
1115                 $params = $loginfaileddefaultparams;
1116                 $params['other']['reason'] = 'password_expired';
1117                 $params['other']['username'] = $user->username;
1118                 $event = \core\event\webservice_login_failed::create($params);
1119                 $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessuserexpired', 'webservice',
1120                     $user->username) . " - ".getremoteaddr(), 0, $user->id));
1121                 $event->trigger();
1122                 throw new moodle_exception('wsaccessuserexpired', 'webservice', '', $user->username);
1123             }
1124         }
1125
1126         //check if the auth method is nologin (in this case refuse connection)
1127         if ($user->auth=='nologin') {
1128             $params = $loginfaileddefaultparams;
1129             $params['other']['reason'] = 'login';
1130             $params['other']['username'] = $user->username;
1131             $event = \core\event\webservice_login_failed::create($params);
1132             $event->set_legacy_logdata(array(SITEID, '', '', '', get_string('wsaccessusernologin', 'webservice',
1133                 $user->username) . " - ".getremoteaddr(), 0, $user->id));
1134             $event->trigger();
1135             throw new moodle_exception('wsaccessusernologin', 'webservice', '', $user->username);
1136         }
1137
1138         // now fake user login, the session is completely empty too
1139         enrol_check_plugins($user, false);
1140         \core\session\manager::set_user($user);
1141         set_login_session_preferences();
1142         $this->userid = $user->id;
1143
1144         if ($this->authmethod != WEBSERVICE_AUTHMETHOD_SESSION_TOKEN && !has_capability("webservice/$this->wsname:use", $this->restricted_context)) {
1145             throw new webservice_access_exception("You are not allowed to use the {$this->wsname} protocol " .
1146                 "(missing capability: webservice/{$this->wsname}:use)");
1147         }
1148
1149         external_api::set_context_restriction($this->restricted_context);
1150     }
1151
1152     /**
1153      * User authentication by token
1154      *
1155      * @param string $tokentype token type (EXTERNAL_TOKEN_EMBEDDED or EXTERNAL_TOKEN_PERMANENT)
1156      * @return stdClass the authenticated user
1157      * @throws webservice_access_exception
1158      */
1159     protected function authenticate_by_token($tokentype){
1160         global $DB;
1161
1162         $loginfaileddefaultparams = array(
1163             'other' => array(
1164                 'method' => $this->authmethod,
1165                 'reason' => null
1166             )
1167         );
1168
1169         if (!$token = $DB->get_record('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype))) {
1170             // Log failed login attempts.
1171             $params = $loginfaileddefaultparams;
1172             $params['other']['reason'] = 'invalid_token';
1173             $event = \core\event\webservice_login_failed::create($params);
1174             $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '' ,
1175                 get_string('failedtolog', 'webservice').": ".$this->token. " - ".getremoteaddr() , 0));
1176             $event->trigger();
1177             throw new moodle_exception('invalidtoken', 'webservice');
1178         }
1179
1180         if ($token->validuntil and $token->validuntil < time()) {
1181             $DB->delete_records('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype));
1182             throw new webservice_access_exception('Invalid token - token expired - check validuntil time for the token');
1183         }
1184
1185         if ($token->sid){//assumes that if sid is set then there must be a valid associated session no matter the token type
1186             if (!\core\session\manager::session_exists($token->sid)){
1187                 $DB->delete_records('external_tokens', array('sid'=>$token->sid));
1188                 throw new webservice_access_exception('Invalid session based token - session not found or expired');
1189             }
1190         }
1191
1192         if ($token->iprestriction and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {
1193             $params = $loginfaileddefaultparams;
1194             $params['other']['reason'] = 'ip_restricted';
1195             $params['other']['tokenid'] = $token->id;
1196             $event = \core\event\webservice_login_failed::create($params);
1197             $event->add_record_snapshot('external_tokens', $token);
1198             $event->set_legacy_logdata(array(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '' ,
1199                 get_string('failedtolog', 'webservice').": ".getremoteaddr() , 0));
1200             $event->trigger();
1201             throw new webservice_access_exception('Invalid service - IP:' . getremoteaddr()
1202                     . ' is not supported - check this allowed user');
1203         }
1204
1205         $this->restricted_context = context::instance_by_id($token->contextid);
1206         $this->restricted_serviceid = $token->externalserviceid;
1207
1208         $user = $DB->get_record('user', array('id'=>$token->userid), '*', MUST_EXIST);
1209
1210         // log token access
1211         webservice::update_token_lastaccess($token);
1212
1213         return $user;
1214
1215     }
1216
1217     /**
1218      * Intercept some moodlewssettingXXX $_GET and $_POST parameter
1219      * that are related to the web service call and are not the function parameters
1220      */
1221     protected function set_web_service_call_settings() {
1222         global $CFG;
1223
1224         // Default web service settings.
1225         // Must be the same XXX key name as the external_settings::set_XXX function.
1226         // Must be the same XXX ws parameter name as 'moodlewssettingXXX'.
1227         $externalsettings = array(
1228             'raw' => array('default' => false, 'type' => PARAM_BOOL),
1229             'fileurl' => array('default' => true, 'type' => PARAM_BOOL),
1230             'filter' => array('default' => false, 'type' => PARAM_BOOL),
1231             'lang' => array('default' => '', 'type' => PARAM_LANG),
1232             'timezone' => array('default' => '', 'type' => PARAM_TIMEZONE),
1233         );
1234
1235         // Load the external settings with the web service settings.
1236         $settings = external_settings::get_instance();
1237         foreach ($externalsettings as $name => $settingdata) {
1238
1239             $wsparamname = 'moodlewssetting' . $name;
1240
1241             // Retrieve and remove the setting parameter from the request.
1242             $value = optional_param($wsparamname, $settingdata['default'], $settingdata['type']);
1243             unset($_GET[$wsparamname]);
1244             unset($_POST[$wsparamname]);
1245
1246             $functioname = 'set_' . $name;
1247             $settings->$functioname($value);
1248         }
1249
1250     }
1251 }
1252
1253 /**
1254  * Web Service server base class.
1255  *
1256  * This class handles both simple and token authentication.
1257  *
1258  * @package    core_webservice
1259  * @copyright  2009 Petr Skodak
1260  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1261  */
1262 abstract class webservice_base_server extends webservice_server {
1263
1264     /** @var array The function parameters - the real values submitted in the request */
1265     protected $parameters = null;
1266
1267     /** @var string The name of the function that is executed */
1268     protected $functionname = null;
1269
1270     /** @var stdClass Full function description */
1271     protected $function = null;
1272
1273     /** @var mixed Function return value */
1274     protected $returns = null;
1275
1276     /** @var array List of methods and their information provided by the web service. */
1277     protected $servicemethods;
1278
1279     /** @var  array List of struct classes generated for the web service methods. */
1280     protected $servicestructs;
1281
1282     /**
1283      * This method parses the request input, it needs to get:
1284      *  1/ user authentication - username+password or token
1285      *  2/ function name
1286      *  3/ function parameters
1287      */
1288     abstract protected function parse_request();
1289
1290     /**
1291      * Send the result of function call to the WS client.
1292      */
1293     abstract protected function send_response();
1294
1295     /**
1296      * Send the error information to the WS client.
1297      *
1298      * @param exception $ex
1299      */
1300     abstract protected function send_error($ex=null);
1301
1302     /**
1303      * Process request from client.
1304      *
1305      * @uses die
1306      */
1307     public function run() {
1308         global $CFG, $USER, $SESSION;
1309
1310         // we will probably need a lot of memory in some functions
1311         raise_memory_limit(MEMORY_EXTRA);
1312
1313         // set some longer timeout, this script is not sending any output,
1314         // this means we need to manually extend the timeout operations
1315         // that need longer time to finish
1316         external_api::set_timeout();
1317
1318         // set up exception handler first, we want to sent them back in correct format that
1319         // the other system understands
1320         // we do not need to call the original default handler because this ws handler does everything
1321         set_exception_handler(array($this, 'exception_handler'));
1322
1323         // init all properties from the request data
1324         $this->parse_request();
1325
1326         // authenticate user, this has to be done after the request parsing
1327         // this also sets up $USER and $SESSION
1328         $this->authenticate_user();
1329
1330         // find all needed function info and make sure user may actually execute the function
1331         $this->load_function_info();
1332
1333         // Log the web service request.
1334         $params = array(
1335             'other' => array(
1336                 'function' => $this->functionname
1337             )
1338         );
1339         $event = \core\event\webservice_function_called::create($params);
1340         $event->set_legacy_logdata(array(SITEID, 'webservice', $this->functionname, '' , getremoteaddr() , 0, $this->userid));
1341         $event->trigger();
1342
1343         // Do additional setup stuff.
1344         $settings = external_settings::get_instance();
1345         $sessionlang = $settings->get_lang();
1346         if (!empty($sessionlang)) {
1347             $SESSION->lang = $sessionlang;
1348         }
1349
1350         setup_lang_from_browser();
1351
1352         if (empty($CFG->lang)) {
1353             if (empty($SESSION->lang)) {
1354                 $CFG->lang = 'en';
1355             } else {
1356                 $CFG->lang = $SESSION->lang;
1357             }
1358         }
1359
1360         // Change timezone only in sites where it isn't forced.
1361         $newtimezone = $settings->get_timezone();
1362         if (!empty($newtimezone) && (!isset($CFG->forcetimezone) || $CFG->forcetimezone == 99)) {
1363             $USER->timezone = $newtimezone;
1364         }
1365
1366         // finally, execute the function - any errors are catched by the default exception handler
1367         $this->execute();
1368
1369         // send the results back in correct format
1370         $this->send_response();
1371
1372         // session cleanup
1373         $this->session_cleanup();
1374
1375         die;
1376     }
1377
1378     /**
1379      * Specialised exception handler, we can not use the standard one because
1380      * it can not just print html to output.
1381      *
1382      * @param exception $ex
1383      * $uses exit
1384      */
1385     public function exception_handler($ex) {
1386         // detect active db transactions, rollback and log as error
1387         abort_all_db_transactions();
1388
1389         // some hacks might need a cleanup hook
1390         $this->session_cleanup($ex);
1391
1392         // now let the plugin send the exception to client
1393         $this->send_error($ex);
1394
1395         // not much else we can do now, add some logging later
1396         exit(1);
1397     }
1398
1399     /**
1400      * Future hook needed for emulated sessions.
1401      *
1402      * @param exception $exception null means normal termination, $exception received when WS call failed
1403      */
1404     protected function session_cleanup($exception=null) {
1405         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1406             // nothing needs to be done, there is no persistent session
1407         } else {
1408             // close emulated session if used
1409         }
1410     }
1411
1412     /**
1413      * Fetches the function description from database,
1414      * verifies user is allowed to use this function and
1415      * loads all paremeters and return descriptions.
1416      */
1417     protected function load_function_info() {
1418         global $DB, $USER, $CFG;
1419
1420         if (empty($this->functionname)) {
1421             throw new invalid_parameter_exception('Missing function name');
1422         }
1423
1424         // function must exist
1425         $function = external_api::external_function_info($this->functionname);
1426
1427         if ($this->restricted_serviceid) {
1428             $params = array('sid1'=>$this->restricted_serviceid, 'sid2'=>$this->restricted_serviceid);
1429             $wscond1 = 'AND s.id = :sid1';
1430             $wscond2 = 'AND s.id = :sid2';
1431         } else {
1432             $params = array();
1433             $wscond1 = '';
1434             $wscond2 = '';
1435         }
1436
1437         // now let's verify access control
1438
1439         // now make sure the function is listed in at least one service user is allowed to use
1440         // allow access only if:
1441         //  1/ entry in the external_services_users table if required
1442         //  2/ validuntil not reached
1443         //  3/ has capability if specified in service desc
1444         //  4/ iprestriction
1445
1446         $sql = "SELECT s.*, NULL AS iprestriction
1447                   FROM {external_services} s
1448                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0 AND sf.functionname = :name1)
1449                  WHERE s.enabled = 1 $wscond1
1450
1451                  UNION
1452
1453                 SELECT s.*, su.iprestriction
1454                   FROM {external_services} s
1455                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1 AND sf.functionname = :name2)
1456                   JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
1457                  WHERE s.enabled = 1 AND (su.validuntil IS NULL OR su.validuntil < :now) $wscond2";
1458         $params = array_merge($params, array('userid'=>$USER->id, 'name1'=>$function->name, 'name2'=>$function->name, 'now'=>time()));
1459
1460         $rs = $DB->get_recordset_sql($sql, $params);
1461         // now make sure user may access at least one service
1462         $remoteaddr = getremoteaddr();
1463         $allowed = false;
1464         foreach ($rs as $service) {
1465             if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
1466                 continue; // cap required, sorry
1467             }
1468             if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
1469                 continue; // wrong request source ip, sorry
1470             }
1471             $allowed = true;
1472             break; // one service is enough, no need to continue
1473         }
1474         $rs->close();
1475         if (!$allowed) {
1476             throw new webservice_access_exception(
1477                     'Access to the function '.$this->functionname.'() is not allowed.
1478                      There could be multiple reasons for this:
1479                      1. The service linked to the user token does not contain the function.
1480                      2. The service is user-restricted and the user is not listed.
1481                      3. The service is IP-restricted and the user IP is not listed.
1482                      4. The service is time-restricted and the time has expired.
1483                      5. The token is time-restricted and the time has expired.
1484                      6. The service requires a specific capability which the user does not have.
1485                      7. The function is called with username/password (no user token is sent)
1486                      and none of the services has the function to allow the user.
1487                      These settings can be found in Administration > Site administration
1488                      > Server > Web services > External services and Manage tokens.');
1489         }
1490
1491         // we have all we need now
1492         $this->function = $function;
1493     }
1494
1495     /**
1496      * Execute previously loaded function using parameters parsed from the request data.
1497      */
1498     protected function execute() {
1499         // validate params, this also sorts the params properly, we need the correct order in the next part
1500         $params = call_user_func(array($this->function->classname, 'validate_parameters'), $this->function->parameters_desc, $this->parameters);
1501         $params = array_values($params);
1502
1503         // Allow any Moodle plugin a chance to override this call. This is a convenient spot to
1504         // make arbitrary behaviour customisations, for example to affect the mobile app behaviour.
1505         // The overriding plugin could call the 'real' function first and then modify the results,
1506         // or it could do a completely separate thing.
1507         $callbacks = get_plugins_with_function('override_webservice_execution');
1508         foreach ($callbacks as $plugintype => $plugins) {
1509             foreach ($plugins as $plugin => $callback) {
1510                 $result = $callback($this->function, $params);
1511                 if ($result !== false) {
1512                     // If the callback returns anything other than false, we assume it replaces the
1513                     // real function.
1514                     $this->returns = $result;
1515                     return;
1516                 }
1517             }
1518         }
1519
1520         // execute - yay!
1521         $this->returns = call_user_func_array(array($this->function->classname, $this->function->methodname), $params);
1522     }
1523
1524     /**
1525      * Load the virtual class needed for the web service.
1526      *
1527      * Initialises the virtual class that contains the web service functions that the user is allowed to use.
1528      * The web service function will be available if the user:
1529      * - is validly registered in the external_services_users table.
1530      * - has the required capability.
1531      * - meets the IP restriction requirement.
1532      * This virtual class can be used by web service protocols such as SOAP, especially when generating WSDL.
1533      */
1534     protected function init_service_class() {
1535         global $USER, $DB;
1536
1537         // Initialise service methods and struct classes.
1538         $this->servicemethods = array();
1539         $this->servicestructs = array();
1540
1541         $params = array();
1542         $wscond1 = '';
1543         $wscond2 = '';
1544         if ($this->restricted_serviceid) {
1545             $params = array('sid1' => $this->restricted_serviceid, 'sid2' => $this->restricted_serviceid);
1546             $wscond1 = 'AND s.id = :sid1';
1547             $wscond2 = 'AND s.id = :sid2';
1548         }
1549
1550         $sql = "SELECT s.*, NULL AS iprestriction
1551                   FROM {external_services} s
1552                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0)
1553                  WHERE s.enabled = 1 $wscond1
1554
1555                  UNION
1556
1557                 SELECT s.*, su.iprestriction
1558                   FROM {external_services} s
1559                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1)
1560                   JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
1561                  WHERE s.enabled = 1 AND (su.validuntil IS NULL OR su.validuntil < :now) $wscond2";
1562         $params = array_merge($params, array('userid' => $USER->id, 'now' => time()));
1563
1564         $serviceids = array();
1565         $remoteaddr = getremoteaddr();
1566
1567         // Query list of external services for the user.
1568         $rs = $DB->get_recordset_sql($sql, $params);
1569
1570         // Check which service ID to include.
1571         foreach ($rs as $service) {
1572             if (isset($serviceids[$service->id])) {
1573                 continue; // Service already added.
1574             }
1575             if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
1576                 continue; // Cap required, sorry.
1577             }
1578             if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
1579                 continue; // Wrong request source ip, sorry.
1580             }
1581             $serviceids[$service->id] = $service->id;
1582         }
1583         $rs->close();
1584
1585         // Generate the virtual class name.
1586         $classname = 'webservices_virtual_class_000000';
1587         while (class_exists($classname)) {
1588             $classname++;
1589         }
1590         $this->serviceclass = $classname;
1591
1592         // Get the list of all available external functions.
1593         $wsmanager = new webservice();
1594         $functions = $wsmanager->get_external_functions($serviceids);
1595
1596         // Generate code for the virtual methods for this web service.
1597         $methods = '';
1598         foreach ($functions as $function) {
1599             $methods .= $this->get_virtual_method_code($function);
1600         }
1601
1602         $code = <<<EOD
1603 /**
1604  * Virtual class web services for user id $USER->id in context {$this->restricted_context->id}.
1605  */
1606 class $classname {
1607 $methods
1608 }
1609 EOD;
1610         // Load the virtual class definition into memory.
1611         eval($code);
1612     }
1613
1614     /**
1615      * Generates a struct class.
1616      *
1617      * @param external_single_structure $structdesc The basis of the struct class to be generated.
1618      * @return string The class name of the generated struct class.
1619      */
1620     protected function generate_simple_struct_class(external_single_structure $structdesc) {
1621         global $USER;
1622
1623         $propeties = array();
1624         $fields = array();
1625         foreach ($structdesc->keys as $name => $fieldsdesc) {
1626             $type = $this->get_phpdoc_type($fieldsdesc);
1627             $propertytype = array('type' => $type);
1628             if (empty($fieldsdesc->allownull) || $fieldsdesc->allownull == NULL_ALLOWED) {
1629                 $propertytype['nillable'] = true;
1630             }
1631             $propeties[$name] = $propertytype;
1632             $fields[] = '    /** @var ' . $type . ' $' . $name . '*/';
1633             $fields[] = '    public $' . $name .';';
1634         }
1635         $fieldsstr = implode("\n", $fields);
1636
1637         // We do this after the call to get_phpdoc_type() to avoid duplicate class creation.
1638         $classname = 'webservices_struct_class_000000';
1639         while (class_exists($classname)) {
1640             $classname++;
1641         }
1642         $code = <<<EOD
1643 /**
1644  * Virtual struct class for web services for user id $USER->id in context {$this->restricted_context->id}.
1645  */
1646 class $classname {
1647 $fieldsstr
1648 }
1649 EOD;
1650         // Load into memory.
1651         eval($code);
1652
1653         // Prepare struct info.
1654         $structinfo = new stdClass();
1655         $structinfo->classname = $classname;
1656         $structinfo->properties = $propeties;
1657         // Add the struct info the the list of service struct classes.
1658         $this->servicestructs[] = $structinfo;
1659
1660         return $classname;
1661     }
1662
1663     /**
1664      * Returns a virtual method code for a web service function.
1665      *
1666      * @param stdClass $function a record from external_function
1667      * @return string The PHP code of the virtual method.
1668      * @throws coding_exception
1669      * @throws moodle_exception
1670      */
1671     protected function get_virtual_method_code($function) {
1672         $function = external_api::external_function_info($function);
1673
1674         // Parameters and their defaults for the method signature.
1675         $paramanddefaults = array();
1676         // Parameters for external lib call.
1677         $params = array();
1678         $paramdesc = array();
1679         // The method's input parameters and their respective types.
1680         $inputparams = array();
1681         // The method's output parameters and their respective types.
1682         $outputparams = array();
1683
1684         foreach ($function->parameters_desc->keys as $name => $keydesc) {
1685             $param = '$' . $name;
1686             $paramanddefault = $param;
1687             if ($keydesc->required == VALUE_OPTIONAL) {
1688                 // It does not make sense to declare a parameter VALUE_OPTIONAL. VALUE_OPTIONAL is used only for array/object key.
1689                 throw new moodle_exception('erroroptionalparamarray', 'webservice', '', $name);
1690             } else if ($keydesc->required == VALUE_DEFAULT) {
1691                 // Need to generate the default, if there is any.
1692                 if ($keydesc instanceof external_value) {
1693                     if ($keydesc->default === null) {
1694                         $paramanddefault .= ' = null';
1695                     } else {
1696                         switch ($keydesc->type) {
1697                             case PARAM_BOOL:
1698                                 $default = (int)$keydesc->default;
1699                                 break;
1700                             case PARAM_INT:
1701                                 $default = $keydesc->default;
1702                                 break;
1703                             case PARAM_FLOAT;
1704                                 $default = $keydesc->default;
1705                                 break;
1706                             default:
1707                                 $default = "'$keydesc->default'";
1708                         }
1709                         $paramanddefault .= " = $default";
1710                     }
1711                 } else {
1712                     // Accept empty array as default.
1713                     if (isset($keydesc->default) && is_array($keydesc->default) && empty($keydesc->default)) {
1714                         $paramanddefault .= ' = array()';
1715                     } else {
1716                         // For the moment we do not support default for other structure types.
1717                         throw new moodle_exception('errornotemptydefaultparamarray', 'webservice', '', $name);
1718                     }
1719                 }
1720             }
1721
1722             $params[] = $param;
1723             $paramanddefaults[] = $paramanddefault;
1724             $type = $this->get_phpdoc_type($keydesc);
1725             $inputparams[$name]['type'] = $type;
1726
1727             $paramdesc[] = '* @param ' . $type . ' $' . $name . ' ' . $keydesc->desc;
1728         }
1729         $paramanddefaults = implode(', ', $paramanddefaults);
1730         $paramdescstr = implode("\n ", $paramdesc);
1731
1732         $serviceclassmethodbody = $this->service_class_method_body($function, $params);
1733
1734         if (empty($function->returns_desc)) {
1735             $return = '* @return void';
1736         } else {
1737             $type = $this->get_phpdoc_type($function->returns_desc);
1738             $outputparams['return']['type'] = $type;
1739             $return = '* @return ' . $type . ' ' . $function->returns_desc->desc;
1740         }
1741
1742         // Now create the virtual method that calls the ext implementation.
1743         $code = <<<EOD
1744 /**
1745  * $function->description.
1746  *
1747  $paramdescstr
1748  $return
1749  */
1750 public function $function->name($paramanddefaults) {
1751 $serviceclassmethodbody
1752 }
1753 EOD;
1754
1755         // Prepare the method information.
1756         $methodinfo = new stdClass();
1757         $methodinfo->name = $function->name;
1758         $methodinfo->inputparams = $inputparams;
1759         $methodinfo->outputparams = $outputparams;
1760         $methodinfo->description = $function->description;
1761         // Add the method information into the list of service methods.
1762         $this->servicemethods[] = $methodinfo;
1763
1764         return $code;
1765     }
1766
1767     /**
1768      * Get the phpdoc type for an external_description object.
1769      * external_value => int, double or string
1770      * external_single_structure => object|struct, on-fly generated stdClass name.
1771      * external_multiple_structure => array
1772      *
1773      * @param mixed $keydesc The type description.
1774      * @return string The PHP doc type of the external_description object.
1775      */
1776     protected function get_phpdoc_type($keydesc) {
1777         $type = null;
1778         if ($keydesc instanceof external_value) {
1779             switch ($keydesc->type) {
1780                 case PARAM_BOOL: // 0 or 1 only for now.
1781                 case PARAM_INT:
1782                     $type = 'int';
1783                     break;
1784                 case PARAM_FLOAT;
1785                     $type = 'double';
1786                     break;
1787                 default:
1788                     $type = 'string';
1789             }
1790         } else if ($keydesc instanceof external_single_structure) {
1791             $type = $this->generate_simple_struct_class($keydesc);
1792         } else if ($keydesc instanceof external_multiple_structure) {
1793             $type = 'array';
1794         }
1795
1796         return $type;
1797     }
1798
1799     /**
1800      * Generates the method body of the virtual external function.
1801      *
1802      * @param stdClass $function a record from external_function.
1803      * @param array $params web service function parameters.
1804      * @return string body of the method for $function ie. everything within the {} of the method declaration.
1805      */
1806     protected function service_class_method_body($function, $params) {
1807         // Cast the param from object to array (validate_parameters except array only).
1808         $castingcode = '';
1809         $paramsstr = '';
1810         if (!empty($params)) {
1811             foreach ($params as $paramtocast) {
1812                 // Clean the parameter from any white space.
1813                 $paramtocast = trim($paramtocast);
1814                 $castingcode .= "    $paramtocast = json_decode(json_encode($paramtocast), true);\n";
1815             }
1816             $paramsstr = implode(', ', $params);
1817         }
1818
1819         $descriptionmethod = $function->methodname . '_returns()';
1820         $callforreturnvaluedesc = $function->classname . '::' . $descriptionmethod;
1821
1822         $methodbody = <<<EOD
1823 $castingcode
1824     if ($callforreturnvaluedesc == null) {
1825         $function->classname::$function->methodname($paramsstr);
1826         return null;
1827     }
1828     return \\core_external\\external_api::clean_returnvalue($callforreturnvaluedesc, $function->classname::$function->methodname($paramsstr));
1829 EOD;
1830         return $methodbody;
1831     }
1832 }
1833
1834 /**
1835  * Early WS exception handler.
1836  * It handles exceptions during setup and returns the Exception text in the WS format.
1837  * If a raise function is found nothing is returned. Throws Exception otherwise.
1838  *
1839  * @param  Exception $ex Raised exception.
1840  * @throws Exception
1841  */
1842 function early_ws_exception_handler(Exception $ex): void {
1843     if (function_exists('raise_early_ws_exception')) {
1844         raise_early_ws_exception($ex);
1845         die;
1846     }
1847
1848     throw $ex;
1849 }