Difference between revisions of "Using web services"

Jump to: navigation, search

Note: You are currently viewing documentation for Moodle 2.2. Up-to-date documentation for the latest stable version is available here: Using web services.

(Enable capabilities to users)
 
(33 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Moodle_2.0}}This document explains how an administrator set up a web service for ordinary users. It is useful if you want many user to access a service. All user will have a specific and unique security key (also known as "token") to access the service. They generally enter their own security keys into an external application.
+
{{Web services}}
 +
This document explains how an administrator can set up a web service for users to access a service. Each user will have a specific and unique security key (also known as a "token") to access the service.
  
= Enable web service feature =
+
== Enabling web services==
[[Image:Enable_web_service.jpg|thumb]]For security reasons, web services should only be enabled if you intend to make use of it.
+
[[Image:Enable_web_service.jpg|thumb|Enabling web services]]
  Settings block > Site Administration > Advanced features<br/>
+
# Access ''Settings > Site administration > Advanced features''
  Check '''Enable web services''' option and '''Save Changes'''
+
# Check 'Enable web services' then click 'Save Changes'
  
= Enable a protocol =
+
Note: For security reasons, web services should only be enabled if you intend to make use of it.
[[Image:Enable_protocol.jpg|thumb]]
 
In this step you will enable some web service protocols. Usually external applications that users wish to use should dictate which protocols are enabled.  
 
  
  Settings block > Site Administration > Plugins > Web services > Manage protocols<br/>
+
== Enabling protocols ==
  Enable the desired protocol (SOAP, REST, XMLRPC, AMF, ...)
+
[[Image:Enable_protocol.jpg|thumb|left|Enabling protocols]]
 +
Usually external applications that users wish to use dictate which protocols should be enabled.  
  
= Enable the web service function documentation =
+
# Access ''Settings > Site administration > Plugins > Web services > Manage protocols''
[[Image:Web services documentation.jpg|thumb]]
+
# Enable the protocols (SOAP, REST, XMLRPC, AMF, ...) as required
On the ''''Manage protocols'''' page you can also enable the web service function documentation. If this documentation is enabled, the user specific web service descriptions will be available to each user. This option is mainly useful to web service client developers.
 
  
 +
== Enabling web service function documentation ==
 +
[[Image:Security keys and documentation.jpg|thumb|Security keys page with documentation link]]
 +
Enabling web service function documentation (also on the Manage protocols page) results in user-specific web service documentation being available for each user on their [[Security keys]] page. This option is mainly useful to web service client developers. If nobody is creating a web service client, there is no need to enable this feature.
  
 +
== Creating a service ==
 +
If none of the pre-build web services match your needs, you can create a custom service i.e. select which of the standard web service functions are available via that service.
  
 +
You can enable only the specific functions that you need to expose, so not compromising on security.
 +
[[Image:Create a service.jpg|thumb|Creating a service|left]]
 +
# Access ''Settings > Site administration > Plugins > Web services > External services''
 +
# Click Add new custom service
 +
#* 'Authorised users only' - If enabled, you will need to select the authorised users manually. Otherwise all users with appropriate permissions are allowed
 +
#* 'Required capability' - If enabled, any user accessing the web service will be checked against this selected capability. (This is just an additional optional security layer.)
 +
# Enter a name and check Enabled
 +
# Click the button 'Add service'
  
.
+
==Adding functions to the service==
 +
[[Image:Select a web service function.jpg|thumb|Adding functions to the service]]Your service is currently empty and doesn't do anything. Web service functions need to be added. Your choice will be dictated by what you allow the external application to do. For this example, select 'Create group'.
  
