Chapter 26. Managing Users

DOC allows granting users specific permissions over the application elements. For more details, refer to Section Setting Permissions.

Users are managed through Keycloak, which provides administrators with a centralized management interface.

Among other features, it allows LDAP, OIDC and SAML2 integration as well as single sign on and social networks authentication.

Keycloak mainly relies on the following concepts:

Roles, which represent types or categories of users.
DOC allows the definition of permissions for specific roles. It is highly recommended to assign access and permissions to roles rather than to users. Roles are the core concept in the security design. There can be 'functional' and 'technical' roles. For example, a user with the role "Planner" could be allowed to create a new plan, while a user without this role would not. For more details, refer to Section Managing User Roles.
Groups, which represent logical aggregations of users.
Groups will often mimic your internal organization. Groups provide ways to manage users: roles can be associated with groups then users added to this group will automatically inherit group roles. Groups are a Keycloak concept, which does not surface in the Application. For more details, refer to Section Managing User Groups.
Users, which are represent the entities that can log into the application.
They are the stakeholders of the system. They are used to defining a fine-grained security. A user can represent an end user or a component of the system. For more details, refer to Section Managing User Accounts.

Note that:

The Keycloak interface is only available if the application is running. For more details, refer to Chapter Building and Running the Application.
This Chapter focuses on Keycloak embedded user database configuration. Note that Keycloak comes with multiple documentation topics (installation, administration, customization, etc.). However, DOC developers should focus on the Server administration documentation for configuration information. For more details, refer to the official Keycloak Documentation.

1. Managing User Roles

Users are usually assigned roles, which are basically equivalent to tags and which can be leveraged in the definition of permission rules. For example, a user with the role "Planner" could be allowed to create a new plan, while a user without this role would not.

Permissions for each role can be configured from the web client. For more details, refer to Section Understanding the Permission Management View.

By default, the following roles are available:

API_KEY_ADMIN provides users with permissions to display, create and delete API keys for all users.
API_KEY_BACKOFFICE provides users with permissions to display, create and delete their own API keys.
APPLICATION_ADMIN provides users with all permissions on every application elements.
GENE_USER is the default role for users.
SESSION_TRACKING provides users with access to metrics about any user session via a dedicated endpoint. For more details, refer to Section Monitoring Active Sessions Using REST and Chapter Monitoring Activity.
SYSTEM provides users with all permissions on every DOC elements. Permissions for this role are not configurable from DOC web client.
PERMISSIONS_ADMIN provides users ACCESS and MODIFY on APPLICATION_PERMISSIONS, as well as permissions on all application elements. Permissions for this role are not configurable from DOC web client.

DOC relies on the roles SYSTEM, APPLICATION_ADMIN, API_KEY_ADMIN and API_KEY_BACKOFFICE, while GENE_USER and SESSION_TRACKING are predefined as a convenience to the application.

Procedure 26.1. To Manage User Roles in Keycloak

Connect to the Keycloak administration console on port 9090. For more details, refer to Section Accessing the Application Endpoints.
From the menu, click on Configure > Clients. The page Clients opens.
Figure 26.1. Selecting the 'gene-web' Client
Select gene-web. The page Clients > gene-web opens.
From the Roles tab, the buttons Add Role, Edit and Delete allow modifying the list of roles.
Figure 26.2. Checking the Content of the 'Roles' Tab

2. Managing User Groups

When managing users, groups should be created first and associated with their roles. In a second step, the users can be added to groups.

The following groups are predefined:

GENE_SERVICES group contains users that represent technical components of the system like the Backend Service, Data Service, or Execution Service. This group is required for DOC to function.
GENE_USERS group is provided as a commodity and is typically meant to contain all the end users of the system.
GENE_ADMINS group is provided as a commodity and is typically meant to contain the sub part of the group GENE_USERS that needs the PERMISSIONS_ADMIN, API_KEY_ADMIN and APPLICATION_ADMIN roles.

Procedure 26.2. To Manage User Groups from Keycloak

