Latest revision as of 07:18, 18 January 2011

Moodle 2.0

This document explains how an administrator can set up a web service for one external system. One token will be generated during this setup. The external system administrator will enter the token into the external system. The external system users do not need to enter any personal security key.

First steps

Enable web service feature
Enable a protocol
Enable the web service function documentation
Create a service however you must check Authorised users only
Add functions to the service

Create a user for the external system

  Settings block > Site Administration > Users > Accounts > Add a new user

  Complete the fields and select Update profile operation

Authorise the user

 Settings block > Site Administration > Plugins > Web services > External Services
 Select Authorised users link
 Select the created user and click Add

As you can see in the second screen capture, Moodle indicates if some capabilities need to be assigned to an authorised user. Moreover if you click on the authorised user you can setup some specific options: IP restriction and Valid until.

.

Create a token

 Settings block > Site Administration > Plugins > Web services > Manage tokens
 Click on Add
 Select the created user and service
 Click on Saves changes

Enable capabilities for the user

The last step, and the trickiest, is to grant the right permission to the external system user. It would need the following capabilities:

"webservice/rest:use, webservice/soap:use, webservice/xmlrpc:use, webservice/amf:use" matching the enabled protocols.
the required capabilities by the web service functions. These required capabilities are listed when you add a function to the service.

As you previously created a token for the external system user, you do not need to assign "moodle/webservice:createtoken" to it. For more information about roles and capabilities, read the Manage roles documentation.

The external system administrator can connect into Moodle and see the token into his/her security keys page. Or you can directly tell him is token if you don't want to communicate his/her web login/password (in this case think to give him/her a copy of the web service function documentation located on his/her security keys page).

@@ Line 1: / Line 1: @@
 {{Moodle_2.0}}
-This document explains how an administrator can set up a web service that an external system can access.
+This document explains how an administrator can set up a web service for one external system. One token will be generated during this setup. The external system administrator will enter the token into the external system. The external system users do not need to enter any personal security key.
-=A brief note about custom web services=
+== First steps ==
+# [https://docs.moodle.org/en/How_to_enable_web_services_for_ordinary_users#Enable_web_service_feature Enable web service feature]
+# [https://docs.moodle.org/en/How_to_enable_web_services_for_ordinary_users#Enable_a_protocol Enable a protocol]
+# [https://docs.moodle.org/en/How_to_enable_web_services_for_ordinary_users#Enable_the_web_service_function_documentation Enable the web service function documentation]
+# [https://docs.moodle.org/en/How_to_enable_web_services_for_ordinary_users#Create_a_service Create a service] '''however you must check''' ''Authorised users only''
+# [https://docs.moodle.org/en/How_to_enable_web_services_for_ordinary_users#Add_functions_to_the_service Add functions to the service]
-There is no such thing as a default web service in Moodle, so anyone looking for one (or for a list of available services) may get rather confused. Instead, '''you must create a custom service.'''
+== Create a user for the external system ==
-Creating a custom service does not mean you are really creating an entirely new web service yourself. You don't have to program anything. Instead, a 'custom web service' just lets you select which of the standard web service functions are available via that service.
-This allows you to enable only the specific functions that you need to expose, therefore increasing security. The procedure is included below.
-=Token authentication method=
-There is two way for the an external service to authenticate on Moodle. Either with a security key (also call token), either with a username/password. In this chapter we explain how a Moodle administrator set up web service for an external system with a security key.
-== Enable the web service in Moodle ==
-   Settings block > Site Administration > Advanced features<br/>
-   Check '''Enable web services''' option and '''Save Changes'''
-[[Image:enable_ws_option.png|800px]]
-== Enable a protocol ==
-   Settings block > Site Administration > Plugins > Web services > Manage protocols<br/>
-   Enable the desired protocol (SOAP, REST, XMLRPC, AMF, ...)
-[[Image:ws_manageprotocal_settings.png|800px]]
-== Create a new user ==
     Settings block > Site Administration > Users > Accounts > Add a new user<br/>