= Create a service =
+
# Click 'Add functions' link
[[Image:Add external service.jpg|thumb]]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.'''
+
# Select 'create group' function and click the 'Add functions' button
  
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.
+
You should be back to the service functions list. 'Required capabilities' are indicated for each function. Users need the required capabilities to run a function. The function descriptions in the API Documentation can also give you more information about the required capabilities (''Settings > Site administration > Plugins > Web services > API Documentation'').
  
This allows you to enable only the specific functions that you need to expose, therefore increasing security.
+
==Enabling capabilities==
  Settings block > Site Administration > Plugins > Web services > External Services
 
  Click on '''Add''' new custom service
 
  
 +
The final step is to grant appropriate permissions. The following capabilities should be allowed:
  
[[Image:Create a service.jpg|thumb]]The ''Add a service'' page should be displayed.
+
* [[Capabilities/moodle/webservice:createtoken|moodle/webservice:createtoken]] - for allowing users to generate a security key
* "''Authorised users''": if enabled, you will need to select the authorised users manually. Otherwise all Moodle users are allowed, at the condition they have the [https://docs.moodle.org/en/How_to_enable_web_services_for_ordinary_users#Enable_capabilities_to_users right permissions]
+
* [[Capabilities/webservice/rest:use | webservice/rest:use]], [[Capabilities/webservice/soap:use | webservice/soap:use]], [[Capabilities/webservice/xmlrpc:use | webservice/xmlrpc:use]], [[Capabilities/webservice/amf:use | webservice/amf:use]] which match the enabled protocols.
* ''required capability'': if enabled, any user accessing the web service will be checked against this selected capability. It is just an additional and optional security layer for your own usage.
+
* The service ''Required capability'' if set (''Settings > Site administration > Plugins > Web services > Manage services >'''Edit''' link'').
 +
* The required capabilities for the web service functions. These required capabilities are listed when you add a function to the service. For more information about roles and capabilities, read the [[Manage roles]] documentation.
  
  Enter a ''name'' and check ''enable''
+
Once done, the web service should be set up. Users should be able to [[Security keys|obtain a personal security key]].
  Uncheck ''Authorised users'' and ''required capability''
 
  Click on '''Add service'''
 
  
= Add functions to the service =
+
= Alternative settings =  
[[Image:Add functions to the service.jpg|thumb]][[Image:Select a web service function.jpg|thumb]]At this moment your service is empty and doesn't do much. You want to add some web service function to it. Your choice will be dictated by what you allow the external application to do. For now you are going to select 'Create group' function for the only reason that it is the function used as example to [https://docs.moodle.org/en/Development:Creating_a_web_service_client create a web service client].
 
  
  Click '''Add functions''' link,
+
== Authorise only specific users==
  Select 'create group' function and click '''Add functions''' button
+
[[Image:Authorised users link.jpg|thumb]] [[Image:Authorised user selection page.jpg|thumb]]
 +
# ''Settings > Site Administration > Plugins > Web services > External Services''
 +
# Select '''Authorised users''' link (the service must have been set as '''Authorised users only''' in the '''Edit''' link)
 +
# Select some users and click '''Add'''
  
[[Image:Function added-1.jpg|thumb]]You should be back to the service function list. Next to each function you can see a 'Required capabilies' field. Users need these capabilities to run each function. However there is some exception. Sometimes a function use case could not require the entire capability list. The only way to be 100% sure is to read the web service function documentation (even though they are currently not indicated see MDL-XXX). Core developers try to keep capability names clear enough that it should straight forward for administrator to guess it right.
+
Moodle indicates if some capabilities need to be assigned to an authorised user. Moreover if you click on the authorised user fullname, you can set up some specific options: ''IP restriction'' and ''Valid until''.
  
 +
== Create a token  ==
 +
[[Image:Create_token.jpg|thumb]]
 +
This feature allows you to create a token for specific user. It can be useful if a user doesn't have the moodle/create:token capability. This is also the only way to create a token for an administrator. For security reason, tokens are not automatically generated in the administrator security  keys page.
  
 +
# ''Settings > Site Administration > Plugins > Web services > Manage tokens''
 +
# Click on '''Add'''
 +
# Select the created user and service
 +
# Click on '''Saves changes'''
  
 +
As you created a token for this user, you do not need to assign "''moodle/webservice:createtoken''" to him/her.
 +
Finally, note that, as for authorised users, you can also set ''IP restriction'' and ''Valid until'' on a token.
  
 +
== See also ==
 +
 +
*[http://www.joomdle.com/wiki/Preparing_Moodle_20#Setting_up_Moodle_Web_services Joomdle documentation about setting Moodle web services]
  
 
+
[[de:Webservices nutzen]]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
.
 
 
 
= Enable capabilities to users=
 
The last step, and the trickiest, is to grant the right permission to the users. They would need the following capabilities:
 
* "''moodle/webservice:createtoken''" so the user can generate a security key.
 
* "''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.
 
For more information about roles and capabilities, read the [https://docs.moodle.org/en/Manage_roles Manage roles] documentation.
 
 
 
 
 
Once done, the web service should be set up. The user can [https://docs.moodle.org/en/How_to_get_a_security_key retrieve his/her personal security key] and copy it in an external application.
 
 
 
= See also=
 
* [https://docs.moodle.org/en/Web_Services Web services]
 
 
 
[[Category:Web Services]]
 

Latest revision as of 15:53, 13 June 2012

This document explains how an administrator can set up a web service for users to access a service. Each user will have a specific and unique security key (also known as a "token") to access the service.

Enabling web services

Enabling web services
  1. Access Settings > Site administration > Advanced features
  2. Check 'Enable web services' then click 'Save Changes'

Note: For security reasons, web services should only be enabled if you intend to make use of it.

Enabling protocols

Enabling protocols

Usually external applications that users wish to use dictate which protocols should be enabled.

  1. Access Settings > Site administration > Plugins > Web services > Manage protocols
  2. Enable the protocols (SOAP, REST, XMLRPC, AMF, ...) as required

Enabling web service function documentation

Security keys page with documentation link

Enabling web service function documentation (also on the Manage protocols page) results in user-specific web service documentation being available for each user on their Security keys page. This option is mainly useful to web service client developers. If nobody is creating a web service client, there is no need to enable this feature.

Creating a service

If none of the pre-build web services match your needs, you can create a custom service i.e. select which of the standard web service functions are available via that service.

You can enable only the specific functions that you need to expose, so not compromising on security.

Creating a service
  1. Access Settings > Site administration > Plugins > Web services > External services
  2. Click Add new custom service
    • 'Authorised users only' - If enabled, you will need to select the authorised users manually. Otherwise all users with appropriate permissions are allowed
    • 'Required capability' - If enabled, any user accessing the web service will be checked against this selected capability. (This is just an additional optional security layer.)
  3. Enter a name and check Enabled
  4. Click the button 'Add service'

Adding functions to the service

Adding functions to the service
Your service is currently empty and doesn't do anything. Web service functions need to be added. Your choice will be dictated by what you allow the external application to do. For this example, select 'Create group'.
  1. Click 'Add functions' link
  2. Select 'create group' function and click the 'Add functions' button

You should be back to the service functions list. 'Required capabilities' are indicated for each function. Users need the required capabilities to run a function. The function descriptions in the API Documentation can also give you more information about the required capabilities (Settings > Site administration > Plugins > Web services > API Documentation).

Enabling capabilities

The final step is to grant appropriate permissions. The following capabilities should be allowed:

Once done, the web service should be set up. Users should be able to obtain a personal security key.

Alternative settings

Authorise only specific users

Authorised users link.jpg
Authorised user selection page.jpg
  1. Settings > Site Administration > Plugins > Web services > External Services
  2. Select Authorised users link (the service must have been set as Authorised users only in the Edit link)
  3. Select some users and click Add

Moodle indicates if some capabilities need to be assigned to an authorised user. Moreover if you click on the authorised user fullname, you can set up some specific options: IP restriction and Valid until.

Create a token

Create token.jpg

This feature allows you to create a token for specific user. It can be useful if a user doesn't have the moodle/create:token capability. This is also the only way to create a token for an administrator. For security reason, tokens are not automatically generated in the administrator security keys page.

  1. Settings > Site Administration > Plugins > Web services > Manage tokens
  2. Click on Add
  3. Select the created user and service
  4. Click on Saves changes

As you created a token for this user, you do not need to assign "moodle/webservice:createtoken" to him/her. Finally, note that, as for authorised users, you can also set IP restriction and Valid until on a token.

See also