Learn to use controlled-access data on Terra by linking your Terra user ID to your NIH authorization account. Linking to external servers allows Terra to automatically determine if you can access controlled datasets hosted in Terra (such as AnVIL and other data hosted by the Broad Institute) based on your valid dbGaP applications. Read on for project-specific screenshots and step-by-step directions.
What data access this covers
- AnVIL data workspaces
- Data in the Terra Data Repository
Open access data
You can access open-access data in AnVIL without linking an NIH-authorization account.
How it works
If you are an NIH researcher with a dbGaP account, you can link your Terra user ID to a Login.gov or ID.me account linked to your eRA Commons ID. AnVIL researchers must link Terra accounts in order to access and import controlled-access data files (i.e., CRAMS and VCFs).
In order to link your NIH authorization to Terra, users of eRA Commons must transition to the use of Login.gov or ID.me credentials, instead of your eRA Commons username and password, to log in. This adds two additional steps to the process of linking your external identity to Terra - 1) Setting up a Login.gov or ID.me account and 2) Linking your Login.gov or ID.me account to your eRA Commons account. See step-by-step instructions below.
For more background, see Transitioning to and using login.gov.
Step 1: Set up a login.gov or id.me account
You will need a Login.gov or ID.me account before you can link your external NIH identity to Terra.
Step-by-step instructions
- If you already have a Login.gov or ID.me account, you can skip this step. NOTE: You may be asked to verify or re-verify your identity depending on the current state of your account.
- To create a new account, follow the steps in Create your Login.gov account or Create your ID.me account. This will require setting up multi-factor authentication (MFA) and verifying your identity.
Step 2: Link your eRA and Login.gov accounts
Linking your eRA account to your Login.gov or ID.me account will maintain your access to your dbGaP studies in Terra and TDR.
Two separate accounts are now required for NIH authorization
- An eRA Commons User ID and password
- A Login.gov or ID.me account with its own separate User ID and password
You will need both to link Terra to your NIH authorization
After setting up Login.gov or ID.me, you will still need to know and maintain your eRA Commons account credentials (and change the password once per year), but you will use Login.gov or ID.me credentials to log in and link your external NIH identity to Terra.
Step-by-step instructions
- Go to the NIH Linked Identities Settings page
- Log in with your Login.gov or ID.me account
- Link your Login.gov or ID.me account with your eRA account
Once linked, your Linked Identities page should look similar to this:
Step 3: Link your Terra profile to NIH authorization
With a Login.gov or ID.me account and a linked eRA Commons account, you can now link your external NIH identity to Terra to access AnVIL data.
Step-by-step instructions
- Go to your Profile > External Identities page on Terra
- Click Log In To RAS within the NIH Researcher Auth Service Section (RAS) section
- Log in with your Login.gov or ID.me account
Once linked, your External Identities page should look similar to this:
NOTE: It may take a few seconds for Terra to synchronize with RAS. If your eRA Commons ID shows as none or your Resource authorizations appear empty, try refreshing the page.
If that does not resolve the issue, click the Manage your linked identities link, which will take you to the NIH Linked Identities Settings page in Step 2 above and validate you have linked your eRA account to your Login.gov or ID.me account.
Finding the data you're authorized to use
Click on the sections under Resources for a full list of datasets you’re authorized and not authorized to access.
If you were just granted access to a dbGaP study, it can take up to 30 hours for your data to be available for analysis in Terra.
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 can finish before the expiration deadline.
Links expire after 15 days and you'll need to renew your link to access 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.
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.