Overview: Managing access to controlled data with Authorization Domains

Updated October 21, 2022 16:39

Learn about Authorization Domains and when you need their additional layer of security for controlled-access data. Workspace permissions protect primary data stored in that workspace's cloud storage or data tables. Authorization Domains reduce the risk of accidental sharing and protect generated data because they extend protection to copies of workspaces.

For step-by-step instructions and troubleshooting, see How to set up and use an Authorization Domain.

Background: Securing data in a cloud-native environment

You may be surprised to learn that data in the cloud can be more secure than data stored locally. This is because in a cloud-native platform, security is built-in, and less dependent on individuals. Terra has several layers of effective protection for your data and tools, which is why the platform has achieved FedRamp moderate compliance.

Workspace permissions approach to data security

Example

Consider a case where everyone in your lab is consented on primary data stored in a workspace bucket.

If a new coworker asks you to share your data with them, you would (traditionally) be responsible for checking that this new coworker is officially consented to access the data before giving them permission to view data or analyze in the workspace. You’d have to keep track for yourself which of your fellow scientists has up-to-date authorization.

After checking their authorization, you could give your colleague the right permission and allow them access (read, write or edit permission, as well as "can-share" and "can compute" roles for their workspace) to the data in the original workspace.

This model works well enough if owners only have to keep track of their own workspaces.

However, there is a danger; if you allow "can-share" permission to a colleague, they can share with someone who is not authorized to access the data.

This is where Authorization Domains can help!

What are Authorization Domains?

Authorization Domains are managed groups with strictly enforced workspace permissions that follow the original workspace and all copies of the workspace.

Granting permission to managed groups standardizes access and eliminate some human errorsSharing workspaces with a managed group, instead of individuals, reduces the risk of forgetting to remove permissions on one workspace out of many when someone joins or leaves the a group. However, the burden of defining and enforcing security with workspace permissions ultimately lies with individual researchers.

Improving data security with authorization domains

In the diagram below, an Authorization Domain is represented as a badge that follows the workspace and any copies of the workspace. Workspace permissions make sure that only members of the AD can clone the original workspace. The AD guarantees that if anyone tries to share a cloned workspace with a colleague who doesn’t have the right badge, they won’t be able to view the workspace.

The Authorization Domain group includes only those consented to use the primary data. If the AD is assigned to the original workspace, team members don't need to worry about accidentally sharing sensitive primary data or any generated data from clones of the original workspace.

Authorization domains prevent accidental data sharing

Consider a scenario where you are in your lab’s Authorization Domain, so you have access to a workspace containing primary data (such as files in workspace cloud storage). You clone the original workspace, and do your analysis.

Your clone doesn't include the primary data if you haven't actively copied it, and you can still accomplish your analysis by pointing data in the original workspace's bucket. You may not think about the security implications of sharing your clone because the original files are still in the original workspace.

But any outputs you've generated (aka "derived data") might now be in your cloned workspace bucket.

WITHOUT an Authorization Domain

Adding a user to your clone's permission list may grant access the new derived data.

WITH an Authorization Domain

All clones derived from an AD-protected workspace will require users to be in that AD to view anything in those clones. Since all ADs are inherited, your copied workspace also has the lab Authorization Domain. When you try to share the workspace with a new coworker, Terra will verify that your coworker is in the Authorization Domain before allowing access to your cloned workspace (far right in diagram above).

Removing the burden of enforcing data access from the individual

Create an Authorization Domain when you create the workspace where the primary data is stored
Store primary data in the workspace bucket
The Authorization Domain limits access for all clones of the original workspace to the group, so you don't have to assign the right permissions to every clone manually
Adjust group membership (who is in the Authorization Domain) as lab members change.
Once membership is updated, it affects access to every AD-protected workspace right away.

Workspace permissions versus Authorization Domains

To keep controlled data secure, but still easy to share with collaborators, Terra has several built-in security features that limit access in any workspace.

To access data stored on external systems, you have to link to existing authorization

This system ensures that only people who already have access to the primary data (via traditional authorization mechanisms) can access controlled primary data for analysis in Terra. This protection does not extend to generated data.
To access data and tools in a workspace, you need sufficient workspace permission

Workspace permissions give owners very precise control of who can access what resources in a workspace. For many users, workspace permissions are sufficient for all their needs. Note: You can share with a managed group to streamline the process. Granting a single type of permission to a set of individuals can eliminate the possibility for human error - such as forgetting to remove or add a person on a workspace when they leave or join the group. To learn more about best practices for sharing data and tools in a workspace, see Managing access to shared resources (data and tools).
To further protect controlled data, you can require inclusion on an (optional) Authorization Domain
Authorization Domains are an additional layer of protection for controlled data. Only those included in the AD have access to the workspace and any clones of the workspace.

