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