.. include:: /shortcuts.rstext .. index:: pair: Administration; Web services single: Site administrator; Web services .. _webservices: Web services ------------------------------------------- *Administration → Extensions → Web services* .. note:: *Web services* are only accessible by site administrators. Web services allow you to connect your Mahara site with other applications that have web services / APIs as well. It might require some configuration or the development of specific web services functions to accomplish the integration you are looking for. The Mahara web services are a framework that makes it possible to develop additional APIs without having to do a great deal more than defining a function that exposes the required functionality, and the associated interface definition. In order to use web services, your site must use a SSL certificate. .. index:: single: Web services; Configuration .. _webservices_config: Configuration ~~~~~~~~~~~~~~~~~~~~~~ *Administration → Extensions → Web services → Configuration* On this page you set up various web services rules and enable or disable them. .. index:: single: Web services configuration; Master switch single: Web services configuration; Switching individual protocols on and off Web services master switch and switching protocols on and off ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can enable web services globally and then configure protocols individually to suit your needs. Once a protocol is enabled, it can be used for all functions, users and tokens. .. figure:: /images/administration/web_services/switch_on_off.* :alt: Switch web services and individual protocols on and off Switch web services and individual protocols on and off #. **Use web services**: If set to "Yes", web services are available to be used on your site. .. note:: If you set the master switch to "No", any activated individual protocols under "Protocol" are turned off and would need to be enabled manually again when you switch web services on again. #. **SOAP**: Allow this protocol if you want to be able to use the Simple Object Access Protocol. #. **XML-RPC**: Set this to "Yes" if you want to make remote procedure calls to XML content. This protocol is used by MNet. .. note:: As long as MNet is supported in Mahara, you can use that to :ref:`configure your connection to Moodle `. #. **REST**: Allow the REpresentational State Transfer protocol by switching this setting to "Yes". The REST interface also supports JSON authentication. #. **OAuth**: If you want to use the OAuth (Open Authentication) protocol, switch this setting to "Yes". .. index:: single: Web services configuration; Networking certificates Networking certificates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this section, the public key of your Mahara certicate that is created on *Administration → Configure site → Networking* is displayed for convenience. .. _manage_service_groups: .. index:: single: Web services configuration; Manage service groups Manage service groups ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Service groups are the units of allocation of access to a user (simple authentication) or user tokens. They are a collection of functions. Mahara already comes with a series of service groups and functions that you can configure. More service groups can be added. .. figure:: /images/administration/web_services/manage_service_groups.* :alt: Overview of the available service groups and their basic settings Overview of the available service groups and their basic settings #. **Service**: The service group under which a number of related functions are grouped that you can enable or disable. #. **Component**: The area through which a service group is available. It is generally "webservice". #. **Enabled**: If a service group is enabled, you see the *Enabled* icon |enabled|. If it is not enabled, you see the *Disabled* icon |disabled|. #. **Authorised users only**: If the service group can be used by people who log in with a username and password, you see the *Enabled* icon |enabled|. If it is not possible to use it as such a user, you see the *Disabled* icon |disabled|. #. **User token access**: You see the *Enabled* icon |enabled| if access to the functions of this group requires a user token. If access via a user token is not allowed, you see the *Disabled* icon |disabled|. #. **Functions**: This is a list of functions that are associated with the service group. .. note:: Clicking on one of the functions takes you to the web services documentation for this function. More information about the web service function is available there including a description of the functions API, input and output parameters, and error handling. #. Click the *Edit* button |edit| to make changes to the service group as described below. #. Click the *Delete* button |delete| to completely remove the service group. .. note:: In many cases you may not want to delete the web service group entirely as you would need to re-create it and associate functions with it if you required it at a later stage. Disabling the group would often be sufficient. #. If you want to create a new service group, add it in this field and click the *Add* button. You can then see your new group in the list of service groups and configure it by clicking the *Edit* button |edit| next to it. When you selected the service group you want to edit, you see the following screen. .. figure:: /images/administration/web_services/service_group_edit.* :alt: Edit the settings of a service group Edit the settings of a service group #. Name of the service group #. **Service**: Set this switch to "Yes" if you want to use this service group. You can tweak the individual functions below. #. **Authorised users only**: Set this switch to "Yes" if only people with a username and password should be affected by this service group. #. **User token access**: Set this switch to "Yes" if you want users to have individual tokens in order to access certain functionalities. .. note:: The user token access gives the enitre Mahara userbase the possibility to make use of the API. Therfore generally, it should be restricted to service groups that give access to user-focused functions like mahara_user_get_my_user for the current user's own details. #. The name of the function. #. **Enabled**: This setting enables or disables the use of this function. #. **Class name**: The name of the class that is part of the function. #. **Method name**: The name of the method that is being called. The link takes you to the web services documentation for that method. #. Click the *Save* button when you are finished making your changes, or click *Back* if you want to cancel the changes. .. index:: single: Web services configuration; Manage service access tokens Manage service access tokens ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can generate access tokens for individual users and associate service groups to which that user shall have access. .. figure:: /images/administration/web_services/manage_service_access_tokens.* :alt: Overview of the access tokens Overview of the access tokens #. **Token**: The token that was generated for a particular user. #. **Institution**: Lists the institution in which the user is a member. #. **User**: The username is displayed and linked to the user's settings page in the administration. #. **Service**: The service group for which the token was generated. #. **Enabled**: If this service group is enabled, you see the *Enabled* icon |enabled|. If it is not enabled, you see the *Disabled* icon |disabled|. #. **Web services security**: If web services security is enabled, you see the *Enabled* icon |enabled|. Otherwise, you see the *Disabled* icon |disabled|. #. **Functions**: This is a list of all the functions that the token has access to for the selected service. #. Click the *Edit* button |edit| to make changes to the settings. #. Click the *Delete* button |delete| to remove the token. #. **Username**: Type a username of a user for whom you wish to add a token. You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type. #. Click the *Generate token* button for a new access token to be created for that user. You are taken to a screen where you can associate a service group to this token (see below). You can only enter one username. When you create a token for a user, you need to provide some additional information. .. figure:: /images/administration/web_services/service_access_tokens_config.* :alt: Configure a service access token Configure a service access token #. Verify that you are editing the correct token. #. **Institution**: Select the institution of the user. #. **Username**: Verify that you have the correct username for which you want to set up a token. The username is linked to the user's settings page in the administration. #. **Service**: Choose the service group from the drop-down list for which you want to enable the token. Only services that allow user token access can be chosen. #. **Enabled**: The token is automatically enabled when the service group is enabled. .. note:: If you want to disable a service group, please do so in the section :ref:`Manage service groups `. #. **Authorised users only**: This checkbox is not used in this context because here you create a token. #. **Functions**: A list of functions that the token has access to. .. note:: When you change the service, the list of functions is not automatically updated. You only see the updated list when you save the page. #. **Enable web services security (XML-RPC only)**: This feature is only available for XML-RPC based authentication. #. **Public key**: Enter the public key for added web service security (only for XML-RPC based authentication). #. **Public key expires**: Date on which the public key that you entered expires. The date is only updated once you save the form. #. Click the *Save* button when you are finished making your changes, or click *Back* if you want to cancel the changes. .. index:: single: Web services configuration; Manage service users Manage service users ^^^^^^^^^^^^^^^^^^^^^^^^^^ If you do not wish to use a token for your users, but give them access to functions via their usernames, you should choose this option. Users must: * only be configured once. * have the "webservice" authentication method in an institution in which they are a member. .. note:: Users with the authentication method "webservice" can only access Mahara via web services and cannot use the standard login form. .. figure:: /images/administration/web_services/manage_service_users.* :alt: Manage service users overview section Manage service users overview section #. **User**: The username is displayed of the user for whom you configured a service group. It is linked to the user's :ref:`account settings page ` in the administration. #. **Institution**: Lists the institution in which the user is a member. #. **Service**: The service group that is associated with the user. #. **Enabled**: If this service group is enabled, you see the *Enabled* icon |enabled|. If it is not enabled, you see the *Disabled* icon |disabled|. #. **Web services security**: If web services security is enabled, you see the *Enabled* icon |enabled|. Otherwise, you see the *Disabled* icon |disabled|. #. **Functions**: This is a list of all the functions that the user has access to for the selected service. #. Click the *Edit* button |edit| to make changes to the settings. #. Click the *Delete* button |delete| to remove the user from the access to the associated service group. #. **Username**: Type a username of a user for whom you wish to manage the services. You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type. The user must have web services as authentication method. #. Click the *Generate token* button for a new access token to be created for that user. You are taken to a screen where you can associate a service group to this token (see below). You can only enter one username. When you add a user, you need to provide some additional information. .. figure:: /images/administration/web_services/manage_service_users_config.* :alt: Associate a user with a specific service group Associate a user with a specific service group #. **Service owner**: The username is displayed. It must match the username below. #. **Institution**: Verify that the institution of the user is correct. If it is not, you can change the institution on the user's :ref:`account settings page `. #. **Username**: Verify that you have the correct username for which you want to set up a token. #. **Service**: Choose the service group from the drop-down menu to which you want to give the user access. Only services that allow access via a username can be chosen. #. **Enabled**: The settings are automatically enabled when the service group is enabled. .. note:: If you want to disable a service group, please do so in the section :ref:`Manage service groups `. #. **Authorised users only**: This checkbox is selected automatically when the service group is configured to allow access via a username. #. **Functions**: A list of functions that the user has access to. .. note:: When you change the service, the list of functions is not automatically updated. You only see the updated list when you save the page. #. **Enable web services security (XML-RPC only)**: This feature is only available for XML-RPC based authentication. #. **Public key**: Enter the public key for added web service security (only for XML-RPC based authentication). #. **Public key expires**: Date on which the public key that you entered expires. The date is only updated once you save the form. #. Click the *Save* button when you are finished making your changes, or click *Back* if you want to cancel the changes. .. index:: single: Web services; OAuth service registration OAuth service registration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Administration → Extensions → Web services → OAuth* OAuth service access is configured separately. This enables the selection of an institution and service definition, for which a consumer key and secret will be generated automatically. .. figure:: /images/administration/web_services/oauth_service_registration.* :alt: Register an OAuth service Register an OAuth service #. **Application**: Lists the applications that are connected via OAuth. #. **Owner**: User who has set up the OAuth service. #. **Consumer key**: The consumer key for the OAuth service. #. **Consumer secret**: The consumer secret for the OAuth service. #. **Enabled**: If the application is enabled, you see the *Enabled* icon |enabled|. If it is not enabled, you see the *Disabled* icon |disabled|. #. **Callback URI**: The callback URI for the application. #. Click the *Edit* button |edit| to make changes to the settings. #. Click the *Delete* button |delete| to remove the application so it cannot connect anymore to Mahara via OAuth. #. **Application**: Give your application that you want to add a name. #. Choose which institution shall have access to your chosen application via OAuth. #. Choose the service group that you want to associate with this application. #. Click the *Add* button to create the OAuth authentication for the seleced service. You are taken to a screen where you can configure your application (see below). When you want an application to connect via OAuth to Mahara, you need to provide some more information. .. figure:: /images/administration/web_services/oauth_service_registration_configuration.* :alt: Configure an OAuth service Configure an OAuth service #. **Server key**: The consumer key for the OAuth service. #. **Consumer secret**: The consumer secret for the OAuth service. #. **Application title**: Give your application that you want to add a name. #. **Service owner**: User who has set up the OAuth service. #. **Appliation URI**: URI of the application. #. **Callback URI**: The callback URI for the application. #. **Institution**: Select the institution for which you want to set up OAuth. #. **Service**: Select the service group that you want to set up for OAuth. #. **Enabled**: The application is automatically enabled when OAuth is enabled. #. **Functions**: A list of functions that the application has access to. .. note:: When you change the service, the list of functions is not updated automatically. You only see the updated list when you save the page. #. Click the *Save* button when you are finished making your changes, or click *Back* if you want to cancel the changes. .. index:: single: Web services; Web services logs Web services logs ~~~~~~~~~~~~~~~~~~~~~~~ *Administration → Extensions → Web services → Web services logs* You can view the logs from the web services and narrow you search so you only see the relevant information. .. figure:: /images/administration/web_services/web_services_logs.* :alt: Search the web services logs Search the web services logs #. **User**: Type the username of the person for whom you want to see the logs. You can only enter one username. You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type. #. **Protocol**: Select the web services protocol that is associated with the user. You can only see the protocols that are enabled. #. **Auth type**: Choose the type of authentication that you selected for the user. The options are: * **All**: Display the logs for any authentication type. * **Token**: Only display logs when the user has a user token. * **User**: Display the logs when the user uses the username for the web service. * **OAuth**: Select this option if you only want to see logs when the user logs in via OAuth. #. **Function**: Search for the function that you are interested in. #. **Only errors**: Tick this checkbox if you only want to see log information that contains an error. #. Click the *Go* button to start your search. If there are any results for your search, you will see them in the **Results** area. .. figure:: /images/administration/web_services/web_services_logs_results.* :alt: Results for the search of the web services logs Results for the search of the web services logs #. **User**: Display the username of the user for which there is a log entry. #. **Institution**: Display the name of the institution in which the user is a member. #. **Protocol**: Show the protocol that is associated with the user for the chosen context. #. **Authentication type**: Show the authentication type that is associated with the user. #. **Function**: Display the function for which there is a log entry. #. **Time taken**: The time it took to fetch the log entry. #. **When**: Display the date that the log entry was produced. #. You can change the sort order for any column by clicking its column title. #. **Info**: Error messages are displayed here. .. index:: single: Web services; Web services test client Web services test client ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Administration → Extensions → Web services → Web services test client* The test client gives you the opportunity to test your settings. Please beware that the functions are executed on the system and not a separate test instance. .. figure:: /images/administration/web_services/web_services_test_client.* :alt: Web services test client Web services test client .. note:: When you start the configuration, you only see the protocol and the authentication type if you only have one protocol selected. The other fields are revealed once you made a decision on what to test. #. **Protocol**: You only see the web services protocols that are currently enabled. If you see more than one, select the one that you want to test. #. **Authentication type**: Select the authentication type that you would like to include in your test. Click the *Next* button to see the following option. #. **Service**: Choose the service group that you want to test. Click the *Next* button to see the following option. #. **Functions**: Select the function that you want to include in your test. Click the *Next* button to see the following option. #. **wstoken**: Enter the web services token for the user that you want to test. .. note:: If you selected "User" for the authentication type, you'll also see a field **wspassword** that you can fill in. #. Click the *Execute* button if you want to run the test, or click *Cancel* if you want to abort the test. Once the test has run, the results of the test are displayed on the screen. .. index:: single: Web services; Application connections Application connections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Administration → Extensions → Web services → Application connections* This is an overview page of all the connections that you have allowed either via personal user tokens or OAuth access tokens. .. figure:: /images/administration/web_services/application_connections.* :alt: Overview of the application connections Overview of the application connections #. The section *Personal user tokens* displays all the tokens that you have generated for individual users and whether they have been accessed or not amongst others. #. **Service access**: This column displays the service group for which you created a token. #. **Enabled**: If the service group is enabled, you see the *Enabled* icon |enabled|. If it is not enabled, you see the *Disabled* icon |disabled|. #. **Token**: The token is displayed here. #. **Functions**: The functions that are part of the service group are listed and linked. The links go to the web services documentation for the function that you selected. #. **Last access**: List the date and time of the last use of the token. #. **Expires**: Show the expiry date of the token. #. Click the *Generate* button to generate a new random token. #. Click the *Delete* button |delete| to delete the token. The user group and functions are still available. You can then click the *Generate* button to create a new token. .. note:: The *Delete* button is only available when a token was generated. #. In the *OAuth access tokens* section you see any tokens generated to be used with OAuth.