Accessing TCGA controlled-access workspaces in Terra

Tiffany Miller
  • Updated

How to access and use the dedicated TCGA controlled-access data workspaces on Terra. 

How to access TCGA Controlled Data workspaces

To use TCGA Controlled Data in Terra, you must:

1. Have an eRA Commons or NIH account with dbGaP authorization 

For instructions on how to set up an eRA Commons or NIH account with dbGaP authorization, follow this link.

2. Link to your eRA Commons/NIH Account and the NCI CRDC Framework Services

2.1 Go to your Profile page by selecting the main menu icon in the top left from any page in Terra

2.2. Log in with your NIH credentials


Once you have met these requirements, you will be granted READER access to all pre-populated TCGA Controlled-Access workspaces.

Derived data from Controlled-Access workspaces

The National Cancer Institute (NCI) and dbGaP consider any data derived from TCGA Controlled Data to also be TCGA Controlled Data.

Terra users can derive data (also controlled-access) from Controlled Data by:

  • Cloning a TCGA Controlled-Access workspace and running analyses in the cloned workspace

  • Creating a new workspace, copying entities referencing Controlled Data into the new workspace, and running analyses in that workspace

Rather than track specific data objects as "controlled-access", Terra identifies workspaces as TCGA Controlled-Access, and restricts access to those workspaces to users who meet the requirements above.

Creating and cloning a TCGA Controlled-Access workspace

When you create a new workspace, you can add the "TCGA-dbGap-Authorized" group to the Authorization Domain to protect any TCGA Controlled Data in your workspace. Once a workspace has this Authorization Domain set up, it remains a TCGA Controlled-Access workspace.

When you clone a TCGA Controlled-Access workspace, the cloned workspace will automatically have "TCGA-dbGap-Authorized" group in the Authorization Domain.

If you are granted access (READER, WRITER, or OWNER) to a TCGA Controlled-Access Workspace but do not meet the requirements listed above, you can view the workspace in your workspaces list, but will be unable to open it. This may occur, for example, if another user shared a TCGA Controlled-Access workspace with you but your dbGaP authorization has not yet been approved or the linkage of your Terra and eRA Commons accounts has expired.

If you can not enter a TCGA Controlled-Access workspace, but believe you have dbGaP authorization for Controlled Data, you may need to re-link your eRA Commons / NIH account. You can go to "Main Navigation" --> "User Profile" to check your dbGaP authorization status. If your login has expired, click Log-In to NIH to re-link your account.

Sharing a TCGA Controlled-Access workspace

If you are the OWNER of a TCGA Controlled-Access workspace, Terra will not prevent you from sharing the workspace with a user who does not meet the requirements to access Controlled-Access workspaces. However, these users will not be able to access the workspace you shared unless they met the requirements (above).

Google buckets for TCGA Controlled-Access workspaces

Google buckets associated with TCGA Controlled-Access workspaces will be accessible to Terra users who

  1. Meet the requirements for TCGA Controlled-Access workspaces
  2. Have the appropriate permission of READER, WRITER, or OWNER for that workspace

Users who meet these requirements can access the buckets using the workspace Summary tab or gsutil.

Copying entities from TCGA Controlled-Access workspaces

In order to copy entities from a Controlled-Access workspace, the destination workspace must also be in the Authorization Domain with the "TCGA-dbGap-Authorized" group. When copying entities to an open-access workspace, Terra will not offer the choice to copy from a Controlled-Access workspace.

Disclaimer about TSV load files

Terra does not identify controlled-access data within TSV load files. Therefore, Terra cannot prevent users from uploading TSV Load Files referencing controlled data to an open-access workspace.

All users accessing controlled-access data are bound by the dbGaP TCGA DATA USE CERTIFICATION AGREEMENT (DUCA). In addition, users must adhere to Terra's Terms of Service.

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.