JWT based access control

Introduction

ProteinPaint employs the secure JSON web token (JWT) method to perform access control ensuring that only authenticated client requests carrying a valid token will be allowed access to a dataset, otherwise the request is denied. By following these steps, you ensure that only authorized users with a valid JWT can access the dataset within ProteinPaint.

Terminologies

• JWT: JSON web-token, a URL-safe way to transfer information between parties as a JSON object. For more information, visit https://jwt.io/
• Data portal: a separate web application that embeds the ProteinPaint visualizations within its interface.
  • In this document, the URL of the data portal is referred to as https://<Data_Portal_Domain>
• ProteinPaint instance: a web service running the ProteinPaint container serving datasets that will be visualized within the data portal.
  • In this document, the URL of the ProteinPaint service is referred to as https://<ProteinPaint_Domain>
  • The dataset hosted in ProteinPaint instance is referred to as <Dataset_Label> which is a short string

General steps

• Step 1: Set up a ProteinPaint instance which hosts an access-restricted dataset
• Step 2: Create and Sign a JWT token e.g. upon user log in and access verification
• Step 3: Pass the token The data portal invokes ProteinPaint client side code bundle by passing the token
• Step 4: Optionally implement role-based access control by modifying the token payload.

Set up a ProteinPaint instance

(Skip this step if this is taken care of by the ProteinPaint team)

See details at https://github.com/stjude/proteinpaint/wiki/Installation-Option-A:-Pull-a-Prebuilt-Image-(Recommended)

This instance should host a dataset that will be embedded into the portal, identified as <Dataset_Label>.

This instance should enable access control on <Dataset_Label>, by adding the following contents to the serverconfig.json file.

  "dsCredentials":{
    "<Dataset_Label>": {
      "*": {
         "<Data_Portal_Domain>": {
           "type": "jwt",
           "secret": "<my-secret>",
           "dsnames": [
              {
                "id": "<Dataset_Label>",
                "label": "<Dataset_Label>"
              }
            ],
            "headerKey": "x-ds-access-token",
            "looseIpCheck": false
          }
        }
     }
   }

Notes:

• Keys under <Dataset_Label> are ProteinPaint routes under access control for this dataset.
  • *: all routes are access controlled. No parts of the dataset will be accessible without the token.
  • termdb: only sample-level data are controlled. Aggregated results e.g. barchart will be accessible without the token.
• Use "*" instead of <Dataset_Label> will secure all datasets.

Embed ProteinPaint in the data portal

Method 1: In the portal HTML, include <script src="https://<ProteinPaint_Domain>/bin/proteinpaint.js" charset="utf-8"></script>. This generates a global function called "runproteinpaint()".

Method 2: Use NPM module. See instructions.

Data portal creates token

The data portal, not ProteinPaint, must create the token. The portal generates a payload (a JSON object) as below:

{
  "datasets":["<Dataset_Label>"],
  "email":"<email or user id>",
  "ip":"<optional IP address>",
  "iat":"<issued at time>",
  "exp":"<expire time>"
}

For standard payload claim keywords, visit: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1

ProteinPaint requires these custom claim keywords:

• datasets: an array containing "<Dataset_Label>" string
• email: for identifying the user
• ip: for identifying the user

The data portal will sign the token with a secret that is shared with the ProteinPaint instance. The shared key could either be a public key from asymmetric encryption, or a private key from symmetric encryption. This detail is automatically handled using the JWT header.

The data portal will need to make the token available on the client side for the next step.

Data portal passes the token to ProteinPaint

The data portal client-side code will invoke the ProteinPaint client-side code bundle by calling:

runproteinpaint({
  host:"https://<ProteinPaint_Domain>",
  holder:<DIV DOM element>,
  mass:{
    state:{
      dslabel:"<Dataset_Label>",
      genome:"<Genome_Name>"
    }
  },
  getDatasetAccessToken:()=>{}
})    

Required parameters of "runproteinpaint()": `

• host: the domain to access the ProteinPaint web service, which is https://<ProteinPaint_Domain>
• holder: a DIV DOM element in which ProteinPaint will render the data visualizations
• mass: a Javascript object to launch the visualization for the dataset identified as "<Dataset_Label>", as well as its accompanying genome name. TODO link to embedding param page.
• getDatasetAccessToken: The data portal should generate this Javascript callback function. The function has no parameter, is not async, and will return the token string

Role-based user access control

The previous section enables "on-or-off" access. To finetune the access based on a user's role, at the token payload, insert the "clientAuthResult" property.

{
  "datasets":["Dataset_Label"],
  "clientAuthResult":{
    "key":"a set of key-value pairs based on actual design"
  } 
}