These features can make working in a public cloud infrastructure safer than working in a traditional local analysis platform, where security is only as good as the weakest (human) link.

How these security features work... together

Terra's security features are like multiple layers that work together to protect the data you store and work you do in a Terra workspace. Some are automatic (i.e., you have to link your authorization to analyze controlled data stored on an external server, after that, access is automatic until your link expires) and some you (or your PI) will need to implement (i.e., assigning the right workspace permissions or assigning an Authorization Domain to a workspace).

When to use Authorization Domains

ADs are most useful when you need to guarantee access control of not only the primary data (stored in workspace storage or a data table) but to all generated data, including data generated by a colleague (or a colleague of a colleague...).

Note that ADs can be useful even if your primary data is stored in an external bucket or platform which requires authorization. In this case, the Authorization Domain protects access to data generated in the workspace from the primary data (stored externally).

Authorization domains

restrict workspace access to the individuals in the group. However, they do not grant access to users in the managed group.
protect access to all data generated on Terra from the original data.
are assigned to workspaces when they are created and follow all workspace copies.

Workspace permissions are sufficient for many use cases See the questions below to decide if you should assign an Authorization Domain for additional protection.

1. Is primary protected data stored in workspace storage?
Authorization Domains are inherited, so they are most effective when applied to workspaces that contain primary, controlled data.

2. Do you need to control what collaborators do with their own clones of the workspace?
You can control who has access to data and tools in a workspace with workspace permissions. However, collaborators with "can share" permission on the workspace with may make their own copies of the original that they can then share.

While it is easy to control the permissions of the primary workspace, it can be hard to keep track of access once collaborators make their own shareable copies. The owner of the original workspace has no control over them sharing with others outside the original group. Authorization Domains can be useful in this case.

3. Is there a well-defined group of people who should have access?
One example: A consent group approved by an IRB or other agency to use controlled data stored in a workspace bucket. An Authorization Domain that includes only the consented users can protect primary data in the Workspace bucket as well as any generated data, no matter who generates or in what workspace it's generated.

Another example: If you want to let people share a workspace with colleagues, but only a certain well-defined set of colleagues (as in a given institution). Note: You can change the individuals in an AD group, but you cannot share a workspace with anyone outside the AD.>

4. Do you anticipate sharing with people who are not on the Authorization Domain?
To ensure protection of controlled data, authorization domains are a permanent fixture for workspaces that use them. There is no easy way add collaborators to workspaces with an AD, unless you also add the collaborators to the AD.

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.

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.

Access requires workspace permissions and AD group membership

Granting access to a protected workspace involves two separate steps.

Add user to the Authorization Domain group list (Terra managed groups only)
Add user to the workspace permission list using the "share" option, and adding that user with a role such as "reader", "writer", or "owner".

Workspace permission is not enough for access

An Authorization Domain supersedes the workspace permission list. Even though it appears possible to add anyone to the permission list of a workspace, if the workspace is protected by an AD that doesn't include the user in question, they won't actually be able to see that workspace. They may get an email notification that a workspace has been shared with them, but if they follow a link in that notification, they'll land on an error message stating they don't have access.

Some Authorization Domain examples

Below are examples of how you might use ADs to protect controlled data for different collaboration scenarios.

Step 1: The PI or PM creates one Lab-wide Authorization Domain, and adds researchers in the lab consented to use the data (i.e., those listed as dbGAP downloaders under the PI) to the AD group.

Step 2: The Authorization Domain group is included when creating any workspaces for that project. The workspace - and all copies of that workspace - are protected by the Authorization Domain

Result: Only researchers consented to use the data can access, copy, or work in the workspaces (this overrides workspace permissions)
Step 1: PI or PM creates several Authorization Domain groups, one for each data consent group and adds researchers to all of the data consent groups that include them.

Step 2: PI creates a primary workspace for each project, and includes the appropriate Authorization Domain. Note: A workspace could be protected by more than one AD, depending on the data (i.e., if a workspace combines data from two consent groups, it will have two Authorization Domains)

Result: A researcher must be included in all the workspace ADs to access a protected workspace
Step 1: PI at one institution creates a project-specific authorization Domain for one consent group. Collaborators in both institutions are added to the Authorization Domain for the data they are consented to use.

Step 2: Collaborating institution creates a second Authorization Domain

Result: Collaborators can access only the workspaces with data they are consented to use, regardless of what institution created the workspace or what institution they are at.