MNet services

This page lists the services (and methods in that service) that are available to MNet clients. Services are MNet's way of grouping methods, and allowing MNet sites to publish and/or subscribe to services. The descriptions are not complete. Please help fill it out!

System

Implemented in /mnet/xmlrpc/server.php, this provides basic information about the MNet server. These methods may also be called as "system.*" in addition to the "system/*" pattern common to the other method names. The system/listMethods, system/methodSignature, and system/methodHelp methods are based on XML-RPC Introspection.

This service is not returned by system/listServices, nor are any of the methods listed by the XML-RPC Introspection methods.

system/listMethods

Lists the available methods.

Parameters

• service name(string) (optional): If provided, list only the methods provided by the given service. If not specified, list all available methods. (This parameter is not present in XML-RPC Introspection.)

Return value

• array of strings, giving the method names

Security

Only lists methods that the client is allowed to execute.

system/methodSignature

Gives the method signature of the requested method.

Parameters

• method name(string): The name of the method to provide the method signature for.

Return value

• array, giving the method signature(s). Note: the format is different from the one specified in the XML-RPC Introspection spec.
  • Each array element is itself an array
    • Each array element is a struct, with fields "type" and "description", and values being strings.
    • The first array element represents the return value. Subsequent array elements represent the parameters.

Security

If the client is not allowed to execute the method, returns an empty array.

system/methodHelp

Give a textual description of the requested method.

Parameters

• method name(string): The name of the method to provide help for.

Return value

• string, a description of the method.

Security

If the client is not allowed to execute the method, returns server fault 7019.

system/listServices

List the available services.

Parameters

none

Return value

• array, giving the service names, versions, and publish/subscription status. Each array element is a struct with the following keys:
  • name(string): the name of the service
  • apiversion(integer): the API version provided
  • publish(integer): whether the server is publishing this service to the client
  • subscribe(integer): whether the server is subscribing to this service from the client

Security

Only services that are published or subscribed are returned.

system/keySwap

Swap public keys via X509 certificates.

Parameters

• wwwroot(string): the client's wwwroot.
• certificate(string): the client's X509 certificate, in PEM format
• application(string): the application type

Return value

• (string) the server's X509 certificate, in PEM format

Security

This is the only MNet method that can be called from all hosts without encryption and signing (since that is the only way to bootstrap the process).

You really shouldn't be trusting the client's parameters, as these can be easily forged. If the certificate differs from the certificate you have stored for the given wwwroot, you should double-check by doing your own system/keySwap call, or trying to send an encrypted and signed XML-RPC request to the client. In this way, a successful attack would require at least DNS hijacking and/or a man-in-the-middle attack, both of which break MNet's security anyways.

sso_idp (version 1)

Identity provider for single sign on.

auth/mnet/auth.php/user_authorise

(note UK spelling of "authorise") Return user data for the provided token, compare with user_agent string.

Parameters

• token(string): token provided by the IdP
• user agent(string): SHA-1 hash of the user's user agent string

Return value

• struct, containing the user's profile data. The fields provided are: username, email, auth (="mnet"), confirmed, deleted, firstname, lastname, city, country, lang, timezone, description, mailformat, maildigest, maildisplay, htmleditor, wwwroot (the IdP's wwwroot), session.gc_maxlifetime, picture (integer/boolean), imagehash (if picture != 0; sha1 hash of profile picture file), myhosts (an array describing how many courses the user is enrolled in, in all known hosts)

auth/mnet/auth.php/keepalive_server

"Receives an array of usernames from a remote machine and prods their sessions to keep them alive"

Parameters

• array of usernames

Return value

• struct:
  • if success:
    • code (int): 0
    • message (string): "All ok"
    • last_log_id (int): the ID of the last log entry received from auth/mnet/auth.php/refresh_log
  • if error:
    • • code (int): 1
      • message (string): "We failed to refresh the session for the following usernames: ..."
      • last_log_id (int): the ID of the last log entry received from auth/mnet/auth.php/refresh_log

auth/mnet/auth.php/kill_children

"The IdP uses this function to kill child sessions on other hosts"

never seems to be called by Moodle networks (called on logout instead)

auth/mnet/auth.php/fetch_user_image

"Returns the user's image as a base64 encoded string."

Parameters

• username (string)

Return value

• false on error, otherwise struct:
  • f1 (string): base64 encoded copy of user's f1.jpg
  • f2 (string): base64 encoded copy of user's f2.jpg

auth/mnet/auth.php/fetch_theme_info

"Returns the theme information and logo url as strings."

Parameters

none

Return value

• struct:
  • themename (string)
  • logourl (string): Url for theme logo
  • auth/mnet/auth.php/update_enrolments

sso_sp (version 1)

Service provider for single sign on.

auth/mnet/auth.php/keepalive_client

"Poll the IdP server to let it know that a user it has authenticated is still online" No, I don't know what that means either.

never seems to be called by Moodle networks (called by cron instead) calls auth/mnet/auth.php/keepalive_server on each IdP that has local users logged in

Parameters

none

Return Value

none

auth/mnet/auth.php/kill_child

Requests that the SP ends the user's session. Used for single sign off.

Parameters

• username(string)
• useragent(string): SHA-1 hash of the user's user agent string

Note that the calling IdP is identified through MNet signatures

Return Value

• true on success (boolean)

mnet_enrol (version 1)

Moodle networks enrolments. Enable remote administrators to enrol users in local courses.