How to access controlled data on external servers (i.e., Gen3)

Liz Kiernan

Learn to use controlled-access data from Gen3 on Terra by linking your Terra user ID to your authorization account (such as a dbGaP account). Linking your authorization lets Terra automatically determine if you can access controlled datasets based on your valid dbGaP applications. Read on for project-specific screenshots and step-by-step directions.

If you need to access data stored in the AnVIL or the Terra Data repository

See How to access controlled data files by linking your NIH authorization

Access Gen3 data files by linking your Terra account 

As an example, if you are an NIH BioData Catalyst researcher with a dbGaP account, you can link your Terra user ID to your eRA Commons ID. BioData Catalyst researchers must link Terra accounts in order to access and import Gen3 data files (i.e., CRAMS and VCFs).

Step 1: Log into Gen3

Before following the steps below, log into your Gen3 account. You can use either your NIH login or your Google login. When you link your account to Terra, Terra will know to use the same login.

BioData catalyst https://gen3.biodatacatalyst.nhlbi.nih.gov/
KidsFirst DRC https://data.kidsfirstdrc.org/
NCI CRDC https://nci-crdc.datacommons.io/

Step 2: Link authorization in Terra

1. Go to the main navigation menu by selecting the three horizontal lines at the top left of any page in Terra

2. Click on your name to expand and then on Profile.

  • Terra platform

    Terra homepage highlighting Profile in left-side hamburger menu

  • BioData Catalyst on Terra

    BioData Catalyst on Terra highlighting Profile in left-side hamburger menu

3. Click the EXTERNAL IDENTITIES tab.

Profile page with the EXTERNAL IDENTITIES tab highlighted

4. Link to the relevant server by clicking its respective LOG IN button.

EXTERNAL IDENTITIES tab on the profile page which displays multiple possible external server links (NIH Account, BDC, CRDC, AnVIL, and Kids First)

When you select a link, you'll be taken to an external authentication webpage. The authentication will automatically match the way you authenticated on the Gen3 platform (Google versus NIH versus RAS, for example). Follow the instructions to link your accounts.

  • NIH authentication screenshot

    NIH-authentication screenshot AnVIL example showing Smart Card login
  • Google login screenshot

    AnVIL instance on Google login page

5. Once you're linked, you'll see a link expiration deadline for each external service.

NHLBI BioData Catalyst Framework Services with link expiration highlighted

Some data requires an NIH Account linkIf you are unable to access the data associated with your external server of choice, try also establishing a link on the NIH Account connection.

Pay attention to the expiration deadlines! If your link expires, any attempt to access/import data/or manipulate files from the Terra platform will result in an error indicating a user is not authorized to access data. For example, if your link expires while you are running a multi-day workflow on imported data, the workflow will fail.

Please ensure all workflows on imported Gen3 data can finish before the expiration deadline. Links expire after 15 days, and you will need to renew your link to access or analyze data. 

Renewing your account link

Select the Renew link and follow the instructions. You can relink your account at any time, which will restart the 15-day link expiration time.

EXTERNAL IDENTITIES tab in the Profile page with the Renew options highlighted under the NIH account link and the CRDC account link.

Unlinking your account

If you don’t renew your authorization links, you will get a notification that they have expired and you need to relink them. You can also do this proactively by clicking Unlink at the end of your session.

EXTERNAL IDENTITIES tab in the Profile page with the Unlink option highlighted under the NIH account link.

 

Was this article helpful?

Comments

6 comments

  • Comment author
    Liz Kiernan

    John-Hanson Machado thanks for letting us know about the issue.

    A colleague was able to replicate the error after associating their eRA Commons account with login.gov. To resolve the issue, they logged out of eRA commons and refreshed the Terra profile page, then tried to renew the link in Terra again. Would you be able to see if it works for you? Thank you!

    1
  • Comment author
    John-Hanson Machado
    • Edited

    Liz Kiernan thank you for your quick response.

    I could not see an option to log out of eRA Commons and my NIH account in the "Identity & External Servers" in the right pane of my profile, only a "Renew" option.

    I could, however, unlink the NHLBI BioData Catalyst, NCI CRDC Framework, & NHGRI AnVIL Data Commons, but when redirected by the link in Terra to enter my username and password, my login.gov credentials do not work here (login failed).

    I then clicked on "Trouble signing in?" and did not see login.gov as an option (not shown in images here). I also verified I had the correct login.gov username and password by going separately to login.gov and using those credentials to successfully sign in. What am I missing?

    0
  • Comment author
    Samantha (she/her)

    Hi Florian Hölzlwimmer,

     

    You should be able to add your student as a data downloader so that he can access GTEx data: Assign Downloaders for dbGaP Data

     

    Best,

    Samantha

    0
  • Comment author
    Samantha (she/her)

    Hi John-Hanson Machado,

    Renewing your access with login.gov credentials is currently not supported by RAS. Can you try signing in with your eRA commons account?

    Best,

    Samantha

    0
  • Comment author
    Florian Hölzlwimmer

    Hi,

    A student working with me does not have any dbGaP account.
    Is it possible for me to grant him access to my workspace even if it requires 'GTEx-dbGaP-Authorized' as authorization domain?

    Otherwise, it sounds like a hassle to request an NIH account + dbGaP access for every student in our lab, especially since dbGaP is not meant for this.

    Best,
    Florian

    0
  • Comment author
    John-Hanson Machado

    Thanks for this!

    I previously had linked to my Terra Profile: NHLBI Biodata Catalyst Framework Services, NCI CRDC Framework Services, & NHGRI AnVIL Data Commons Framework Services. These links expired. The "Renew" link appears, but following this link in either Firefox or Chrome does not allow me to renew.

    I think this may have to do with the migration of eRA Commons to using login.gov, which is required by all users by September 15, 2021. Any idea how I can now use my login.gov credentials instead of eRA Commons when renewing expired access?

    Cheers,
    John-Hanson

    0

Please sign in to leave a comment.