Search moodle.org's
Developer Documentation


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

Search This Site: