There are three security mechanisms for using the web services. You can use any of these.
Token
This is a simple token added to every web method call to let us know who is requesting the data. The token can be used to test calls but it should never be exposed in web pages from where others might read it.
Application key
So we can identify who is using the web services for what, an application key is issued to each developer. The key is used in conjunction with a secret to sign each URL.
Subscribing organisations and registered users are automatically assigned a key for their organisation to use by signing in and going to the Keys page.
Once you have a key, you can use developertools.esd.org.uk/service to sign URLs. An example of PHP source code which can be used in a page is available. Python code to make web service calls is also available.
OAuth access
OAuth is the open standard for authorisation.
esd has a sign-in mechanism which uses OAuth so any developer can implement sign-in in the same way as LG Inform and LG Inform Plus. If your application uses OAuth sign-in, you can give signed-in users access (via the web services) to data personal to them and non-public data that their organisation might be permitted to use.
To prevent security issues when handling redirects from the OAuth process, please don't allow redirection to other domains that you do not control.
OAuth - retrieving an access token
OAuth uses a per-organisation shared secret / access token combination, which prevents access from unauthorised parties. The OAuth service uses version 1 of the OAuth standard. You should choose a suitable OAuth library for your desired programming language.
There are three steps involved in getting an access token. This is normally handled by your OAuth library:
- Get the request token
- Users manually grant access
- Exchange request token for access token
In OAuth there can be three different end points one for each of the above steps. We implement the three end points with the same URL: https://signin.esd.org.uk/oauth.handler
Before you can get an access token for your application you need to ask esd support to set up a consumer key and secret for you. Note you should never expose your consumer secret.
Use the instructions detailed in your chosen OAuth library along with the consumer key, secret and above end point URL to get the access token. Your server must be within a couple of minutes of the current time, otherwise the tokens will not work.
OAuth - Accessing the web services
Once you have retrieved the access token as described above you can use it to access the web services. Your library should provide a method that creates an authorised request. This should accept the access token and automatically add all the required OAuth parameters to your request. These parameters will be read by the web service and used to grant access as well as provide any user specific information.
