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. Permissions are needed in order to have granted access to the data (except for the study owner that will always have access no matter what).

How it works

Permissions can be associated to almost any entry level except for user or project. Entries that can have permissions associated are studies (java bean), files (java bean), samples (java bean), jobs (java bean), individuals (java bean), cohorts (java bean), datasets (java bean) and disease panels (java bean).

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...).
UPDATE_*: Give permission to modify the parameters of that entry. This do not include permissions to modify variables, variable sets, annotation and/or annotation sets. Those actions will need additional permissions.
CREATE_*: Give permission to create that kind of entries within the study.
SHARE_*: Give permission to share that kind of entries and, therefore, authorise other users to access them.
DELETE_*: Give permission to delete that kind of entries.

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.
VIEW_FILE_CONTENTS or VIEW_CONTENT: Give permission to retrieve the contents 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.

In order to give permissions to a user at any entry level, first, that user must have permissions at the study level.

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:

The owner adds an ACL at study level for the user leaving empty the array of permissions.
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