Overview of projects & permissions
Benchling's permission system provides a way to control three things: who can take what actions on which data. These map to three kinds of objects in Benchling:
-
Teams and organizations are collections of users
-
Access policies are collections of actions that can be taken on an item
-
Projects are collections of data. Almost all items in Benchling are associated with a project, either by being associated with the project directly, or by living in a folder hierarchy under the project.
To grant access to data in Benchling, a user, team, or organization is added as a collaborator with a particular access policy to a project.
Example: Basic permissions on a project
Below is the settings page for an example project.
There are two sections here that grant permissions.
The owner has admin access to the project (meaning that they can edit permissions of the project itself, and take any action on any data associated with the project). If the owner is an organization (instead of a user), all users who are admins on that organization will have this access. All projects must have an owner (and on many tenants, that owner must be an organization).
The collaborators are other users, teams, or organizations that are assigned a specific policy. When they're interacting with data associated with that project, they'll only be able to take actions that are granted by that policy. In the example above:
-
Franklintx is the organization that owns the project. If the owner is an organization, the organization's members will automatically be given a policy on the project (although it can be set to NONE if desired). In this case, all members of Franklintx will be able to see all data associated with the project.
-
Gregor is a user. Adding a user as a collaborator will give that user the specified policy. In this case, Gregor will have the ability to edit all data associated with the project, except for the permissions of the project itself.
-
Purification Group is a team. Adding a team or organization as a collaborator does something special: it allows you to assign the team members one policy, and the team admins a different one.
-
In this case, all members of the Purification Group team have also been given the WRITE policy. Any member of that group will have the same permissions that Gregor has. This is a much more scalable way to assign permissions.
-
The admins of the Purification Group team have been given the ADMIN policy in addition to the WRITE policy. This will let them take administrative actions on the project (such as archiving it, changing the collaborators, or even changing the owner)
If a user ends up with multiple policies (for instance, if Gregor is a member of franklintx, he'll have been assigned both the READ and the WRITE policy), Gregor will get access to actions that any of the policies grant. More details can be found in the "Conflicting Policies" section of this article.
As mentioned above, this system relies on Organization Admins and Team Admins to grant additional privileges.
Customizing access policies
In the above example, we saw users assigned READ, WRITE, and ADMIN policies. These are the policies that Benchling comes with by default.
However, Benchling has a lot of data types, and each of those data types have a lot of properties. Users should be able to edit some of those properties, or take some actions, but not others. A simple READ vs. WRITE policy isn't enough control for more complex organizations. Now we'll see how to customize these policies, using actions.
Note: Only tenant admins are able to customize policies, since they are used by all organizations on the tenant. If you would like to be added as a tenant admin, please contact your IT administrator and Benchling Support. All users can see the current list of policies, and what actions each policy grants.
First, go to Feature Settings > Access Policies.
This shows a list of all access policies on your tenant. The defaults are Read, Write, and Admin, but you can add an unlimited number of these. Clicking on one will show you what actions the policy grants.
A policy is divided into sections, corresponding to the item type that's affected. The policy is always assigned at the project level (as we saw above), but it can affect different item types in different ways. For instance, a policy might grant read access to bioentities, but write access to notebook entries.
Each section has a list of actions that can be taken for that item type. These actions can either be “Granted” or “Not granted”. Some actions have an additional option, “Granted to author”, which is explained in more detail in the "Granted to author" section of the article. The first action for any item type is Read, and it is always granted. Currently, it is not possible to make a policy that grants read access to some item types, but not others.
After making changes, users are prompted to save them. Changes take effect immediately once they're saved.
How does Benchling determine access?
Now that we've covered how to create access policies beyond basic Read and Write, let's look at how Benchling uses them to grant access.
Whenever a user wants to take an action, Benchling takes these steps:
-
Find the item(s) that an action is being taken on
-
For each of these items, look up the project that's associated with it
-
Find all access policies that the user has on that project
-
Look up the action the user wants to take on those access policies (based on item type)
-
If any of the access policies grant the user the action, then the user may proceed with taking the action. If none of them do, the user may not.
Example: Enforcing permissions with custom policies
Here is our example project from earlier, now with more customized access policies:
Let's say that Gregor wants to open a plasmid in Benchling. The plasmid is in the “Example Project” project.
First, Benchling will determine if Gregor can see “Example Project” in the first place. Benchling will check if Gregor is a collaborator on the project, or if he's a member of a team or organization that's a collaborator. He's added as a collaborator directly, so he'll be allowed to see the project in Benchling, open it, and see all items in the project's folder hierarchy. Once Gregor opens the project, he'll be able to click on the plasmid to open it.
With the plasmid open, Gregor tries to edit the bases of the plasmid. Benchling will do the following:
-
Determine what items are affected by the action. In this case, it's just the plasmid.
-
Find what project controls the item's permissions. In this case, it's “Example Project”.
-
Benchling will find all policies that Gregor has on that project. Gregor is a member of the franklintx organization, but he is not a member of the Purification Group team. As a result, Benchling will see that he has the “Research Assistant” and the “Construct Designer” policies.
-
Benchling will look at those policies to determine if Gregor has been granted access to edit plasmid bases. First, Benchling checks the “Research Assistant” policy. Here is a screenshot from the config page:
Research assistants are not granted permission to edit sequence bases; the only edit action they can take is the one that lets them annotate and analyze the sequence. This action allows some cosmetic changes, but no changes to the underlying sequence data.
Benchling then opens the “Construct Designer” policy.
The “Construct Designer” policy is much more permissive; it allows Gregor to take just about any action with a sequence (the notable exception is editing the Registry ID itself, which is typically restricted to admins).
5. Because one of the policies that Gregor has grants him access to edit bases, Benchling allows him to take the action.
Granted to author
Some actions have more than “Granted” and “Not granted” available when creating a policy; they have an option called “Granted to author”. This allows users to take the action as long as they are an author on the item they are taking the action on. For instance, if Gregor had “Granted to author” access for editing sequence bases, he would be allowed to edit sequences in “Example Project” that he was the author on, but he wouldn't be allowed to edit other sequences in that project.
Conflicting policies
In many cases (including the above example), a user will have access to multiple policies that grant different levels of access. In all of these cases, the user takes the most permissive policy available. If a user has access to two policies on a project, one of which grants permission to edit entities, and the other which grants permission to edit notebook entries, the user will be able to edit both entities and entries in that project.