How to set up and use an Authorization Domain

Yashasvika Duggal
  • Updated

Step-by-step directions plus troubleshooting for Authorization Domains (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. 

To learn the principles of Authorization Domains see Overview: Managing access to controlled data with Authorization Domains.

Step 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 Authorization Domain groups. 

  • User-defined groups (must be set up in Terra)
  • Third-party groups
  • User-defined groups are created and managed 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

    You can 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.

    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.

Step 2: Assign an Authorization Domain 

Once you have set up or verified your group membership, you can use it to assign 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.

Step 3: Share the workspace

3.1. You can now 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 learn more about linking to external servers, see this article.

To understand the principles behind Authorization Domains, see Managing access to controlled data.

Was this article helpful?

0 out of 0 found this helpful



Please sign in to leave a comment.