Overview

One of the most important features in Catalog is the ability to decide which users will have access to the data. This can be easily achieved thanks to the new Access Control List (ACLs) that have been defined, providing a fully customizable authorization mechanism.

Each member, either a user or a group, can have associated a list of predefined permissions that are needed in order to have granted access to the data. Permissions can be assigned to almost any entry level except for User and Project. The permissions that can be assigned can be divided into three different main groups:

Owner

The owner of a study will always be able to perform any action over the data contained in the study. The kind of actions that will only be possible to be performed by the owner are deleting the study and assign or remove users to/from the admins groups (next subsection).

Administrative groups

OpenCGA defines two reserved groups that will have some special behaviour.

Admins

Every Study in OpenCGA contains a special group called admins. This group will contain a list of users that will be able to do most of the administrative work the owner might want other users to do. Users belonging to this group will be able to perform almost any action except for the two ones that are only allowed for the owner of the study. Special operations that only these users will be able to perform are create/update/delete groups of users, create/update/delete variable sets and assign/remove permissions to other users/groups.

Members

Apart from admins, there is also an special group called members. Any user with any kind of granted access to the study will automatically belong to this group. The main aim of this group is to keep track of the users with any access to the study, but it also has other advantages such as:

• The admin users might want to predefine some permissions any member of a study will have. In such a case, admin users will just add new users to that group and those users will automatically be granted the permissions the group has.
• If an admin user wants to completely revoke any permission to one user, by removing that user from the members group, OpenCGA will automatically search for any permissions set for that user in any entity and remove it.

Other groups

Any other user belonging to other groups will be able to be granted the rest of permissions that are not for admins or owners.

Summary Table

Category	Permission	Users and Groups	Admins (users in admins group)	Owner
Study	Delete
	Create new admins
	Groups
	Variable Sets
	Set permissions (share)
Job	View, Write and Delete
File	View, Write and Delete
	View Header
	Download
Sample	View, Write and Delete
	Annotations (clinical data)
Individual	View, Write and Delete
	Annotations (clinical data)
Family	View, Write and Delete
	Annotations (clinical data)
Cohort	View, Write and Delete
	Annotations (clinical data)
Clinical Analysis	View, Write and Delete

How it works

Permissions can be associated to almost any entry level except for User or Project. Entries that can have permissions associated are Study, File, Sample, Job, Individual, Cohort, and Family.

A list of the basic permissions and their explanations can be found in the list below:

• VIEW_*: Give permission to access in read-only mode to the entry (study, file, sample...).
• WRITE_*: Give permission to create and update that kind of entries within the study. This do not include permissions to modify annotation and/or annotation sets. Those actions will need additional permissions.
• DELETE_*: Give permission to delete that kind of entries.
• *_ANNOTATIONS: In Sample, Individual, Family and Cohort we have three additional permissions to create, write or delete annotations in the same way it was described before.

Files deserve a special treatment as they not only exist in the database, but also physically in the file system. The special permissions added for files are the following:

• VIEW_FILE_HEADERS or VIEW_HEADER: Give permission to retrieve just the header of a file.
• DOWNLOAD_FILES or DOWNLOAD: Give permission to download the whole file.

The permission names might differ depending the entry they are related to. For instance, if we would like one user to have read-only permissions to all the files, samples, cohorts... the permissions VIEW_FILES, VIEW_SAMPLES, VIEW_COHORTS, etc should be set for the user. However, if we only want that user to have permission in just one file, sample or cohort, only the VIEW permission will be needed to that concrete file, sample or cohort.

ACLs are hierarchically read in order to determine the permission from a user over some data. Each entry of the ACL specify the actions that a set of users can perform with an specific resource. This set of users can either refer to a single user, a group or others.

• userName will define the ACL for a single user.
• groupName will define the ACL for a group of users.
• will define the default ACL for the rest of registered users for which no ACL was defined.

A basic diagram to decide whether a user has granted access to data or not can be seen below:

This process is used to check any permission except if it is a study permission directly (VIEWSTUDY, UPDATESTUDY...). In those cases, only the second and last part of the diagram will be applied checking if the user or the group where the user might belong to have that permission.

Templates

We have created three sets of predefined roles to give permissions to users to a Study, these are admin, analyst and view_only:

• admin: The user or group will be given full permissions to do anything.
• analyst: The user or group will be given full READ and WRITE permissions. Analyst members will not be able to delete or give permissions to other members.
• view_only: The user or group will be given full READ permissions. However, members with this "role" will not be able to manipulate or give permissions to other members.

Special cases

Permissions can be given to any concrete entity (file, sample, cohort...) to deny or grant access to just one concrete entry. This is always true except for a few exceptions in which we might propagate those same permissions to other entries:

Files

File entry might be of type file or folder. Permissions given to users to folder entries are propagated to all the children (files and folders) recursively.

In version 1.0.0-final, all permissions that might have had files and folders under the folder being given permissions will be modified according to the action being performed in the parent folder. In other words, if we are setting new permissions for the folder, any possible permissions the files and folders under the parent folder might have had will be completely replaced by the parent folder's permissions. However, if the action being performed is just adding a new permission to the parent folder, children files and folders will keep their old permissions plus the new one(s) added to the parent folder.

Individuals

Individuals are really strong related with samples. So every time permissions are given to an individual, the same permissions will be applied to all the samples corresponding to that individual according to the action being performed as described previously for files. (https://github.com/opencb/opencga/issues/509)

Use cases

Give public access to non-existing users

Catalog has one special user for this purpose called anonymous. Anytime a user tries to fetch anything and no session id is provided, Catalog will treat that user as anonymous. By default, only authorised users will have access to data. However, in order to make the data available to anyone without the need to log in, the study owner will need to add corresponding permissions to the anonymous.

Give access just to one specific sample

The actions to do this will be as follows:

1. The owner adds an ACL at study level for the user leaving empty the array of permissions.
2. The owner adds an ACL for that specific sample and user setting the permission the owner wants the user to have.

This way, the user will not have permissions to see anything in Catalog, just that specific sample.

Grant access to all the samples except for one

The actions to do this will be as follows:

1. The owner adds an ACL at study level for the user with all the permissions the owner wants for the samples.
2. The owner adds an ACL for that specific sample and user leaving empty the array of permissions.