lib.php 79.2 KB
Newer Older
1 2 3 4
<?php
/**
 *
 * @package    mahara
5
 * @subpackage auth-webservice
6
 * @author     Catalyst IT Ltd
7 8
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
 * @copyright  For copyright information on Mahara, please see the README file distributed with this software.
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
 *
 */

defined('INTERNAL') || die();

require_once(get_config('docroot') . 'webservice/locallib.php');
require_once(get_config('docroot') . 'artefact/lib.php');
require_once(get_config('docroot') . 'webservice/libs/net.php');
require_once(get_config('docroot') . 'api/xmlrpc/lib.php');

/**
 * The directory within a component that contains the web service files
 */
define('WEBSERVICE_DIRECTORY', 'webservice');

/**
 * Security token used for allowing access
 * from external application such as web services.
 * Scripts do not use any session, performance is relatively
 * low because we need to load access info in each request.
 * Scripts are executed in parallel.
 */
define('EXTERNAL_TOKEN_PERMANENT', 0);

/**
 * Security token used for allowing access
 * of embedded applications, the code is executed in the
 * active user session. Token is invalidated after user logs out.
 * Scripts are executed serially - normal session locking is used.
 */
define('EXTERNAL_TOKEN_EMBEDDED', 1);

/**
 * OAuth Token type for registered applications oauth v1
 */
define('EXTERNAL_TOKEN_OAUTH1', 2);

/**
47
 * Security token self-generated by a normal user
48 49 50 51
 */
define('EXTERNAL_TOKEN_USER', 3);

/**
52
 * Personal User Tokens expiry time (12 weeks)
53
 */
54
define('EXTERNAL_TOKEN_USER_EXPIRES', (12 * 7 * 24 * 60 * 60));
55 56 57 58 59 60 61 62

define('WEBSERVICE_AUTHMETHOD_USERNAME', 0);
define('WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN', 1);
define('WEBSERVICE_AUTHMETHOD_SESSION_TOKEN', 2);
define('WEBSERVICE_AUTHMETHOD_OAUTH_TOKEN', 3);
define('WEBSERVICE_AUTHMETHOD_USER_TOKEN', 4);

// strictness check
63
define('IGNORE_MISSING', 1);
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
define('MUST_EXIST', 2);

/** Get remote addr constant */
define('GETREMOTEADDR_SKIP_HTTP_CLIENT_IP', '1');

/** Get remote addr constant */
define('GETREMOTEADDR_SKIP_HTTP_X_FORWARDED_FOR', '2');


/**
 * What debugging state is Web Services in
 *
 * @return boolean true on yes
 */
function ws_debugging() {
    // must be set in config.php
    if (get_config('enablewsdebugging')) {
        return true;
    }
    else {
        return false;
    }
}

/**
 * Check that a user is in the institution
 *
 * @param array $user array('id' => .., 'username' => ..)
 * @param string $institution
 * @return boolean true on yes
 */
function mahara_external_in_institution($user, $institution) {
    $institutions = array_keys(load_user_institutions($user->id));
    $auth_instance = get_record('auth_instance', 'id', $user->authinstance);
    $institutions[]= $auth_instance->institution;
    if (!in_array($institution, $institutions)) {
        return false;
    }
    return true;
}

/**
 * parameter definition for output of any Atom generator
 *
 * Returns description of method result value
 * @return external_description
 */
function mahara_external_atom_returns() {
    return new external_single_structure(
    array(
            'id'      => new external_value(PARAM_RAW, 'Atom document Id'),
            'title'   => new external_value(PARAM_RAW, 'Atom document Title'),
            'link'    => new external_value(PARAM_RAW, 'Atom document Link'),
            'email'   => new external_value(PARAM_RAW, 'Atom document Author Email'),
            'name'    => new external_value(PARAM_RAW, 'Atom document Author Name'),
119
            'updated' => new external_value(PARAM_RAW, 'Atom document Updated date'),
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
            'uri'     => new external_value(PARAM_RAW, 'Atom document URI'),
            'entries' => new external_multiple_structure(
                                new external_single_structure(
                                            array(
                                                    'id'        => new external_value(PARAM_RAW, 'Atom entry Id'),
                                                    'link'      => new external_value(PARAM_RAW, 'Atom entry Link'),
                                                    'email'     => new external_value(PARAM_RAW, 'Atom entry Author Link'),
                                                    'name'      => new external_value(PARAM_RAW, 'Atom entry Author Name'),
                                                    'updated'   => new external_value(PARAM_RAW, 'Atom entry updated date'),
                                                    'published' => new external_value(PARAM_RAW, 'Atom entry published date'),
                                                    'title'     => new external_value(PARAM_RAW, 'Atom entry Title'),
                                                    'summary'   => new external_value(PARAM_RAW, 'Atom entry Summary', VALUE_OPTIONAL),
                                                    'content'   => new external_value(PARAM_RAW, 'Atom entry Content', VALUE_OPTIONAL),
                                                    ), 'Atom entry', VALUE_OPTIONAL)
                    , 'Entries', VALUE_OPTIONAL),
                )
    );
}

/**
 * validate the user for webservices access
 * the account must use the webservice auth plugin
 * the account must have membership for the selected auth_instance
 *
 * @param object $dbuser
145
 * @return object $auth_instance or null if $dbuser is empty
146 147 148 149
 */
