Step-by-step directions to set up an Authorization Domain (AD), plus troubleshooting hints for ADs in Terra. Recommended for protecting access to controlled data, ADs build on workspace permissions with an additional layer of security. While workspace permissions protect primary data stored in workspace cloud storage or data tables, Authorization Domain protection follows a workspace when it's copied, so only authorized users can access generated data.
Before you assign an Authorization DomainAuthorization Domains are permanent! To share down the line with people not on the AD, you'll need to create new versions of the workspaces and copy over any TSVs/data/notebooks you need manually, since clones of the workspace protected by the AD will automatically inherit the AD. Note: You will not be able to copy the workspace bucket contents to the new workspace, as the bucket contents are protected by the AD!
Are workspace permissions enough protection?
When cloning a workspace, the metadata in the data tab are copied, but any files referenced by that metadata stay in their original location. So the original files in the original workspace won't be accessible anyway if a workspace is cloned by someone with "reader" access to the workspace. They'll create a replica of the data table with the metadata, but it will point to the newly cloned workspace's bucket, which will be empty. Note, however, that derived results in the new workspace would be shared if using workspace permissions.
To learn the principles of Authorization Domains see Overview: Managing access to controlled data with Authorization Domains.
If workspace permissions are enough for your needs, see Managing access to shared resources (data and tools for more details about how to use and set them up.
1. Set up/ verify Authorization Domain group
Before you can assign an Authorization Domain to a workspace, you will need an authorization domain group. There are two kinds of groups you can use for Authorization Domains: Terra managed groups and third-party groups such as TCGA or TARGET.
-
You can create a Terra managed group to use with an AD within Terra. Once you set up a group, you can use it for the authorization domain when you create a new workspace.
How to create a managed group in Terra
Create a (user-defined) AD group by going to the Groups page in the main navigation menu under your name. Follow the prompts to create a group, e.g., “sample_group”, and add members to the group.
See the screen capture of the process below.
Group owners are responsible for giving and revoking access.
-
Terra supports a number of third-party party groups such as TCGA Controlled-Access, GTEx, and TARGET. These groups are organized and managed outside of Terra. Access depends on external permissions.
To gain access to workspaces protected by these authorization domains, you must link your Terra account to your eRA Commons or NIH account on your Profile page.
Click here for step-by-step instructions to link data authorization to your Terra account.
Terra then checks for the user ID of the linked account in the dbGaP access list to complete the authorization.
2. Create a workspace and assign an Authorization Domain
Once you have set up or verified your group membership, you can use it when assigning an Authorization Domain to a workspace. Any member of the authorization group can assign an AD to a workspace they create.
An Authorization Domain can only be set when creating the workspaceOnce set, it cannot be removed from the workspace. It will be copied over to any cloned version of the workspace, protecting any derived data.
2.1. When creating a new workspace, you'll see the Authorization domain dropdown in the Create a new Workspace form.
2.2. Select one or more groups for the Authorization Domain from the dropdown. All Authorization Domains you belong to (third-party and Terra user-managed) should appear in the dropdown.
3. Share the workspace
3.1. Once you've set up the AD, you'll need to share the workspace, either with the group you used in the Authorization Domain, or with one or more individuals.
To access an AD-protected workspace requires two permissions 1. Membership in all the workspace ADs
2. Reader, writer or editor permission on the workspace
3.2. To share with a group, start typing the group name into the Sharing dialog and choose from the autocomplete options.
Troubleshooting and Additional resources
When an Authorization Domain includes multiple groups
When multiple groups are included in the Authorization Domain, you must be a member of all groups to access the workspace. This is because of strict guidelines with third-party dbGaP registered datasets (TCGA and TARGET).
Example case: TCGA and TARGET Consider a workspace whose Authorization Domain includes both the TCGA and TARGET groups. If a user is invited to the workspace, Terra checks both the TCGA and the TARGET access lists before allowing access.
What happens when someone not in the AD tries to access the workspace?
If you share with individuals or a group not in the Authorization Domain, they will see the workspace grayed out in their workspace list. When they click it, Terra will send an email to all owners of the Authorization Domain groups requesting access. Once the user is a member of the AD(s), they can enter the workspace and access the protected data.
GTEx, TARGET, or TCGA workspace?
If you receive an error message that you aren't a member of the authorization domain for a GTEx, TARGET, or TCGA workspace, this generally means your authorization in your NIH/dbGaP link isn't active.
Access to the AD is automated based on authorization from dbGaP, which is updated every six hours on Terra. Click here for step-by-step instructions to link data authorization to your Terra account.
Additional resources
- To understand the principles behind Authorization Domains, see Managing access to controlled data.
- To learn more about linking to external servers, see this article.