The article gives an overview of the structure of permissions in Terra, and includes a helpful diagram of a hypothetical scenario.

Contents

1. Permissions - how users access resources
2. Groups - how large sets of users access resources
3. Billing - the role of the Billing Project Owner

1. Permissions

Access to resources is managed through a permission system based on resources, users, and policies (roles). A policy governs what sort of action (e.g. read, edit, share) can be performed on a given resource (e.g. workspace, dataset), and which users are allowed to perform those actions. When someone creates a resource, the system automatically generates a policy, and adds the user who created the resource to the policy. The level of access is dictated by the role on a policy. For example, a resource creator receives the role of "Owner" for their resource. Each role has its own set of actions that it permits.

The three main resource types are:

• Billing project
• Workspace
• Workflow collection

Some examples of the types of roles that a policy can ascribe to a user for a workspace:

• Owner - may add/remove users (grant access), lock workspace, etc.
• Writer - may write to the metadata, method configs, etc.
• Reader - may read the metadata, method configs, etc.
• Can-compute - able to launch batch compute and notebooks
• Share-writer - able to grant others write access
• Share-reader - able to grant others read access

Some policies are public, and all authenticated users are are automatically added to these policies. This includes things like policies of public workspaces, as well as a policy that allows all authenticated users to request access to a group.

2. Groups

Policies may either be for individual users or for managed groups, which are user groups created and managed by users. These groups also function as resources, since they have the following possible roles/policies governing how a given user interacts with the group:

• Member - users who are in the group. When any form of access is granted to a group, the members are all who have that access.
• Admin - users who may add or remove members or other admins. Admins are also members of the group.
• Admin-notifier - users who are allowed to send notifications to the admins of a group. When a group is created, this access policy is set to public meaning all users are able to request access to a group.

The group gains access to a particular resource when the owner of that resource adds the group to an access policy, and a group member connects to the role/policy of the resource via the policy that connects them to their group. Permissions for managed groups should not be confused with permissions for other resources.  If a group is given access to a workspace, the workspace's owner controls what policy will connect the group to their workspace, but the group's owner controls the policies that connect the users to the group, and subsequently to the resource (workspace) policy. 

3. Billing

Roles function hierarchically, with the highest role being "Billing Project Owner". As with other Owner policies, creating a new billing project will generate a Billing Project Owner policy and add the creator to the policy. The Billing Project Owner role permits this user to add other users as Workspace Creators, who subsequently become Owners of whatever resources they create.

Roles/policies for a billing project (resource):

• Owner - full access including adding and removing users to policies
• Workspace-creator - may create workspaces. Importantly, this role may also grant other users access to the can-compute policy. This is because users who create workspaces are owners of those workspaces and are permitted to grant write access to those workspaces to any other user. Write access on a workspace includes the ability to launch batch jobs and notebooks.
• Notebook-user - may launch a notebook cluster
• Batch-compute-user - may create a batch job
  
  

Example

Below is a flowchart outlining a likely scheme. In this scenario, the head of a research laboratory (User #1) creates a billing project, generating an "Owner" policy for themselves. They proceed to generate a "Workspace Creator" policy for one of their post-doctoral fellows (User #2), charging them with the task of creating a fresh workspace to be shared with potential collaborators. The post doc creates the workspace (automatically generating their own "Owner" policy), adds some content, and then invites one of their coworkers (User #3) to help edit the content. When the invitation for access is sent, this generates a "Writer" policy to which the coworker is added. User #3 is can now edit and run code in the workspace, but cannot give other new users access.

In the meantime, a researcher from an unrelated group (User #4) - who wants introduce a team of students to Terra - creates a group, generating an "Owner" policy for themselves, and as many "Member" policies as they need. In order for the students (User #5, User #6) to access the workspace, User #2 must add the group created by User #4 to a policy for that workspace. In this case, the policy assigns the group a "Reader" role, meaning this is the role proscribed for all of the group's members (including the group's owner).

Note that all of these users are also on a multitude of public policies, not shown in this illustration.