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