Catalog Authentication

Overview

OpenCGA Catalog is an authenticated environment. This means that a typical user would need to be authenticated in order to start working with it.

From the moment OpenCGA is installed the first time, the admin will need to define whether Catalog user registration is going to be public or private. If the admin defines a public user registration, any user with access to the webservices will be able to create their own user and start working. However, in many situations, the admin will decide to make it private, being only the admin who will have the rights to create new user accounts.

User creation

As for Release Candidate 1, the admin has two different ways of defining the account type of a user (FULL or GUEST). Basically, a user with a full member account will be able to define its own projects and studies, whereas a user with a guest member account will not. However, it is worth to mention that although users with guest accounts will not be able to define new projects, they will still be able to create new files, samples... if he/she has the proper creation permissions in other else's user study. The permissions are explained in Sharing and Permissions page.

There exists basically two different ways of defining new user accounts depending on the authentication system the user will be authenticated against.

Catalog

The most typical use case would imply creating new users that will be authenticated using our own authentication implementation. The admin will just have to use the admin command line to create a new user. In this case, the user information and user password will need to be provided. The password will be encrypted and safely stored in our database.

Import users from other authentication system

A different way of defining new users in Catalog would be using the import command line. This command line will basically connect to an external authentication* system (properties defined in the Catalog configuration file) and fetch the relevant user information in order to create a new user entry in our database. In this case, passwords are not asked nor stored in the database.

⚠️ *As for RC1, only LDAP system is supported. Other authentication systems might be supported in the future.

This command line will also retrieve the groups the users belong to and, only in the cases where the group already exists in the study the admin provides, the user will be also added in our database so our information is synchronised with the external information. 🚧 This concrete feature is under development and still not present in RC1.

Login system

Like it was mentioned in the overview, Catalog is an authenticated environment. Because users can only exist in Catalog itself but they could also come from other external authentication systems, we need to store each user's authentication method. This is stored in the user data model, in the account object. Catalog users will be authenticated using our implementation as we have the encrypted password stored. However, users coming from an external authentication system will be authenticated against it.

When the authentication is successful, a random 20-character token or session id is generated and provided. This session id will need to be used by the user to perform any action from that moment on.

⚠️ At this point, unless the user uses the java command line to perform any action, the sessions will be active until a proper logout has been done. We have added a method in the java command line to only allow sessions to be active for x minutes (by default, 2 minutes). If that time has been exceeded, the session will be closed calling the logout method. The amount of minutes inactive can be modified in the client configuration file.

Group definition

In order to make sharing things with other users easier, groups are also taken into account. Each group will contain a list of users belonging to that group and are defined at study level (see here). This means, that different studies could have defined the same group name but some users might belong to that group in one study and not in the other.

At first, only the study owner is allowed to create groups and add users to them. However, the owner, might also choose some users to be able to do this actions as well (authorisation page).

⚠️ As for RC1, a user can only belong to zero or one group maximum per study. This limitation will be removed in RC2 and users will be allowed to belong to as many groups as the owner or persons in charge decide.