Catalog Sharing
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.
Each member, either a user or a group, can have associated a list of predefined permissions. Permissions must be set in order to have granted access to the data (except for the study owner that will always have access no matter what).
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.
The order in which the permissions are checked is really important to determine the behaviour of the authorisation process. The process to verify if a user has a concrete permission in an entry different from study can be followed with the diagram below:
If some user has the VIEW_FILES permission set at study level, it will mean that the user will have read-only access to all* the files that are associated with that study.
Be aware of the different name of the permissions depending on whether they are stored at the study level or at the file level in this case. If we add the permission VIEW_FILE_HEADERS at the study level for one user, we will be giving access to that user to see the header of all the files stored in the study. However, the owner could decide that that user will not have access to see the header of any file except for one. In that case, VIEW_FILE_HEADERS should not be set for the study but for that concrete file. The name of the permission will not be VIEW_FILE_HEADERS but VIEW_HEADER as it is already related to one file. This is more explained with detailed examples below.