Documentation › OAuth

OAuth

The ProvStore API supports OAuth protocol for authentication and authorization. The API supports the common web server application flow for using the protocol. At its core OAuth will register applications with the web service and allow these applications to access resources by redirecting the browser to a given URL, parsing the token from the response and using it to authenticate. For detailed information about the flow of the protocol we suggest reading the official OAuth Guide. This guide explains how to use the protocol for authentication and authorization as is used by the ProvStore service.

Registering an App

In order to send/receive OAuth exchanges, you must have registered your app to use with the service. Creating an app provides you with two keys, a consumer key and a secret key, that are used to authenticate and identify your app to ProvStore. To create an app, when logged in, visit the Developer Area and click 'New App'. When you have submitted your app's details you will be redirected back to the Developer Area and should now see your app listed and along with it the two keys you need.

Workflow

The flow of obtaining Access Token is well defined by the OAuth specifications and we will demonstrate it here in practice with the ProvStore API. Let's assume that John is a developer who wants to use the OAuth protocol to access user resources from his web application. He registers his application, as detailed above, and the result of the registration would look like this:

Name
John's App
Description
A friendly application for displaying resources.
Consumer Key
dpf43f3p2l4k3l03
Consumer Secret
kd94hf93k423kf44

Obtaining Request Token

On his application John now has to create a function to obtain a Request Token from the ProvStore. This is achieved by sending either a GET or POST request to https://provenance.ecs.soton.ac.uk/store/oauth/request_token with the following parameters included in the request:

oauth_consumer_key : dpf43f3p2l4k3l03
oauth_signature_method : PLAINTEXT
oauth_signature : kd94hf93k423kf44,
oauth_timestamp : 1191242096
oauth_nonce : kllo9940pd9333jh
oauth_version : 1.0
oauth_callback : http://johns_domain/request_token_ready
scope: api

These parameters can be included in different places in the request according to the OAuth Specifications - "The parameters are collected from three locations: the URL query element (as defined by RFC 3986 section 3), the OAuth 'Authorization' header (excluding the 'realm' parameter), and parameters included in a single-part 'application/x-www-form-urlencoded' POST body (as defined by HTML4)."
Assuming Jane visits John's App and decides that she wants to check out John's visualization of the provenance, when she clicks to connect to her account obtaining the Request Token is the first thing to do. A corresponding response would contain the following information:

oauth_token_secret : Qc7bPafBTku2yT7X
oauth_token : 6e63d062712c4381a559eaf5887a64ef
oauth_callback_confirmed : true

Obtain User Authorization

After obtaining the Request Token, John's App has to get Jane's permission to access her resources. This happens by calling with GET or POST request the authorization URL https://provenance.ecs.soton.ac.uk/store/oauth/authorize/ with only the ouath_token as parameter.

oauth_token : 6e63d062712c4381a559eaf5887a64ef

The response returned from the server would be a redirect and the 'Location' header will contain the URL back to John's App, in order to redirect Jane back to his app. When this happen Jane will be presented with a form to login to ProvStore and when she is logged in she will be given a choice to grant access of her data to John's App. If she grants that access she will be redirected back to the oauth_callback URL (http://johns_domain/request_token_ready) with two extra arguments attached - oauth_token and oauth_verifier. John's Request Token will be approved.

http://johns_domain/request_token_ready?oauth_verifier=8449664522&oauth_token=916197bbb7224e3facd7133c0ead7f52

Obtain Access Token

Now all that is left to do for John is to exchange the Request Token for an Access Token which is the Token used for the actual data. This can be done again by either GET or POST method to the URL https://provenance.ecs.soton.ac.uk/store/oauth/access_token/ with the following parameters:

oauth_consumer_key : dpf43f3p2l4k3l03
oauth_token : 6e63d062712c4381a559eaf5887a64ef
oauth_signature_method : PLAINTEXT
oauth_signature : kd94hf93k423kf44&Qc7bPafBTku2yT7X
oauth_timestamp : 1191242096
oauth_nonce : kllo9940pd9333jh
oauth_version : 1.0
oauth_verifier : 8449664522
scope : api
This will result in response from the server containing the Access Token given all the information provided was correct and flow of the protocol was followed. An example response body may look like this:
oauth_token_secret : UUy9xz2b2YafykRJ
oauth_token : b7c21ff3256447078a2de2a9572be44a

Now when John's App has acquired the Access Token it can access Jane's provenance resources.

Example Request with Access Token

An example request to the API using such Access Token:

oauth_consumer_key : dpf43f3p2l4k3l03
oauth_token : b7c21ff3256447078a2de2a9572be44a
oauth_signature_method : 'HMAC-SHA1',
oauth_timestamp : now
oauth_nonce : accessresourcenonce
oauth_version :  1.0

The URL path of the request would be 'https://provenance.ecs.soton.ac.uk/store/api/v0/documents/X.json' asssuming Jane is the owner of document with ID 'X'. Don't forget that you have to add one more parameter to the request - the oauth_signature which is a digest using the given signature_method of a special oauth Request object. Most languages have support of already build libraries for creating such object given the Access Token, the URL and the parameters above. After adding the oauth_signature to the parameter list John is ready to make a request to 'https://provenance.ecs.soton.ac.uk/store/api/v0/documents/X.json' and successfully retrieve Jane's resource.