Introduction

The cBioPortal provides access to data within its database through the cBioPortal web service. While most users interact with this web service indirectly while visiting cBioPortal web pages, it is possible to access this web service directly. Direct access to the web service is appealing for those users with an interest in mining or analyzing cBioPortal data beyond the confines of a web browser, such as from ‘R’ or Python clients.

If your instance of the cBioPortal will not require user authorization (login), direct access to the web service is available without any additional server configuration or client side prerequisites. However, if your instance of the cBioPortal will require login, additional data access token server configuration is necessary before direct access to the web service is available to your users. Additionally, prior to web service access, clients will need to obtain a data access token and present this token with each web service request.

This document contains information for both cBioPortal administrators and users. For administrators, this document describes how to configure an instance of the cBioPortal with data access token support. For users, this document provides details about how to obtain a data access token and present it with a web service request (see Using Data Access Tokens).

Configuring Data Access Tokens within cBioPortal

Implementations

The cBioPortal codebase comes with two data access token implementations, both of which come with strengths and weaknesses. The first implementation based on JSON Web Token (JWT) technology, is appealing because the data access token contains all the information required to validate the token during a web service request. When a data access token is generated by the cBioPortal, its expiration date is inserted into the token. The data access token is then signed and encrypted before presenting it to the user. When the data access token is presented in a subsequent web service request, the cBioPortal is able to inspect the token and determine its validity before satisfying the request. The downside to this implementation is that since the data access token is self-validating, no information about the token is stored in the database. This means there is no way to revoke a data access token in the event that it has been compromised or limit the number of data access tokens per user.

The second implementation based on Universally unique identifier (UUID) technology, allows for greater control over the data access token at the cost of additional database support. Unlike JWT based data access tokens which are self-validating, a UUID based token is a string representation of a unique number. When a data access token is generated by the cBioPortal, a record is inserted into the data_access_tokens database table:

mysql> describe data_access_tokens;
+------------+--------------+------+-----+---------+-------+
| Field      | Type         | Null | Key | Default | Extra |
+------------+--------------+------+-----+---------+-------+
| TOKEN      | varchar(50)  | NO   | PRI | NULL    |       |
| USERNAME   | varchar(255) | NO   | MUL | NULL    |       |
| EXPIRATION | datetime     | NO   |     | NULL    |       |
| CREATION   | datetime     | YES  |     | NULL    |       |
+------------+--------------+------+-----+---------+-------+
4 rows in set (0.00 sec)

In addition to storing the token (the unique number), its creation and expiration dates along with the associated username is also stored prior to presenting it to the user. When the data access token is presented in a subsequent web service request, the cBioPortal compares the token presented in the request against this table for validity. If the token exists in the table and has not yet expired, the request will be satisfied. The creation date is used by the cBioPortal when a user requests a new data access token. Based on the server configuration, if the number of outstanding data access tokens together with this new one exceeds the number of allowable data access tokens per user, the cBioPortal may refuse to present a new one or it may invalidate the oldest one before presenting the new one to the user.

Modifying Configuration

The following properties must be present in portal.properties in order to allow direct access to the cBioPortal web service when login is required:

Property: dat.method (required)

• Description: The desired data access token implementation.
• Permissible Values: jwt, uuid, none
• Default Value: none

Property: dat.unauth_users (optional)

• Description: A list of users that should not be allowed to download a data access token.
• Permissible Values: A comma-delimited list of valid user names as found in the users table.
• Default Value: anonymousUser

Property: dat.ttl_seconds (required)

• Description: The time in seconds between token creation and token expiration.
• Permissible Values: An integer value greater than zero.
• Default Value: 2592000 (30 days)

Property: dat.jwt.secret_key (required only when dat.method = jwt)

• Description: The signature used to sign JWT based data access tokens during creation. This signature is used in subsequent web service requests to validate the request. This property is used only when dat.method = jwt.
• Permissible Values: A string value.
• Default Value: none

Property: dat.uuid.max_number_per_user (required only when dat.method = uuid)

• Description: This property determines the number of data access tokens that can be allocated to a single user at any given time. If a user requests a data access token that puts them over this limit, then based on the value of dat.uuid.revoke_other_tokens (see below), the cBioPortal will either refuse to present a new token to the user or it may invalidate the oldest one before presenting the new one to the user. This property is used only when dat.method = uuid.
• Permissible Values: An integer value greater than zero.
• Default Value: 1

Property: dat.uuid.revoke_other_tokens (required only when dat.method = uuid)

• Description: If true, Indicates that the oldest token should be invalidated when a user requests a new data access token that puts them over the dat.uuid.max_number_per_user limit. If false, new token requests which put a user over the data.uuid.max_number_per_user limit will not be satisfied until an existing token has expired. This property is used only when dat.method = uuid.
• Permissible Values: true or false
• Default Value: true

Using Data Access Tokens

To directly access the web service of a cBioPortal instance which requires user login, clients will need to obtain a data access token and present this token with each web service request. To obtain a data access token, login to the cBioPortal and then choose “Download token” from the “Logged in as…” dropdown menu located on the top-right section of the webpage (note this menu option will not be present if the instance of the cBioPortal has not be configured to support data access tokens):

The downloaded data access token file will contain the token, a creation date, and an expiration date:

token: 63efa81c-2490-4e15-9d1c-fb6e8e50e35d
creation_date: 2018-11-28T20:23:55.241Z
expiration_date: 2019-05-27T20:23:55.241Z

To directly access the web service, add an Authorization header to the web service request:

Authorization: Bearer 63efa81c-2490-4e15-9d1c-fb6e8e50e35d

Here is an example curl command showing a request to GET /api/studies with the proper Authorization header set:

curl -X GET "http://www.cbioportal.org/api/studies" -H "accept: application/json" -H "Authorization: Bearer 63efa81c-2490-4e15-9d1c-fb6e8e50e35d"

If a web service request is made without an Authorization header or if the token within the header is not valid, the web service will not satisfy the request and will return with an HTTP Status 401. Additionally, there are a handful of properties which determine the behavior of cBioPortal data access tokens (see Configuring Data Access Tokens within cBioPortal). For example, a data access token may have an expiration date of 30 days after its creation date or 300 days. Similarly, there may be a limit to the number of data access tokens a user may have at any one time. If this limit is reached a new data access token may or may not be downloadable. Please check with the local cBioPortal system administrator for more information about how data access token behavior has been configured.