View source for Plugins/Artefact/WebServices/WebServicesConfiguration

=Web Services Configuration=

All [[Plugins/Artefact/WebServices| Web Services]] configuration hangs off the plugin administration page http://your.mahara.local.net/artefact/webservice/pluginconfig.php

The main page:

[[File:Webservices-config.png|border|Web Services main configuration page]]
<br/>

From here, you can carry out all the main administrative tasks:

* Globally activate/deactivate web services
* activate/deactivate individual protocols (REST, SOAP, XML-RPC)
* Create Services Groups of Functions that can be accessed
* Generate access tokens, and allocate users, and services groups
* Grant access to users for simple authentication access, and allocate service groups
* look up API descriptions for functions


== Global activation ==

Globally activate or deactivate all web service access for when you need to shut off access completely

[[File:Webservices-enable-services.png|border|Global activation/deactivation of all web services]]


== Activating Protocols ==

Individual protocols can be activated or deactivated.  Once activated, the protocol is available to all configured functions/users/tokens.

Available protocols are:
* SOAP
* REST (a basic HTTP and forms POST based interface)
* XML-RPC
* OAuth

[[File:Webservices-enable-protocols.png|border|activate and deactivate inidividual protocols]]

== Service Groups ==

Service groups are the unit of allocation of access to a user (simple auth) or user token.  They are a collection of functions.

[[File:Webservices-manage-service-groups.png|border|Web Services service groups]]


Give a service group a name, and then specify what functions are to be included.  You must also decide what form of authentication can access this service group - web service token, or user simple auth (user and password), and User Token authentication.  User Tokens are personal tokens that individual users can have access to - this enables all the widest possible Mahara user base to make use of the API, and should generally be restricted to Service Groups that give access to individual-user focused  functions like mahara_user_get_my_user for the current users own details.

From here, and individual service group can be deactivated for all users.

[[File:Webservices-service-group.png|border|edit service group]]

== Function API Descriptions ==

From the Service Group editing view(above), there is a link to each API function that will take you to a description of the functions API - input/output parameters, and error handling.

[[File:Webservices-group-delete-api.png|border|Web Services Group Delete API description]]

=Authentication=

There are currently two forms of authentication for web service access, which are available for all protocols:
* Web Service Tokens
* User/Password based simple authentication

In both cases, the authentication data is passed as query string parameters:
* Token - http://your.mahara.local.net/artefact/webservice/rest/server.php?wstoken=484dfea8715ed427b4d95796c3013f7d
* simple auth - http://your.mahara.local.net/artefact/webservice/rest/simpleserver.php?wsusername=blah3&wspassword=blahblah

Note: that the application changes for each - server.php vs simpleserver.php

There is one exception, for SOAP, where the user and password can be passed as part of the Web Services Security Extension SOAP headers (wsse), as plaintext username and password. eg:
 <env:Header>
   <wsse:Security env:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
     <wsse:UsernameToken>
       <wsse:Username>bean</wsse:Username>
       <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">blahblah</wsse:Password>
     </wsse:UsernameToken>
   </wsse:Security>
  </env:Header>



== Token Based Access Control ==

Each token is generated, and allocated to a user.  You then choose a service group that the given user is allowed to access with this token.  Only service groups that have been enabled for tokens can be selected.

[[File:Webservices-access-tokens.png|border|Web services generate an access token]]

== Personal User Token Based Access Control ==

Individual Users can have Personal Access Tokens.  These are a specific type of access token that enables access to a Service Group that has been enabled for User Token Access.
These appear in the same list under the users Settings page -&gt; Application connections.

The purpose of these tokens, and the Service Groups restricted to 'User Token' is to provide individuals access to API calls that are restricted to their own data.  For instance - a Service Group can be created 'User Token User Query' with the functions mahara_user_get_context, and mahara_user_get_my_user which enable a user to query their institution connection context (just the internal institution name), and their own user master details.

[[File:ApplicationConnections.png|border|Web services Application Connections]]

== Simple User Authentication Access Control ==

To configure a user for simple authentication access, choose a user, and then allocate a service group.  Only service groups that are enabled for simple user authentication can be used.

A selected user must have the "webservice" authentication method.  This authentication method will only allow access via Web Services, restricting the user form normal login.

[[File:Webservices-user-access.png|border|Web Service allocate access to a user for simple authentication]]


== OAuth Authentication Access Control ==

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 automatically generated.

[[File:Oauth-service-configuration.png|border|Web Service access configuration for OAuth]]

When an external application attempts to access the Mahara API via OAuth, it will be challenged requiring the user to login and accept the application linking.  This creates a Mahara specific user access token.  Mahara users can inspect and maintain their own access tokens:

[[File:Oauth-user-tokens.png|border|User OAuth access tokens]]