sign in

There are three security mechanisms for using the web services.  You can use any of these.

Public key

This is a simple key added to every web method call to let us know who is requesting the data.  The public key can be used to test calls but it should never be exposed in web pages from where others might read it.
 

Public/private 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 a private application secret to sign each URL.

Subscribers to LG Inform Plus (aka the esd-toolkit programme) and others should request their own personal key.

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.

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:

  1. Get the request token
  2. Users manually grant access
  3. 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: http://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.