-    Complete the other fields and select '''Update profil''' operation
+    Complete the fields and select '''Update profile''' operation
-== Enable capabilities to specific user==
+== Authorise the user==
-=== for protocols ===
+[[Image:Authorised users link.jpg|thumb]] [[Image:Authorised user selection page.jpg|thumb]]
-you need to set the activated protocol (webservice/rest:use, webservice/soap:use,...) capability to the specific user.
+  Settings block > Site Administration > Plugins > Web services > External Services
+  Select '''Authorised users''' link
+  Select the created user and click '''Add'''
-== Create a service with funtions ==
-   Settings block > Site Administration > Plugins > Web services > External Services
+As you can see in the second screen capture, Moodle indicates if some capabilities need to be assigned to an authorised user. Moreover if you click on the authorised user you can setup some specific options: IP restriction and Valid until.
-   Click on '''Add''' new custom service
-[[Image:externlservices_settings.png|800px]]
-===Add new custom service page===
-A service is a group of web service functions. By default any user using the web service authentication method will be able to call a service. To restrict a service to some user you need to select the '''Authorized users''' option.
-   Enter a name, check enable
-   Checked authorized users
-   Click on Save changes
-=== Select authorized user===
-===Add a function to the service ===
-   Settings block > Site Administration > Plugins > Web services > External Services<br/>
-   Click on the Functions link for the newly created service
-===Service functions page===
-   Select Add function operation, then select a function and Save changes
-[[Image:wsfunctionadmin.png|800px]]
-[[Image:selectservicefunction.png|800px]]
+.
-== Admin create token for specific user==
+== Create a token  ==
-=== create a token for a user ===
+[[Image:Create_token.jpg|thumb]]
+  Settings block > Site Administration > Plugins > Web services > Manage tokens
+  Click on '''Add'''
+  Select the created user and service
+  Click on '''Saves changes'''
-=== give the token to the user ===
+== Enable capabilities for the user==
-The client can connect into Moodle and see the token into his "security keys" page.
+The last step, and the trickiest, is to grant the right permission to the external system user. It would need the following capabilities:
+* "''webservice/rest:use'', ''webservice/soap:use'', ''webservice/xmlrpc:use'', ''webservice/amf:use''" matching the enabled protocols.
+* the required capabilities by the web service functions. These required capabilities are listed when you add a function to the service.
+As you previously created a token for the external system user, you do not need to assign "''moodle/webservice:createtoken''" to it.
+For more information about roles and capabilities, read the [https://docs.moodle.org/en/Manage_roles Manage roles] documentation.
-= Variant: simple authentication method =
-This authentication method is a little different from the token one. The client send his username/password instead of a token. All steps are similar except that the administrator doesn't need to create any token and need to process the following steps:
-== Enable the web service authentication plugin ==
+[[Image:The token.jpg|thumb]]The external system administrator can connect into Moodle and see the token into his/her [https://docs.moodle.org/en/How_to_get_a_security_key security keys] page. Or you can directly tell him is token if you don't want to communicate his/her web login/password (in this case think to give him/her a copy of the web service function documentation located on his/her [https://docs.moodle.org/en/How_to_get_a_security_key security keys] page).
-   Settings block > Site Administration > Plugins > Authentication > Manage authentication<br/>
-   Enable '''Web services'''
-[[Image:ws_manageauth_settings.png|800px]]
-== Create a new user ==
-this steps is little bit different from the one in the token authentication.
-   Settings block > Site Administration > Users > Accounts > Add a new user<br/>
-   Select '''Web services''' option for '''Choose an authentication method'''.
-   This user will not be able to log into the site but can access web service.
-   Complete the other fields and select '''Update profil''' operation
-[[Image:ws_authentication_settings.png|800px]]
+= See also=
+* [https://docs.moodle.org/en/Web_Services Web services]
+* [[How to enable web services for ordinary users]]
 [[Category:Web Services]]

Documentation

How to enable web services for an external system: Difference between revisions