Molgenis Auth Manual

Short manual on how to use the Molgenis Auth module.

General Setup

In order to use authentication and authorization with Molgenis add auth.xml to your data model. Example:

model_database = handwritten/datamodel/shared/core.xml,\

handwritten/datamodel/shared/auth.xml,\

handwritten/datamodel/shared/organization.xml

Regenerate your project and update your database tables using the UpdateDatabase class. Example:

new Molgenis(“handwritten/apps/org/molgenis/myproject/myproject.properties”).updateDb(true);

Updating the database creates the following entities in your database:

MolgenisRole

A role is a function that a user or group fulfils. Both the MolgenisUser and MolgenisGroup tables extend the MolgenisRole table, meaning that role names might be the name of the individual him/herself or the name of a group. If role names are important in your application, you can always use groups and add the appropriate persons to that group.

MolgenisUser

This table represents a Molgenis user and their personal information. The superuser field indicates whether the user is allowed access to everything: every table, every row, every screen, and this user may also add/remove all permissions for all users. This field should be used with utmost care.

MolgenisGroup

This table represents a Molgenis group, which one or more users can belong to. Groups make it easier to share permissions to a team or set of individuals with the same needs.

MolgenisUserGroupLink

A table handling the many-to-many relationship between MolgenisGroup and MolgenisUser. Molgenis provides an mref which normally handles m2m relationships but the auth developers wanted to be able to access this table from both sides of the m2m, thus chose to create an explicit table.

MolgenisEntity

This table represents a MolgenisEntity, for example a 'Protocol' or an 'ObservedValue'. This table is used to define table-level security, and is automatically filled with all entities in your datamodel during generation.

MolgenisPermission

This table represents a permission, which consists of a MolgenisRole, a MolgenisEntity, and the type of permission (read, write, execute, own). The permissions can be looked at as a hierarchy, thus someone with 'write' access also has 'read' access. Someone with 'own' access can do everything: add/delete other permissions on that entity, for example, in addition to write and read access.

Authorizable

This is an interface that is used to implement row level security. It has three fields: 'canRead', 'canWrite', and 'owns'. Tables wanting row-level security should implement this interface.

Authentication

Molgenis currently offers two ways of authentication: DatabaseLogin and OpenIdLogin. DatabaseLogin allows to store the login information in the local database while the OpenIdLogin uses a third party for checking the credentials. Currently supported providers are Google and Yahoo. In order to use one of the authentication modules add a further line to the properties file of your project.

auth_loginclass = org.molgenis.auth.DatabaseLogin

or

auth_loginclass = org.molgenis.auth.OpenIdLogin

Authorization

Molgenis allows for security on table-level, row-level and for security on screens.

Table level security

Table level security is managed by the MolgenisPermission table.

A Permission Management Module was made for normal (non-admin/non-superuser) users to access and manage their permissions. The Module consists of a plugin that shows all permissions for a user, and a seperate form that shows all permissions for all users on entities that the current user owns. Currently there is no filtering for either of these forms, but the intention is to create filtering in the future. In order to use the permission management module add the following to your ui model:

<plugin name="PermissionManagementPlugin" type="org.molgenis.auth.service.permissionmanagement.PermissionManagementPlugin"/>

Furthermore the tables described above can be used directly in order to perform Molgenis security. By default these tables are only visible to the superuser. They can be included in the ui model:

<plugin name="UserLogin" type="org.molgenis.auth.ui.UserLogin" label="Login"/>

<menu name="Management">

<form name="MolgenisUser" entity="MolgenisUser"/>

<form name="MolgenisGroup" entity="MolgenisGroup"/>

<form name="MolgenisUserGroupLink" entity="MolgenisUserGroupLink"/>

<form name="MolgenisPermission" entity="MolgenisPermission"/>

</menu>

Row level security

In order to use row level security on an entity, it has to implement the Authorizable interface. Implementing this interface the entity receives three extra fields: canRead, canWrite, owns. Upon inserting a new row into the table these fields can be used to specify a person or group with certain permissions. The user inserting the new row becomes automatically the owner of that row.

It's important to note that all authorizable fields are xrefs, and not mrefs. So if user mswertz has canRead on OntologyTerm?, then no one else can. If you want multiple people on a permission, then you'll need to make a group. Then mswertz and rwagner can both be in group “Team Awesome”, and have canRead on OntologyTerm?.

Example:

<entity name="TestClass" implements="Authorizable">

<field name="id" type="autoid"/>

<field name="testField"/>

</entity>

Screen level security

Screen level security is achieved in the same way as table level security (see above).

Technical Details

Backend (Database) Tables

A number of tables were made to support the Authorization system.

Service Package

The Molgenis Suite already has a Login interface and a SimpleLogin class, which is the default login for molgenis applications. The interface provides methods such as !isAuthenticated, !isLoginRequired, !canRead, !canWrite, etc. SimpleLogin just returns true for most of these methods, allowing all users access to everything.

To implement the auth package, a new login was created, DatabaseLogin. Some interesting information about overridden methods from the Login interface:

• !isAuthenticated() now checks to see if MolgenisUser is set (if null, no one is authenticated).
• Login() checks the MolgenisUser? table for matching username and password.
• A map of all permissions is kept locally to speed up checking, and is loaded by calling loadPermissions(). This is also called on reload().
• canRead(), canWrite() all check the map to see if the given action is allowed for the given user. canRead() and canWrite() are implemented for table and row level security. canRead() is additionally implemented for screen-level security.

OpenIdLogin allows users to use the popular OpenId to log in, i.e. using their google account or yahoo login. This class extends DatabaseLogin and has some extra methods to achieve authentication.

An AuthorizationEmailService was created to send emails to new users, this extends the SimpleEmailService.

Util Package

A PasswordHasher.java was created with one method, toMD5(), which converts a password to MD5 for security. Eventually we'd like to make the system more secure by using extra mechanisms when encrypting (salting?).

VO Package

The vo package contains one class, UserLogin, which handles all the user login related forms. (i.e. getters and setters for all forms).

Form Package

All of the auth forms use the “new” way of creating screens, i.e. freemarker-less.

• DatabaseAuthenticatonForm provides a screen for logging in and logging out.
• ForgotForm provides a screen for getting a new password (i.e. you remember your username but have lost your password, you can request that a new password is sent to you.
• OpenIdAuthenticationForm provides a screen for logging in and out with OpenId?.
• RegistrationForm provides a screen for registering yourself in the molgenis system.
• UserAreaForm provides a screen for changing user details.

UserLogin.java is a plugin that is also located in the auth package, and this plugin is the controller for all auth screens to do with logging in, personal details, forgotten password, etc. The only thing that it does not handle is the Permission Management Screens, and the Molgenis generic forms. Thus, it handles log in and long out requests, add new user requests, change details request and forgotten password requests. UserLogin has a matching ftl that handles the UI.

PermissionManagementModule

The PermissionManagementModule consists of four classes, a plugin, a module, a service, and a freemarker template.

ToDo's

We are still working on proper facilities for managing row-level security (something like PermissionManagementScreen) but for now, it can be done through the standard Molgenis forms, assuming that the user has the right access.

Furthermore, there is no permission request system in place yet, so users need to rely on external resources (email, telephone, face-to-face) in order to ask admins/owners of entities for permission.