There are two scenarios in which authentication is required in SMART Genomics: (1) when an app accesses an account's data; and (2) when an account accesses external records of the container (server). SMART Genomics uses OAuth2.0 for both authentication processes.
Table of Contents
Overview
All third-side clients must register against a SMART Genomics container before accessing data from that container. There are two steps that are necessary in order for a third party to access data using SMART Genomics' version of OAuth2: (1) Obtain an access token; and (2) use the access token to access data. One must obtain an access token using this work flow (with redirectable url). To use an access token in a request, use the HTTP Authorization header as below:
Authorization: bearer {access_token}
Triggering Web App
When a web-based application is launched within a SMART Genomics container (server), the app will be hit with the following HTTP request:
Request
GET {launch_uri_registered}
Parameters
api_base = {base_url_of_the_api_server},
launch_with = {resource_type}/{id_of_the_resource} //optional
The parameter launch_with indicates the resource that the user launches with the app. Possible values for {resource_type} are patient, sequencinganalysis, and sequencinglab.
Scope
Different permissions that are required to access different resources are specified on this page. To inform the user of the scope of your access, set scope to be a space-delimited list of permissions when requesting authorization code from the user.
Below is an example scope specifying the right to read the user's sequence and patient resources in the user's account:
scope = read:sequence read:patient
Permission
A permission in the OAuth2.0 flow of SMART Genomics API is formatted as follows:
operation:resource
with resource being one of FHIR resources or file. An exception to this rule is that file can also have permission as follows:
operation:file:{file_id}
Here is a list of possible operations with a brief explanation:
- read - The right to access existing resources
- write - The right to modify content of existing resources
- delete - The right to delete resources
- create - The right to create resources
- admin - The right covering all of the above
Obtaining access token
Get authorization code* by redirecting the user to an authorization page, specifying your client id and scope**.
1. Use the HTTP request below for requesting authorization.
Request
GET /auth/authorize
Parameters
response_type = code,
client_id = {your_client_id},
scope = {your_scope},
state = {any_text_you_want_to_put_here} //optional
2. If your access is authorized by the user, the following parameters will be sent to the redirect_uri* specified in your app dashboard.
code = {authorization_code_given}
state = {the_state_you_specified_in_step_1} //optional
3. Exchange the access token with the code you received in step 2.
Use HTTP request below for exchanging the access token.
Request
POST /auth/token
Parameters
grant_type = authorization_code,
client_id = {your_client_id},
client_secret = {your_client_secret},
code = {code_you_got_in_step_2},
state = {any_text_you_want_to_put_here} //optional
4. If your credentials are authenticated, a HTTP 200 will be sent back to you with the following parameters.
access_token = {access_token_given},
expires_in = 86400,
state = {state_you_specified_in_step_3} //optional
5. Access the protected resource with the access token.