COG-UK Docs

View the Project on GitHub COG-UK/docs

Updated 2020-09-11 by @samstudio8

Creating an OAuth application

Registering an OAuth application with Majora

If you want an applicaton to perform actions as a Majora account holder, you need to register an application. Note that the testing and real versions of Majora are entirely separate, and so are the OAuth systems. The locations to register an application are:

Click “New application” and fill out the form as appropriate:

Finally, if your application has a web-based front end, you can specify a callback for authorised requests to automatically flow to - along with a grant token. If you do not have one, we provide a basic callback that will expose the grant code.

As per NHS digital guidelines, we only allow applications that use the authorization code flow.

Basics

Once you have an application, the authorisation flow can be summarised as follows:

1. Ask for a user to give permissions to your application

2. Convert the new grant token to an access token

3. Receive an access token

4. Use the access token

You will need to send a Authorization header formatted: Bearer TOKEN where TOKEN is your access_token. All API endpoints in the v2 API support OAuth and rotating API keys.

API requests must continue to include the username and token in the request data, though these are not checked (this is just a feature that enables backward compatibility).

5. Refresh the access token

If successful, you’ll see the same JSON struct as step 3. Store the new access token and refresh token to repeat. You can automate this process easily through cron to keep your token rotated.

Scopes

You must request at least one scope from a user. Every scope maps to a user permission in Majora. A user can only authorize an application if they have been granted all the permissions for all scopes requested. When specifying scope in Step 1, scopes must be separated by an URL-encoded space (%20).

Currently, OAuth scopes only cover the functionality provided by the uploader tool (e.g. biosamples and their collections, sequencing libraries and their pooling events and seqencing runs). To simplify matters during this trial phase, just request all scopes to cover these activities:

majora2.add_biosampleartifact
majora2.change_biosampleartifact
majora2.add_biosamplesource
majora2.change_biosamplesource
majora2.add_biosourcesamplingprocess
majora2.change_biosourcesamplingprocess
majora2.add_libraryartifact
majora2.change_libraryartifact
majora2.add_librarypoolingprocess
majora2.change_librarypoolingprocess
majora2.add_dnasequencingprocess
majora2.change_dnasequencingprocess

These will change and be expanded as we continue to integrate OAuth to the rest of the system.

More information

Common pitfalls


Published 2020-09-11. Updated 2020-09-11. Page maintainer @samstudio8.