function webservice_validate_user($dbuser) {
    global $SESSION;
    if (!empty($dbuser)) {
150 151 152 153 154 155 156 157 158
        if ($auth_instance = get_record_sql("SELECT * FROM {auth_instance}
                                             WHERE authname = 'webservice'
                                             AND active = 1
                                             AND institution = (
                                                SELECT institution FROM {auth_instance}
                                                WHERE id = ?
                                                AND active = 1
                                             )", array($dbuser->authinstance))) {
            // User belongs to an institution that contains the 'webservice' auth method
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177
            $memberships = count_records('usr_institution', 'usr', $dbuser->id);
            if ($memberships == 0) {
                // auth instance should be a mahara one
                if ($auth_instance->institution == 'mahara') {
                    return $auth_instance;
                }
            }
            else {
                $membership = get_record('usr_institution', 'usr', $dbuser->id, 'institution', $auth_instance->institution);
                if (!empty($membership)) {
                    return $auth_instance;
                }
            }
        }
    }
    return NULL;
}

/**
178 179
 * List all potential webservice locations
 * (i.e. plugins, local, and the "pseudo-module" /webservice).
180 181 182 183
 *
 * @return array of web service plugin directories
 */
function get_ws_subsystems() {
184
    static $plugindirs = false;
185 186

    if (!$plugindirs) {
187 188 189 190 191 192 193
        $plugindirs = [
            'webservice',
            'local'
        ];
        $activeplugins = plugin_all_installed();
        foreach ($activeplugins as $plugindata) {
            $plugindirs[] = "{$plugindata->plugintype}/{$plugindata->name}";
194 195 196 197 198 199 200 201 202 203 204 205 206 207
        }
    }

    return $plugindirs;
}

/**
 *  Generate a web services token
 * @param string $tokentype
 * @param integer $serviceorid
 * @param integer $userid
 * @param string $institution
 * @param integer $validuntil
 * @param string $iprestriction
208 209 210
 * @param string $clientname (Optional) Human-readable name of client program using this token
 * @param string $clientenv (Optional) Human-readable description of device/environment for client
 * @param string $clientguid (Optional) Unique identifier for the client program
211 212 213
 * @throws WebserviceException
 * @return string token
 */
214
function webservice_generate_token($tokentype, $serviceorid, $userid, $institution = 'mahara',  $validuntil = 0, $iprestriction = null, $clientname = null, $clientenv = null, $clientguid = null) {
215 216 217 218 219 220
    global $USER;
    // make sure the token doesn't exist (even if it should be almost impossible with the random generation)
    $numtries = 0;
    do {
        $numtries ++;
        $generatedtoken = md5(uniqid(rand(),1));
221
        if ($numtries > 5) {
222 223 224 225 226
            throw new WebserviceException('tokengenerationfailed');
        }
    } while (record_exists('external_tokens', 'token', $generatedtoken));
    $newtoken = new stdClass();
    $newtoken->token = $generatedtoken;
227
    if (!is_object($serviceorid)) {
228
        $service = get_record('external_services', 'id', $serviceorid);
229 230
    }
    else {
231 232 233 234 235
        $service = $serviceorid;
    }
    $newtoken->externalserviceid = $service->id;
    $newtoken->tokentype = $tokentype;
    $newtoken->userid = $userid;
236
    if ($tokentype == EXTERNAL_TOKEN_EMBEDDED) {
237 238 239 240 241
        $newtoken->sid = session_id();
    }

    $newtoken->institution = $institution;
    $newtoken->creatorid = $USER->get('id');
242
    $newtoken->ctime = db_format_timestamp(time());
243
    $newtoken->timecreated = time();
244 245 246 247
    $newtoken->publickeyexpires = time();
    $newtoken->wssigenc = 0;
    $newtoken->publickey = '';
    $newtoken->validuntil = $validuntil;
248 249 250 251
    $newtoken->clientname = $clientname;
    $newtoken->clientenv = $clientenv;
    $newtoken->clientguid = $clientguid;
    $newtoken->iprestriction = $iprestriction;
252 253 254 255 256 257 258 259 260 261
    insert_record('external_tokens', $newtoken);
    return $newtoken->token;
}

/**
 * Create and return a session linked token. Token to be used for html embedded client apps that want to communicate
 * with the Moodle server through web services. The token is linked to the current session for the current page request.
 * It is expected this will be called in the script generating the html page that is embedding the client app and that the
 * returned token will be somehow passed into the client app being embedded in the page.
 * @param string $servicename name of the web service. Service name as defined in db/services.php
262 263 264 265
 * @param integer $userid
 * @param string $institution
 * @param integer $validuntil
 * @param string $iprestriction
266 267
 * @return int returns token id.
 */
268
function webservice_create_service_token($servicename, $userid, $institution = 'mahara',  $validuntil=0, $iprestriction='') {
269 270 271 272
    $service = get_record('external_services', 'name', $servicename, '*');
    return webservice_generate_token(EXTERNAL_TOKEN_EMBEDDED, $service, $userid, $institution,  $validuntil, $iprestriction);
}

273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313
/**
 * Calculate where the webservices directory should be, for a given value of
 * "component".
 *
 * There are three general types of "component" value we expect to see.
 * 1. "webservice": Indicates a the "core" webservices, which are in htdocs/webservice
 * 2. "local": Indicates custom webservices under htdocs/local/webservice
 * 3. "{plugintype}/{pluginname}": Indicates webservices for a plugin.
 *
 * @param string $component The component to look for
 * @param reference $plugintype If the component represents a plugin, the plugin's type will
 * be returned via this variable, passed by reference.
 * @param reference $pluginname If the component represents a plugin, the plugin's name will
 * be returned via this variable, passed by reference.
 * @return string Relative path to the component's webservices directory. If the component
 * is a plugin, this path will be relative the plugin's directory. Otherwise, it'll be
 * relative to $CFG->docroot.
 * @throws WebserviceCodingException
 */
function webservice_component_ws_directory($component, &$plugintype, &$pluginname) {
    if ($component == WEBSERVICE_DIRECTORY) {
        $plugintype = false;
        $pluginname = false;
        return WEBSERVICE_DIRECTORY;
    }

    if ($component == 'local') {
        $plugintype = false;
        $pluginname = false;
        return 'local/' . WEBSERVICE_DIRECTORY;
    }

    $bits = explode('/', $component);
    if (count($bits) == 2) {
        list($plugintype, $pluginname) = $bits;
        return WEBSERVICE_DIRECTORY;
    }

    throw new WebserviceCodingException("Invalid component name: '{$component}'");
}

314 315 316 317 318 319 320
/**
 * Returns detailed function information
 * @param string|object $function name of external function or record from external_function
 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
 *                        MUST_EXIST means throw exception if no record or multiple records found
 * @return object description or false if not found or exception thrown
 */
321 322
function webservice_function_info($function, $strictness=MUST_EXIST, $component = null) {
    $mustexist = ($strictness === MUST_EXIST);
323
    if (!is_object($function)) {
324 325 326 327 328 329 330
        if ($component) {
            $function = get_record('external_functions', 'name', $function, 'component', $component);
        }
        else {
            $function = get_record('external_functions', 'name', $function);
        }
        if (!$function) {
331 332
            return false;
        }
333
        $component = $function->component;
334 335 336
    }

    //first find and include the ext implementation class
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371
    if (!class_exists($function->classname)) {

        $wsdir = webservice_component_ws_directory(
            $function->component,
            $plugintype,
            $pluginname
        );

        if ($plugintype && $pluginname) {
            // Standard plugin; can use safe_require
            $foundfile = safe_require_plugin(
                $plugintype,
                $pluginname,
                $wsdir . '/functions/' . $function->classname . '.php',
                'require_once',
                true
            );
            if (!$foundfile) {
                if ($mustexist) {
                    throw new WebserviceCodingException(get_string('cannotfindimplfile', 'auth.webservice'));
                }
                return false;
            }
        }
        else {
            // Not a plugin, must handle manually
            $filepath = get_config('docroot') . $wsdir . '/functions/' . $function->classname . '.php';
            if (!file_exists($filepath)) {
                if ($mustexist) {
                    throw new WebserviceCodingException(get_string('cannotfindimplfile', 'auth.webservice'));
                }
                return false;
            }
            require_once($filepath);
        }
372 373 374 375 376 377 378
    }

    $function->parameters_method = $function->methodname . '_parameters';
    $function->returns_method    = $function->methodname . '_returns';

    // make sure the implementaion class is ok
    if (!method_exists($function->classname, $function->methodname)) {
379 380 381 382
        if ($mustexist) {
            throw new WebserviceCodingException(get_string('missingimplofmeth', 'auth.webservice', $function->classname . '::' . $function->methodname));
        }
        return false;
383 384
    }
    if (!method_exists($function->classname, $function->parameters_method)) {
385 386 387 388
        if ($mustexist) {
            throw new WebserviceCodingException(get_string('missingparamdesc', 'auth.webservice'));
        }
        return false;
389 390
    }
    if (!method_exists($function->classname, $function->returns_method)) {
391 392 393 394
        if ($mustexist) {
            throw new WebserviceCodingException(get_string('missingretvaldesc', 'auth.webservice'));
        }
        return false;
395 396 397 398 399
    }

    // fetch the parameters description
    $function->parameters_desc = call_user_func(array($function->classname, $function->parameters_method));
    if (!($function->parameters_desc instanceof external_function_parameters)) {
400 401 402 403
        if ($mustexist) {
            throw new WebserviceCodingException(get_string('invalidparamdesc', 'auth.webservice'));
        }
        return false;
404 405 406 407 408 409
    }

    // fetch the return values description
    $function->returns_desc = call_user_func(array($function->classname, $function->returns_method));
    // null means void result or result is ignored
    if (!is_null($function->returns_desc) and !($function->returns_desc instanceof external_description)) {
410 411 412 413
        if ($mustexist) {
            throw new WebserviceCodingException(get_string('invalidretdesc', 'auth.webservice'));
        }
        return false;
414 415 416 417 418 419 420 421
    }

    //now get the function description
    //TODO: use localised lang pack descriptions, it would be nice to have
    //      easy to understand descriptions in admin UI,
    //      on the other hand this is still a bit in a flux and we need to find some new naming
    //      conventions for these descriptions in lang packs
    $function->description = null;
422 423 424 425
    $result = webservice_load_services_file($function->component);
    $functionlist = $result['functions'];
    if (isset($functionlist[$function->name]['description'])) {
        $function->description = $functionlist[$function->name]['description'];
426 427 428 429 430
    }

    return $function;
}

431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448
/**
 * Returns a list of all of the webservice connection definitions declared
 * by all of the installed plugins.
 */
function webservice_connection_definitions() {

    $connections = array();

    $plugins = array();
    $plugins['blocktype'] = array();

    foreach (plugin_types()  as $plugin) {
        // this has to happen first because of broken artefact/blocktype ordering
        $plugins[$plugin] = array();
        $plugins[$plugin]['installed'] = array();
        $plugins[$plugin]['notinstalled'] = array();
    }
    foreach (array_keys($plugins) as $plugin) {
449
        if (db_table_exists($plugin . '_installed')) {
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489
            if ($installed = plugins_installed($plugin, true)) {
                foreach ($installed as $i) {
                    $key = $i->name;
                    if ($plugin == 'blocktype') {
                        $key = blocktype_single_to_namespaced($i->name, $i->artefactplugin);
                    }
                    if (!safe_require_plugin($plugin, $key)) {
                        continue;
                    }
                    if ($i->active) {
                        $classname = generate_class_name($plugin, $key);
                        if (method_exists($classname, 'define_webservice_connections')) {
                            $conns = call_static_method($classname, 'define_webservice_connections');
                            if (!empty($conns)) {
                                $connections[$classname] = array('connections' => $conns, 'type' => $plugin, 'key' => $key);
                            }
                        }
                    }
                    if ($plugin == 'artefact') {
                        safe_require('artefact', $key);
                        if ($types = call_static_method(generate_class_name('artefact', $i->name), 'get_artefact_types')) {
                            foreach ($types as $t) {
                                $classname = generate_artefact_class_name($t);
                                if (method_exists($classname, 'define_webservice_connections')) {
                                    $conns = call_static_method($classname, 'define_webservice_connections');
                                    if (!empty($conns)) {
                                        $connections[$classname] = array('connections' => $conns, 'type' => $plugin, 'key' => $key);
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    return $connections;
}


490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510
/**
 * General web service library
 */
class webservice {

    /**
     * Get the list of all functions for given service ids
     * @param array $serviceids
     * @return array functions
     */
    public function get_external_functions($serviceids) {
        global $WS_FUNCTIONS;

        if (!empty($serviceids)) {
            $where = (count($serviceids) == 1 ? ' = '.array_shift($serviceids) : ' IN (' . implode(',', $serviceids) . ')');
            $sql = "SELECT f.*
                      FROM {external_functions} f
                     WHERE f.name IN (SELECT sf.functionname
                                        FROM {external_services_functions} sf
                                       WHERE sf.externalserviceid $where)";
            $functions = get_records_sql_array($sql, array());
511 512
        }
        else {
513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562
            $functions = array();
        }

        // stash functions for intro spective RPC calls later
        $WS_FUNCTIONS = array();
        foreach ($functions as $function) {
            $WS_FUNCTIONS[$function->name] = array('id' => $function->id);
        }

        return $functions;
    }
}

/**
 * Base class for external api methods.
 */
class external_api {
    private static $contextrestriction;

    /**
     * Set context restriction for all following subsequent function calls.
     * @param stdClass $contex
     * @return void
     */
    public static function set_context_restriction($context) {
        self::$contextrestriction = $context;
    }

    /**
     * This method has to be called before every operation
     * that takes a longer time to finish!
     *
     * @param int $seconds max expected time the next operation needs
     * @return void
     */
    public static function set_timeout($seconds=360) {
        $seconds = ($seconds < 300) ? 300 : $seconds;
        set_time_limit($seconds);
    }

    /**
     * Validates submitted function parameters, if anything is incorrect
     * WebserviceInvalidParameterException is thrown.
     * This is a simple recursive method which is intended to be called from
     * each implementation method of external API.
     * @param external_description $description description of parameters
     * @param mixed $params the actual parameters
     * @return mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found
     */
    public static function validate_parameters(external_description $description, $params) {
563 564 565 566 567
        // we need to turn the social profile information into a single string to pass external_value test
        // because we can either pass in the information as a string 'profiletype|profileurl' or as an array
        if (isset($params['socialprofile']) && is_array($params['socialprofile'])) {
            $params['socialprofile'] = (!empty($params['socialprofile']['profiletype']) ? $params['socialprofile']['profiletype'] : '') . '|' . (!empty($params['socialprofile']['profileurl']) ? $params['socialprofile']['profileurl'] : '');
        }
568 569 570 571 572 573 574 575 576 577 578 579 580
        if ($description instanceof external_value) {
            if (is_array($params) or is_object($params)) {
                throw new WebserviceInvalidParameterException(get_string('errorscalartype', 'auth.webservice'));
            }

            if ($description->type == PARAM_BOOL) {
                // special case for PARAM_BOOL - we want true/false instead of the usual 1/0 - we can not be too strict here ;-)
                if (is_bool($params) or $params === 0 or $params === 1 or $params === '0' or $params === '1') {
                    return (bool)$params;
                }
            }
            return validate_param($params, $description->type, $description->allownull, get_string('errorinvalidparamsapi', 'auth.webservice'));

581 582
        }
        else if ($description instanceof external_single_structure) {
583 584 585 586 587 588 589 590 591 592
            if (!is_array($params)) {
                throw new WebserviceInvalidParameterException(get_string('erroronlyarray', 'auth.webservice'));
            }
            $result = array();
            foreach ($description->keys as $key=>$subdesc) {
                if (!array_key_exists($key, $params)) {
                    if ($subdesc->required == VALUE_REQUIRED) {
                        throw new WebserviceInvalidParameterException(get_string('errormissingkey', 'auth.webservice', $key));
                    }
                    if ($subdesc->required == VALUE_DEFAULT) {
593
                        $result[$key] = $subdesc->default;
594
                    }
Matt Clarkson's avatar
Matt Clarkson committed
595 596 597 598 599

                    if ($subdesc->required == VALUE_OPTIONAL) {
                        $result[$key] = null;
                    }

600 601
                }
                else {
602 603 604 605
                    try {
                        $result[$key] = self::validate_parameters($subdesc, $params[$key]);
                    } catch (WebserviceInvalidParameterException $e) {
                        //it's ok to display debug info as here the information is useful for ws client/dev
606
                        throw new WebserviceParameterException(get_string('invalidextparam', 'auth.webservice', "key: $key - " . $e->getMessage() . (isset($e->debuginfo) ? " (debuginfo: " . $e->debuginfo . ") " : "")));
607 608 609 610 611 612 613
                    }
                }
                unset($params[$key]);
            }
            if (!empty($params)) {
                //list all unexpected keys
                $keys = '';
614
                $customkeys = '';
615
                foreach ($params as $key => $value) {
616 617 618 619 620 621 622 623 624 625
                    if (substr($key, 0, 7) === "custom_") {
                        $customkeys .= $key . ',';
                    }
                    else {
                        $keys .= $key . ',';
                    }
                }
                if (!empty($customkeys) && !get_config('productionmode')) {
                    log_info(get_string('errorunexpectedcustomkey', 'auth.webservice', $customkeys));
                }
626 627 628 629
                if (!empty($keys) && !get_config('productionmode')) {
                    // We will stop throwing error on unexpected param keys and instead just show them in error log
                    // when the site is not in production mode
                    log_info(get_string('errorunexpectedkey', 'auth.webservice', $keys));
630 631 632 633
                }
            }
            return $result;

634 635
        }
        else if ($description instanceof external_multiple_structure) {
636 637 638 639 640 641 642 643 644
            if (!is_array($params)) {
                throw new WebserviceInvalidParameterException(get_string('erroronlyarray', 'auth.webservice'));
            }
            $result = array();
            foreach ($params as $param) {
                $result[] = self::validate_parameters($description->content, $param);
            }
            return $result;

645 646
        }
        else {
647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674
            throw new WebserviceInvalidParameterException(get_string('errorinvalidparamsdesc', 'auth.webservice'));
        }
    }

    /**
     * Clean response
     * If a response attribute is unknown from the description, we just ignore the attribute.
     * If a response attribute is incorrect, WebserviceInvalidResponseException is thrown.
     * Note: this function is similar to validate parameters, however it is distinct because
     * parameters validation must be distinct from cleaning return values.
     * @param external_description $description description of the return values
     * @param mixed $response the actual response
     * @return mixed response with added defaults for optional items, WebserviceInvalidResponseException thrown if any problem found
     */
    public static function clean_returnvalue(external_description $description, $response) {
        if ($description instanceof external_value) {
            if (is_array($response) or is_object($response)) {
                throw new WebserviceInvalidResponseException(get_string('errorscalartype', 'auth.webservice'));
            }

            if ($description->type == PARAM_BOOL) {
                // special case for PARAM_BOOL - we want true/false instead of the usual 1/0 - we can not be too strict here ;-)
                if (is_bool($response) or $response === 0 or $response === 1 or $response === '0' or $response === '1') {
                    return (bool)$response;
                }
            }
            return validate_param($response, $description->type, $description->allownull, get_string('errorinvalidresponseapi', 'auth.webservice'));

675 676
        }
        else if ($description instanceof external_single_structure) {
677 678 679 680 681 682 683 684 685 686 687
            if ($response === null) {
                if ($description->required == VALUE_REQUIRED) {
                    throw new WebserviceInvalidParameterException(get_string('errormissingkey', 'auth.webservice', $description->type));
                }
                else if ($description->required == VALUE_DEFAULT) {
                    return $description->default;
                }
                else {
                    return null;
                }
            }
688 689 690 691 692 693 694 695 696
            if (!is_array($response)) {
                throw new WebserviceInvalidResponseException(get_string('erroronlyarray', 'auth.webservice'));
            }
            $result = array();
            foreach ($description->keys as $key=>$subdesc) {
                if (!array_key_exists($key, $response)) {
                    if ($subdesc->required == VALUE_REQUIRED) {
                        throw new WebserviceParameterException('errorresponsemissingkey', $key);
                    }
697 698 699 700 701 702
                    else if ($subdesc->required == VALUE_DEFAULT) {
                        try {
                            $result[$key] = self::clean_returnvalue($subdesc, $subdesc->default);
                        }
                        catch (Exception $e) {
                            throw new WebserviceParameterException('invalidextresponse',$key . " (" . $e->getMessage() . ")");
703 704
                        }
                    }
705 706
                }
                else {
707 708 709 710 711 712 713 714 715 716 717 718
                    try {
                        $result[$key] = self::clean_returnvalue($subdesc, $response[$key]);
                    } catch (Exception $e) {
                        //it's ok to display debug info as here the information is useful for ws client/dev
                        throw new WebserviceParameterException('invalidextresponse', $key . " (" . $e->getMessage() . ")");
                    }
                }
                unset($response[$key]);
            }

            return $result;

719 720
        }
        else if ($description instanceof external_multiple_structure) {
721 722 723 724 725 726 727 728 729 730 731
            if ($response === null) {
                if ($description->required == VALUE_REQUIRED) {
                    throw new WebserviceInvalidParameterException(get_string('errormissingkey', 'auth.webservice', $description->type));
                }
                else if ($description->required == VALUE_DEFAULT) {
                    return $description->default;
                }
                else {
                    return null;
                }
            }
732 733 734 735 736 737 738 739 740
            if (!is_array($response)) {
                throw new WebserviceInvalidResponseException(get_string('erroronlyarray', 'auth.webservice'));
            }
            $result = array();
            foreach ($response as $param) {
                $result[] = self::clean_returnvalue($description->content, $param);
            }
            return $result;

741 742
        }
        else {
743 744 745
            throw new WebserviceInvalidResponseException(get_string('errorinvalidresponsedesc', 'auth.webservice'));
        }
    }
746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819

    /**
     * Returns detailed function information
     *
     * @param string|object $function name of external function or record from external_function
     * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
     *                        MUST_EXIST means throw exception if no record or multiple records found
     * @return stdClass description or false if not found or exception thrown
     */
    public static function external_function_info($function, $strictness=MUST_EXIST) {

        if (!is_object($function)) {
            if (!$function = get_record('external_functions', 'name', $function)) {
                return false;
            }
        }

        // First try class autoloading.
        if (!class_exists($function->classname)) {
            if ($function->classpath == 'webservice') {
                $function->classpath = get_config('docroot') . $function->classpath . '/functions/' . $function->classname . '.php';
            }
            else {
                $function->classpath = get_config('docroot') . $function->classpath;
                if (!preg_match('/\.php$/', $function->classpath)) {
                    $function->classpath .= '/functions/' . $function->classname . '.php';
                }
            }
            if (!file_exists($function->classpath)) {
                throw new MaharaException('Cannot find file with external function implementation');
            }
            require_once($function->classpath);
            if (!class_exists($function->classname)) {
                throw new MaharaException('Cannot find external class');
            }
        }

        $function->ajax_method = $function->methodname . '_is_allowed_from_ajax';
        $function->parameters_method = $function->methodname . '_parameters';
        $function->returns_method    = $function->methodname . '_returns';
        $function->deprecated_method = $function->methodname . '_is_deprecated';

        // Make sure the implementaion class is ok.
        if (!method_exists($function->classname, $function->methodname)) {
            throw new MaharaException('Missing implementation method of ' . $function->classname . '::' . $function->methodname);
        }
        if (!method_exists($function->classname, $function->parameters_method)) {
            throw new MaharaException('Missing parameters description');
        }
        if (!method_exists($function->classname, $function->returns_method)) {
            throw new MaharaException('Missing returned values description');
        }
        if (method_exists($function->classname, $function->deprecated_method)) {
            if (call_user_func(array($function->classname, $function->deprecated_method)) === true) {
                $function->deprecated = true;
            }
        }
        $function->allowed_from_ajax = false;

        // Fetch the parameters description.
        $function->parameters_desc = call_user_func(array($function->classname, $function->parameters_method));
        if (!($function->parameters_desc instanceof external_function_parameters)) {
            throw new MaharaException('Invalid parameters description');
        }

        // Fetch the return values description.
        $function->returns_desc = call_user_func(array($function->classname, $function->returns_method));
        // Null means void result or result is ignored.
        if (!is_null($function->returns_desc) and !($function->returns_desc instanceof external_description)) {
            throw new MaharaException('Invalid return description');
        }

        return $function;
    }
820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861
}

/**
 * Common ancestor of all parameter description classes
 */
abstract class external_description {
    /** @property string $description description of element */
    public $desc;
    /** @property bool $required element value required, null not allowed */
    public $required;
    /** @property mixed $default default value */
    public $default;

    /**
     * Contructor
     * @param string $desc
     * @param bool $required
     * @param mixed $default
     */
    public function __construct($desc, $required, $default) {
        $this->desc = $desc;
        $this->required = $required;
        $this->default = $default;
    }
}

/**
 * Scalar alue description class
 */
class external_value extends external_description {
    /** @property mixed $type value type PARAM_XX */
    public $type;
    /** @property bool $allownull allow null values */
    public $allownull;

    /**
     * Constructor
     * @param mixed $type
     * @param string $desc
     * @param bool $required
     * @param mixed $default
     * @param bool $allownull
862
     * @param bool $oneof
863 864
     */
    public function __construct($type, $desc='', $required=VALUE_REQUIRED,
865
    $default=null, $allownull=NULL_ALLOWED, $oneof=false) {
866 867 868
        parent::__construct($desc, $required, $default);
        $this->type      = $type;
        $this->allownull = $allownull;
869
        $this->oneof     = $oneof; // a string to identify a oneof grouping
870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921
    }
}

/**
 * Associative array description class
 */
class external_single_structure extends external_description {
    /** @property array $keys description of array keys key=>external_description */
    public $keys;

    /**
     * Constructor
     * @param array $keys
     * @param string $desc
     * @param bool $required
     * @param array $default
     */
    public function __construct(array $keys, $desc='',
    $required=VALUE_REQUIRED, $default=null) {
        parent::__construct($desc, $required, $default);
        $this->keys = $keys;
    }
}

/**
 * Bulk array description class.
 */
class external_multiple_structure extends external_description {
    /** @property external_description $content */
    public $content;

    /**
     * Constructor
     * @param external_description $content
     * @param string $desc
     * @param bool $required
     * @param array $default
     */
    public function __construct(external_description $content, $desc='',
    $required=VALUE_REQUIRED, $default=null) {
        parent::__construct($desc, $required, $default);
        $this->content = $content;
    }
}

/**
 * Description of top level - PHP function parameters.
 * @author skodak
 *
 */
class external_function_parameters extends external_single_structure {
}
922

923 924 925 926 927 928
/**
 * Is protocol enabled?
 * @param string $protocol name of WS protocol
 * @return bool
 */
function webservice_protocol_is_enabled($protocol) {
929
    if (!get_config('webservice_provider_enabled')) {
930 931
        return false;
    }
932
    return get_config('webservice_provider_'.$protocol.'_enabled');
933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012
}

//=== WS classes ===

/**
 * Mandatory interface for all test client classes.
 * @author Petr Skoda (skodak)
 */
interface webservice_test_client_interface {
    /**
     * Execute test client WS request
     * @param string $serverurl
     * @param string $function
     * @param array $params
     * @return mixed
     */
    public function simpletest($serverurl, $function, $params);
}

/**
 * Mandatory interface for all web service protocol classes
 * @author Petr Skoda (skodak)
 */
interface webservice_server_interface {
    /**
     * Process request from client.
     * @return void
     */
    public function run();
}

/**
 * Abstract web service base class.
 * @author Petr Skoda (skodak)
 */
abstract class webservice_server implements webservice_server_interface {

    /** @property string $wsname name of the web server plugin */
    protected $wsname = null;

    /** @property string $username name of local user */
    protected $username = null;

    /** @property string $password password of the local user */
    protected $password = null;

    /** @property string $service service for wsdl look up */
    protected $service = null;

    /** @property int $userid the local user */
    protected $userid = null;

    /** @property integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_* */
    protected $authmethod;

    /** @property string $token authentication token*/
    protected $token = null;

    /** @property int restrict call to one service id*/
    protected $restricted_serviceid = null;

    /** @property string info to add to logging*/
    protected $info = null;
    /**
     * Contructor
     * @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_*
     */
    public function __construct($authmethod) {
        $this->authmethod = $authmethod;
    }

    /**
     * Authenticate user using username+password or token.
     * This function sets up $USER global.
     * It is safe to use has_capability() after this.
     * This method also verifies user is allowed to use this
     * server.
     * @return void
     */
    protected function authenticate_user() {
Matt Clarkson's avatar
Matt Clarkson committed
1013
        global $USER, $SESSION, $WEBSERVICE_INSTITUTION, $WEBSERVICE_OAUTH_USER, $WEBSERVICE_OAUTH_SERVERID;
1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052
        if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
            $this->auth = 'USER';
            //we check that authentication plugin is enabled
            //it is only required by simple authentication
            $plugin = get_record('auth_installed', 'name', 'webservice');
            if (empty($plugin) || $plugin->active != 1) {
                throw new WebserviceAccessException(get_string('wsauthnotenabled', 'auth.webservice'));
            }

            if (!$this->username) {
                throw new WebserviceAccessException(get_string('missingusername', 'auth.webservice'));
            }

            if (!$this->password) {
                throw new WebserviceAccessException(get_string('missingpassword', 'auth.webservice'));
            }

            // special web service login
            safe_require('auth', 'webservice');

            // get the user
            $user = get_record('usr', 'username', $this->username);
            if (empty($user)) {
                throw new WebserviceAccessException(get_string('wrongusernamepassword', 'auth.webservice'));
            }

            // user account is nolonger validly configured
            if (!$auth_instance = webservice_validate_user($user)) {
                throw new WebserviceAccessException(get_string('invalidaccount', 'auth.webservice'));
            }
            // set the global for the web service users defined institution
            $WEBSERVICE_INSTITUTION = $auth_instance->institution;

            // get the institution from the external user
            $ext_user = get_record('external_services_users', 'userid', $user->id);
            if (empty($ext_user)) {
                throw new WebserviceAccessException(get_string('wrongusernamepassword', 'auth.webservice'));
            }
            // determine the internal auth instance
1053
            $auth_instance = get_record('auth_instance', 'institution', $ext_user->institution, 'authname', 'webservice', 'active', 1);
1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065
            if (empty($auth_instance)) {
                throw new WebserviceAccessException(get_string('wrongusernamepassword', 'auth.webservice'));
            }

            // authenticate the user
            $auth = new AuthWebservice($auth_instance->id);
            if (!$auth->authenticate_user_account($user, $this->password, 'webservice')) {
                // log failed login attempts
                throw new WebserviceAccessException(get_string('wrongusernamepassword', 'auth.webservice'));
            }

        }
1066
        else if ($this->authmethod == WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN) {
1067 1068 1069
            $this->auth = 'TOKEN';
            $user = $this->authenticate_by_token(EXTERNAL_TOKEN_PERMANENT);
        }
1070
        else if ($this->authmethod == WEBSERVICE_AUTHMETHOD_OAUTH_TOKEN) {
1071 1072 1073 1074 1075 1076
            //OAuth
            $this->auth = 'OAUTH';
            // special web service login
            safe_require('auth', 'webservice');

            // get the user - the user that authorised the token
1077 1078
            $user = $this->authenticate_by_token(EXTERNAL_TOKEN_OAUTH1);

Matt Clarkson's avatar
Matt Clarkson committed
1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096
            $is_site_admin = false;

            foreach (get_site_admins() as $site_admin) {
                if ($site_admin->id == $user->id) {
                    $is_site_admin = true;
                    break;
                }
            }

            if (!$is_site_admin) {

                // check user is member of configured OAuth institution
                $institutions = array_keys(load_user_institutions($this->oauth_token_details['user_id']));
                $auth_instance = get_record('auth_instance', 'id', $user->authinstance, 'active', 1);
                $institutions[]= $auth_instance->institution;
                if (!in_array($this->oauth_token_details['institution'], $institutions)) {
                    throw new WebserviceAccessException(get_string('institutiondenied', 'auth.webservice'));
                }
1097 1098 1099 1100 1101 1102
            }

            // set the global for the web service users defined institution
            $WEBSERVICE_INSTITUTION = $this->oauth_token_details['institution'];
            // set the note of the OAuth service owner
            $WEBSERVICE_OAUTH_USER = $this->oauth_token_details['service_user'];
Matt Clarkson's avatar
Matt Clarkson committed
1103 1104
            // set the OAuth server id
            $WEBSERVICE_OAUTH_SERVERID = $this->oauth_token_details['id'];
1105 1106
        }
        else {
1107 1108 1109 1110 1111 1112 1113 1114
            $this->auth = 'OTHER';
            $user = $this->authenticate_by_token(EXTERNAL_TOKEN_USER);
        }

        // now fake user login, the session is completely empty too
        $USER->reanimate($user->id, $user->authinstance);
    }

1115 1116 1117 1118 1119 1120
    /**
     * Authenticate by token type
     *
     * @param $tokentype string tokentype constant
     * @return $user object
     */
1121
    public function authenticate_by_token($tokentype) {
1122 1123
        global $WEBSERVICE_INSTITUTION;

1124 1125 1126 1127 1128 1129 1130
        if ($tokentype == EXTERNAL_TOKEN_OAUTH1) {
            $user = get_record('usr', 'id', $this->oauth_token_details['user_id']);
            if (empty($user)) {
                throw new WebserviceAccessException(get_string('wrongusernamepassword', 'auth.webservice'));
            }
            return $user;
        }
1131

1132 1133 1134 1135
        if (empty($this->token)) {
            // log failed login attempts
            throw new WebserviceAccessException(get_string('invalidtokennotsupplied', 'auth.webservice'));
        }
1136 1137

        $token = get_record('external_tokens', 'token', $this->token);
1138 1139 1140 1141
        if (!$token) {
            // log failed login attempts
            throw new WebserviceAccessException(get_string('invalidtoken', 'auth.webservice'));
        }
1142 1143

        // tidy up the auth method - this could be user token or session token
1144
        if ($token->tokentype != EXTERNAL_TOKEN_PERMANENT) {
1145 1146 1147 1148 1149 1150 1151
            if ($token->tokentype === EXTERNAL_TOKEN_USER) {
                // TODO: These should probably be constants, not strings...
                $this->auth = 'TOKEN_USER';
            }
            else {
                $this->auth = 'OTHER';
            }
1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162
        }

        /**
         * check the valid until date
         */
        if ($token->validuntil and $token->validuntil < time()) {
            delete_records('external_tokens', 'token', $this->token, 'tokentype', $tokentype);
            throw new WebserviceAccessException(get_string('invalidtimedtoken', 'auth.webservice'));
        }

        //assumes that if sid is set then there must be a valid associated session no matter the token type
1163
        if ($token->sid) {
1164
            $session = session_get_instance();
1165
            if (!$session->session_exists($token->sid)) {
1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179
                delete_records('external_tokens', 'sid', $token->sid);
                throw new WebserviceAccessException(get_string('invalidtokensession', 'auth.webservice'));
            }
        }

        if ($token->iprestriction and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {
            throw new WebserviceAccessException(get_string('invalidiptoken', 'auth.webservice'));
        }

        $this->restricted_serviceid = $token->externalserviceid;

        $user = get_record('usr', 'id', $token->userid, 'deleted', 0);

        // log token access
1180
        set_field('external_tokens', 'mtime', db_format_timestamp(time()), 'id', $token->id);
1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218

        // set the global for the web service users defined institution
        $WEBSERVICE_INSTITUTION = $token->institution;

        return $user;
    }

    /**
     * Intercept some maharawssettingXXX $_GET and $_POST parameter
     * that are related to the web service call and are not the function parameters
     */
    protected function set_web_service_call_settings() {
        global $CFG;

        // Default web service settings.
        // Must be the same XXX key name as the external_settings::set_XXX function.
        // Must be the same XXX ws parameter name as 'maharawssettingXXX'.
        $externalsettings = array(
            'raw' => false,
            'fileurl' => true,
            'filter' =>  false);

        // Load the external settings with the web service settings.
        $settings = external_settings::get_instance();
        foreach ($externalsettings as $name => $default) {

            $wsparamname = 'maharawssetting' . $name;

            // Retrieve and remove the setting parameter from the request.
            $value = param_variable($wsparamname, $default);
            unset($_GET[$wsparamname]);
            unset($_POST[$wsparamname]);

            $functioname = 'set_' . $name;
            $settings->$functioname($value);
        }

    }
1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311

    /**
     * Gets information about services the authenticated user is allowed
     * to access.
     * @param string $serviceid (Optional) Only look at this service
     * @param string $functionname (Optional) Services must contain this function
     * @throws WebserviceInvalidParameterException
     */
    protected function get_allowed_services($serviceid = false, $functionname = false) {
        global $USER;

        if ($functionname) {
            $fncond1 = 'AND sf.functionname = ?';
            $fncond2 = 'AND sf.functionname = ?';
        }
        else {
            $fncond1 = '';
            $fncond2 = '';
        }

        if ($serviceid) {
            $wscond1 = 'AND s.id = ? ';
            $wscond2 = 'AND s.id = ? ';
        }
        else {
            $wscond1 = '';
            $wscond2 = '';
        }

        if ($this->auth === 'TOKEN_USER') {
            $tokencond = 'AND s.tokenusers = 1';
        }
        else {
            $tokencond = '';
        }

        // now let's verify access control
        // Allow access only if:
        // - restrictedusers = 0
        // - OR
        //   - restrictedusers = 1
        //   - AND user is on the list for the service
        //   - AND user's listing hasn't expired
        //   - AND user's IP matches any restrictions for their listing
        $sql = "
            SELECT s.*, NULL AS iprestriction
            FROM
                {external_services} s
                INNER JOIN {external_services_functions} sf ON
                    sf.externalserviceid = s.id
                    AND s.restrictedusers = 0
                    $fncond1
            WHERE
                s.enabled = 1
                $tokencond
                $wscond1
        UNION
            SELECT s.*, su.iprestriction
            FROM
                {external_services} s
                INNER JOIN {external_services_functions} sf ON
                    sf.externalserviceid = s.id
                    AND s.restrictedusers = 1
                    $fncond2
                INNER JOIN {external_services_users} su ON
                    su.externalserviceid = s.id
                    AND su.userid = ?
            WHERE
                s.enabled = 1
                AND (su.validuntil IS NULL OR su.validuntil < ?)
                $tokencond
                $wscond2
";
        $params = array();
        $fncond1 && $params[] = $functionname;
        $wscond1 && $params[]= $serviceid;
        $fncond2 && $params[]= $functionname;
        $params[]= $USER->get('id');
        $params[]= time();
        $wscond2 && $params[]= $serviceid;
        $rs = get_records_sql_array($sql, $params);

        $remoteaddr = getremoteaddr();
        $serviceids = array();
        foreach ($rs as $service) {
            if ($service->iprestriction && !address_in_subnet($remoteaddr, $service->iprestriction)) {
                // wrong request source ip, sorry
                continue;
            }
            $serviceids[] = $service->id;
        }
        return $serviceids;
    }
1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377
}

/**
 * Web Service server base class, this class handles both
 * simple and token authentication.
 * @author Petr Skoda (skodak)
 */
abstract class webservice_base_server extends webservice_server {

    /** @property array $parameters the function parameters - the real values submitted in the request */
    protected $parameters = null;

    /** @property string $functionname the name of the function that is executed */
    protected $functionname = null;

    /** @property object $function full function description */
    protected $function = null;

    /** @property mixed $returns function return value */
    protected $returns = null;

    /**
     * This method parses the request input, it needs to get:
     *  1/ user authentication - username+password or token
     *  2/ function name
     *  3/ function parameters
     *
     * @return void
     */
    abstract protected function parse_request();

    /**
     * Send the result of function call to the WS client.
     * @return void
     */
    abstract protected function send_response();

    /**
     * Send the error information to the WS client.
     * @param exception $ex
     * @return void
     */
    abstract protected function send_error($ex=null);

    /**
     * Process request from client.
     * @return void
     */
    public function run() {
        global $WEBSERVICE_FUNCTION_RUN, $USER, $WEBSERVICE_INSTITUTION, $WEBSERVICE_START;

        $WEBSERVICE_START = microtime(true);

        // we will probably need a lot of memory in some functions
        raise_memory_limit('128M');

        // set some longer timeout, this script is not sending any output,
        // this means we need to manually extend the timeout operations
        // that need longer time to finish
        external_api::set_timeout();

        // set up exception handler first, we want to sent them back in correct format that
        // the other system understands
        // we do not need to call the original default handler because this ws handler does everything
        set_exception_handler(array($this, 'exception_handler'));

1378 1379 1380 1381
        // Set the auth method as UNKNOWN at this point - it should be changed to correct value
        // in authenticate_user() function
        $this->auth = 'UNKNOWN';

1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442
        // init all properties from the request data
        $this->parse_request();

        // authenticate user, this has to be done after the request parsing
        // this also sets up $USER and $SESSION
        $this->authenticate_user();

        // find all needed function info and make sure user may actually execute the function
        $this->load_function_info();

        // finally, execute the function - any errors are catched by the default exception handler
        $this->execute();

        $time_end = microtime(true);
        $time_taken = $time_end - $WEBSERVICE_START;

        //log the web service request
        $log = (object)  array('timelogged' => time(),
                               'userid' => $USER->get('id'),
                               'externalserviceid' => $this->restricted_serviceid,
                               'institution' => $WEBSERVICE_INSTITUTION,
                               'protocol' => 'REST',
                               'auth' => $this->auth,
                               'functionname' => $this->functionname,
                               'timetaken' => "" . $time_taken,
                               'uri' => $_SERVER['REQUEST_URI'],
                               'info' => '',
                               'ip' => getremoteaddr());
        insert_record('external_services_logs', $log, 'id', true);

        // send the results back in correct format
        $this->send_response();

        // session cleanup
        $this->session_cleanup();

        die;
    }

    /**
     * Specialised exception handler, we can not use the standard one because
     * it can not just print html to output.
     *
     * @param exception $ex
     * @return void does not return
     */
    public function exception_handler($ex) {
        global $WEBSERVICE_FUNCTION_RUN, $USER, $WEBSERVICE_INSTITUTION, $WEBSERVICE_START;

        // detect active db transactions, rollback and log as error
        db_rollback();

        $time_end = microtime(true);
        $time_taken = $time_end - $WEBSERVICE_START;

        //log the error on the web service request
        $log = (object)  array('timelogged' => time(),
                               'userid' => $USER->get('id'),
                               'externalserviceid' => $this->restricted_serviceid,
                               'institution' => $WEBSERVICE_INSTITUTION,
                               'protocol' => 'REST',
1443
                               'auth' => $this->auth,
1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468
                               'functionname' => ($WEBSERVICE_FUNCTION_RUN ? $WEBSERVICE_FUNCTION_RUN : $this->functionname),
                               'timetaken' => '' . $time_taken,
                               'uri' => $_SERVER['REQUEST_URI'],
                               'info' => 'exception: ' . get_class($ex) . ' message: ' . $ex->getMessage() . ' debuginfo: ' . (isset($ex->debuginfo) ? $ex->debuginfo : ''),
                               'ip' => getremoteaddr());
        insert_record('external_services_logs', $log, 'id', true);

        // some hacks might need a cleanup hook
        $this->session_cleanup($ex);

        // now let the plugin send the exception to client
        $this->send_error($ex);

        // not much else we can do now, add some logging later
        exit(1);
    }

    /**
     * Future hook needed for emulated sessions.
     * @param exception $exception null means normal termination, $exception received when WS call failed
     * @return void
     */
    protected function session_cleanup($exception=null) {
        if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
            // nothing needs to be done, there is no persistent session
1469 1470
        }
        else {
1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484
            // close emulated session if used
        }
    }

    /**
     * Fetches the function description from database,
     * verifies user is allowed to use this function and
     * loads all paremeters and return descriptions.
     * @return void
     */
    protected function load_function_info() {
        global $USER;

        if (empty($this->functionname)) {
1485
            throw new WebserviceInvalidParameterException(get_string('missingfuncname', 'auth.webservice'));
1486 1487 1488 1489 1490
        }

        // function must exist
        $function = webservice_function_info($this->functionname);
        if (!$function) {
1491
            throw new WebserviceInvalidParameterException(get_string('accessextfunctionnotconf', 'auth.webservice'));
1492
        }
1493

1494 1495 1496 1497
        // Check that the function is in a service this user is allowed
        // to access.
        $serviceids = $this->get_allowed_services($this->restricted_serviceid, $this->functionname);
        if (!count($serviceids)) {
1498 1499
            throw new WebserviceAccessException(get_string('accesstofunctionnotallowed', 'auth.webservice', $this->functionname));
        }
1500

1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515
        // now get the list of all functions - this triggers the stashing of
        // functions in the context
        $wsmanager = new webservice();
        $functions = $wsmanager->get_external_functions($serviceids);

        // we have all we need now
        $this->function = $function;
    }

    /**
     * Execute previously loaded function using parameters parsed from the request data.
     * @return void
     */
    protected function execute() {
        // validate params, this also sorts the params properly, we need the correct order in the next part
1516
        ksort($this->parameters);
1517 1518 1519
        $params = call_user_func(array($this->function->classname, 'validate_parameters'), $this->function->parameters_desc, $this->parameters);

        // execute - yay!
1520
        log_debug('executing: ' . $this->function->classname . "/" . $this->function->methodname);
1521 1522 1523 1524 1525 1526 1527 1528 1529
        $this->returns = call_user_func_array(array($this->function->classname, $this->function->methodname), array_values($params));
    }
}

/**
 * Delete all service and external functions information defined in the specified component.
 * @param string $component name of component (mahara, local, etc.)
 * @return void
 */
1530
function external_delete_descriptions($component) {
1531 1532 1533 1534 1535 1536

    $params = array($component);

    delete_records_select('external_services_users', "externalserviceid IN (SELECT id FROM {external_services} WHERE component = ?)", $params);
    delete_records_select('external_tokens', "externalserviceid IN (SELECT id FROM {external_services} WHERE component = ?)", $params);
    delete_records_select('oauth_server_token', "osr_id_ref IN (SELECT id FROM {oauth_server_registry} WHERE externalserviceid IN (SELECT id FROM {external_services} WHERE component = ?))", $params);
1537
    delete_records_select('oauth_server_config', "oauthserverregistryid IN (SELECT id FROM {oauth_server_registry} WHERE externalserviceid IN (SELECT id FROM {external_services} WHERE component = ?))", $params);
1538
    delete_records_select('oauth_server_registry', "externalserviceid IN (SELECT id FROM {external_services} WHERE component = ?)", $params);
1539 1540 1541 1542 1543 1544
    delete_records_select(
        'external_services_functions',
        "externalserviceid IN (SELECT id FROM {external_services} WHERE component = ?)"
            . " OR functionname IN (SELECT name FROM {external_functions} WHERE component = ?)",
        array($component, $component)
    );
1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566
    delete_records('external_services', 'component', $component);
    delete_records('external_functions', 'component', $component);
}

/**
 * The web services cron callback
 * clean out the old records that are N seconds old
 */
function webservice_clean_webservice_logs() {
    $LOG_AGE = 8 * 24 * 60 * 60; // 8 days
    delete_records_select('external_services_logs', 'timelogged < ?', array(time() - $LOG_AGE));
}

/**
 * Reload the webservice descriptions for all plugins
 *
 * @return bool true = success
 */

function external_reload_webservices() {

    // first - prune all components that are nolonger available/installed
1567 1568 1569 1570 1571 1572 1573 1574 1575 1576
    $dead_components = get_records_sql_array(
        'SELECT DISTINCT component AS component
        FROM {external_functions}
        WHERE
            component != \'\'
            AND component NOT IN ('.
                implode(', ', array_fill(1, count(get_ws_subsystems()), '?'))
        .')',
        get_ws_subsystems()
    );
1577 1578
    if ($dead_components) {
        foreach ($dead_components as $component) {
1579
            external_delete_descriptions($component->component);
1580 1581 1582
        }
    }
    foreach (get_ws_subsystems() as $component) {
1583
        external_reload_component($component);
1584 1585 1586 1587 1588 1589
    }

    return true;
}

/**
1590 1591 1592
 * Utility function to load up the $services and $functions arrays
 * from the services.php file for the specified component. (Calling it
 * from its own function in order to avoid polluting the namespace.)
1593 1594
 *
 * @param string $component
1595
 * @return array [$services, $functions]
1596
 */
1597
function webservice_load_services_file($component) {
1598

1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620
    $wsdir = webservice_component_ws_directory(
        $component,
        $plugintype,
        $pluginname
    );

    if ($plugintype && $pluginname) {
        // Standard plugin; can use safe_require
        $file = safe_require(
            $plugintype,
            $pluginname,
            WEBSERVICE_DIRECTORY . '/services.php',
            'include',
            true,
            array('services', 'functions')
        );
        $services = $file['services'];
        $functions = $file['functions'];
    }
    else {
        // Not a plugin, must handle manually
        $filepath = get_config('docroot') . $wsdir . '/services.php';
1621 1622
        if (file_exists($filepath)) {
            include($filepath);
1623 1624
        }
    }
1625

1626 1627
    if (empty($services)) {
        $services = array();
1628
    }
1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645
    if (empty($functions)) {
        $functions = array();
    }
    return array(
        'services' => $services,
        'functions' => $functions
    );
}

/**
 * Reload the webservice descriptions for a single plugins
 *
 * @param string $component ("webservice", "local", or a plugin e.g.
 * "artefact/internal".
 * @return bool Whether or not we found webservices for this component
 */
function external_reload_component($component) {
1646

1647 1648 1649 1650 1651 1652 1653 1654
    // Load arrays $services and $functions from the plugin or component's
    // {path_to_plugin}/webservice/services.php file.
    $result = webservice_load_services_file($component);
    $services = $result['services'];
    $functions = $result['functions'];

    // Does the component have a valid services.php file?
    if (!$services && !$functions) {
1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670
        external_delete_descriptions($component);
        return false;
    }

    // update all function first
    $dbfunctions = get_records_array('external_functions', 'component', $component);
    if (!empty($dbfunctions)) {
        foreach ($dbfunctions as $dbfunction) {
            if (empty($functions[$dbfunction->name])) {
                // the functions is nolonger available for use
                delete_records('external_services_functions', 'functionname', $dbfunction->name);
                delete_records('external_functions', 'id', $dbfunction->id);
                continue;
            }
            $function = $functions[$dbfunction->name];
            unset($functions[$dbfunction->name]);
1671 1672 1673 1674 1675 1676 1677 1678 1679
            // Fill in default classpath
            if (empty($function['classpath'])) {
                if ($component === WEBSERVICE_DIRECTORY) {
                    $function['classpath'] = WEBSERVICE_DIRECTORY;
                }
                else {
                    $function['classpath'] = $component . '/' . WEBSERVICE_DIRECTORY;
                }
            }
1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701