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