Defining user roles and hierarchy

Owned by Marcin Kubala (Unlicensed)
Last updated: May 08, 2014 by Krzysztof Nadolski

Qcadoo Framework by default provide 3 roles (with related groups) and predefined hierarchy:

ROLE_SUPERADMIN > ROLE_ADMIN > ROLE_USER

Since v1.2.1 you can add your custom roles and modify roles hierarchy.

Glossary

  • user role - role, used for authorization
  • user group - Group has one or more roles. Each user belongs to one related user group.

Adding roles and modifying hierarchy in two steps

First step - prepare security.properties

All user roles management can be done by creating security.properties in application resources directory (<application-sources-dir>/src/main/resources/security.properties).
Presence of the security.properties file is unnecessary when default roles and they hierarchy are sufficient for you.

Because contents of security.properties override the defaults, you have to include also declaration for default roles (mentioned in first section).

Template

Here is an template of security.properties, containing default hierarchy definition (hint: read the ">" sign as "includes"):

rolesHierarchy = ROLE_SUPERADMIN > ROLE_ADMIN \n \
                 ROLE_ADMIN > ROLE_USER

Explanation of the above:
In effect every user with ROLE_SUPERADMIN has also priviledges given to ROLE_ADMIN and ROLE_USER,
every user with ROLE_ADMIN has (besides its own) also priviledges of the ROLE_USER,
every user with ROLE_USER has only its role

Be careful when using new line symbols in *.properties files. If you need to put new line inside property value (as in example above) you have to type '\n \' on end of line. Otherwise second line will be treated as independent properties entry.

Second step - define user groups

You have to create exacly one role for each newly added, non-default role using 'Role module'.
I recommend keeping all custom roles declarations in one, the most basic plugin or even create new specialized plugin and put them as a dependency of the basic plugin.

Example

Let's see some example, we want to add new role which will be representing auditors. Suppose that auditor should have at least the same priviledges as regular user, but not so wide as an administrator.

First create src/main/resources/security.properties file inside application source directory (for example: mes-application/src/main/resources/security.properties) with following contents (don't forget about default roles!): 

rolesHierarchy = ROLE_SUPERADMIN > ROLE_ADMIN \n \
                 ROLE_ADMIN > ROLE_AUDITOR \n \
                 ROLE_AUDITOR > ROLE_USER

Next define role in xml. Choose most basic plugin, in my case (Qcadoo MES) this will be mes-plugins-basic. Append following declaration into qcadoo-plugin.xml:

<security:role identifier="ROLE_AUDITOR"/>

We can also define new group with this role.

<security:user-group name="auditors" identifier="AUDITOR" roles="ROLE_AUDITOR"/>