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 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 two sets of predefined permissions to give permissions to users in a study. This way, if the owner of a study wants to give all the permissions to a member, it will have to add the parameter templateId with the value admin. However, if the owner wants to give all the permissions except for the deletes and shares, it will have to put the value analyst.

This could be understood as if they were roles, but they are no more than a kind of shortcut to give users permissions. An analyst will be then able to create, view and update anything, but never to delete and share anything with any user.

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 the data. However, in order to make the data available to anyone without the need to log in, the study owner will have to add an ACL for the user anonymous setting any permission he/she might want the community to have.

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