Connect to the Keycloak administration console on port 9090. For more details, refer to Section Accessing the Application Endpoints.
From the menu, click on Manage > Groups. The page User Groups opens.
From the Roles tab, the buttons New, Edit, Cut, Paste and Delete allow modifying the list of groups.
Figure 26.3. Listing the Available Groups
To add roles to a group:
1. From the page User Groups, select a group in the list and click on Edit. The page Groups > <group-name> opens.
  Figure 26.4. Editing the Given Group
2. In the Role Mappings tab, select gene-web in Client Role.
  Figure 26.5. Mapping the 'gene-web' Client Role
3. Select a role from the Available Roles and use the button Add selected to add them to the Assigned Roles for the group. Another button allows to Remove selected roles from the Assigned Roles.
  Figure 26.6. Adding Selected Roles

3. Managing User Accounts

User accounts allow specific accesses to the application elements depending on their roles.

By default, the Keycloak configuration of the application defines the following users:

gene_admin, with all available roles. For more details, refer to Section Managing User Roles.
Specific roles are recognized by the permission system and assigned by default to the gene_admin.
Note that:
- PERMISSIONS_ADMIN role allows to edit permissions, which prevents locking all users out of the application due to a misconfiguration of permission rules.
- APPLICATION_ADMIN role allows users with this role to perform application administration tasks, such as exporting and resetting application configuration, or running job-cleaning task.
These roles are also assigned, by default, to members of the user group GENE_ADMINS. For more details, refer to Section Managing User Groups.
user1, user2, user3, and user4 with the role GENE_USER.

Finally, the mandatory system role and users are defined in the default configuration.

The default configuration of an application defines a role named SYSTEM and four users with (only) this role, named backend-service, data-service, execution-service, and scenario-service. These users correspond to the microservices of the application and are used to authenticate REST calls between microservices. They are mandatory for the application to work, but they do not surface in the permission rules. The names and passwords of these four users must coincide with the ones defined in the application.yml files of the corresponding microservices, under the spring.application.name and spring.application.keycloak-password properties.

In the default configuration, the SYSTEM role is assigned to these four users through a group. That is, a Keycloak group named GENE_SERVICES is defined, the SYSTEM role is actually assigned to this group, and the four system users are set to belong to the group. The same principle is used to assign roles to the other users.

When you define your users and roles, the only requirement is the system role and users described above. However, as in the default configuration, you may want to assign the PERMISSIONS_ADMIN and APPLICATION_ADMIN roles to at least one user.

Note that, when managing users, groups should be created first and associated with their roles. In a second step, the users can be added to groups.

You can find the official Keycloak documentation about group management here.

To list the available users in the system, click on the "Groups" menu.

Figure 26.7. Listing the Available Groups

To delete a user, click on the associated button.

Figure 26.8. Deleting a User

Defining a user requires going through three steps: user creation, credentials configuration and group association.

Click on the "Add user" button in the "Users" page.

Figure 26.9. Adding a User

Then the only field that is mandatory is the username. Once filled in, just click on the "Save" button.

Figure 26.10. Typing a Username and Clicking on Save

The new user is created and its credentials must be defined to allow a real user to log into the application. Set temporary credentials by filling in the credentials form. Leave the temporary option enabled and then click on the "Set Password" button.

Figure 26.11. Filling in the Credential Form

Once a user has been created, its credentials can be edited at any given time. For more details, refer to Section Configuring User Credentials.

Join the user into the "GENE_USERS" group in the "Groups" tab.

Figure 26.12. Joining the GENE_USERS Group

4. Importing and Exporting User Data

From the administration console, select the "Export" page. Check options "Export groups and roles" and "Export clients" before clicking on "Export" to download the configuration.

Figure 26.13. Exporting the Keycloak Configuration

A file realm-export.json is generated that contains all the configuration.


	Note that users and groups that are not part of the imported configuration are left untouched. Realm and client information is overridden.

Select the file to import.

Figure 26.14. Selecting the Configuration File

And configure the "overwrite" option.

Figure 26.15. Configuring the Import


	These roles are also assigned, by default, to members of the user group `GENE_ADMINS`. For more details, refer to Section Managing User Groups.