# Authentication and Authorization

# Introduction

Authentication is the process of ensuring that a user is who the user claims to be, while authorization pertains to checking whether the authenticated user is allowed to perform a certain action. Authorization is managed using role-based access control (RBAC). Permissions that define access control are assigned to roles, which are in turn assigned to users.

Hume has the following auth providers, that can perform user authentication and authorization:

Native Auth provider

Hume provides a native auth provider that stores user and role information in the Hume application database. This option is controlled by the parameter hume.security.provider which is set to native by default.

Keycloak Auth provider

Hume provides an integration with Keycloak (opens new window), an open-source Identity and Access Management sponsored by RedHat.

This integration provides Single-Sign-On and User Federation (LDAP, Kerberos) capabilities.


# Terminology

This section describes the terminology used in the manual.

# Permissions

Permissions define the access control a Role has on particular objects. They are granted to roles during the lifecycle of the application. Permissions can also be representend as groups, in order to ease the assignment. Permission Groups and Permissions are specific for particular object types, for example the visualisation_create permission cannot be granted on Skill objects as well as you cannot create a PermissionGroup that groups permissions for different object types.

# Roles

A Role groups Permissions or PermissionsGroup together. Users are assigned roles.

# Users

A User is represented by an identity and this identity is assigned roles.


# Built-in Roles

Hume ships with the following built-in Roles and Permission Groups :

ROLES

  • ADMINISTRATOR
  • SYSTEM_INTEGRATOR
  • RESOURCE_MANAGER
  • SKILL_MANAGER
  • KNOWLEDGE_GRAPH_MANAGER

PERMISSION GROUPS

  • EXPLORER
  • OFFICER
  • MANAGER

# Hume Access Control Mechanisms

Hume’s access control mechanism is based on the Role Based Access Control (RBAC) paradigm. RBAC assigns rights based on the functions or tasks of people. It generally works better in environments in which control of access to resources or information is required and where the number of users, information types or variety of resource is large.

In the Hume context, RBAC provides an access solution that balance the following forces:

  • In most organizations people can be classified according to their role, function or tasks.
  • Common tasks require a similar set of rights.
  • It is necessary to help organizations to define precise access rights for its members according to a need-to-know or need-to-do policy.

This coarse grained control mechanism has been mitigated by Hume via resource specific access control mechanisms that apply to each object to be protected.

Hume RBAC is modelled using the following concepts:

  • User: it represents a registered user;
  • Role: it identifies a specific user’s role in respect of what he or she can do on the platform.
  • Right or Permission: It defines the access type (read, write, edit, etc.) the subject is allowed to perform on the corresponding object (a Protection Object).
  • Group of Permissions: it defines a group of permissions in order to help the user to access a Protection Object in different ways.
  • Protection Object: It represents the object (resource, information, and so on) to be protected.

Users are assigned to roles, so no user is assigned directly to permissions without a role in the middle. Roles are given rights on protection objects or on class of objects. Each user must have a set of roles to operate over the Hume Ecosystem. These roles will determine the list of permissions a user has on which resource or class of resources. The list of permissions is available at the Appendix A.

A role can be a composite role, which means that it contains, apart from a list of permissions (that can be empty), a list of sub-roles.

Hume distinguishes between two types of Roles:

  • Built-In Roles: These are roles that control main functionalities of the system such as: managing users, creating resources and skills, creating and managing knowledge graphs. These roles belong to the platform and they are shipped with it, they cannot be changed neither in terms of names nor in terms of permissions. For example, RESOURCE_MANAGER can manage (create, delete, edit, view) all the resources (like neo4j connections, s3 buckets, and so on) in the system.
  • Custom Roles: These are roles created ad hoc, by administrators, to grant permissions to groups of people to a specific set of resources. Custom roles are created by composition of Built-In Roles and/or other custom roles. For example a role called DOCTOR will be able to access only certain knowledge graphs.

To allow a restricted group of users to access a specific resource in the system (e.g. a Skill) an administrator can create a custom role (e.g. DOCTOR), assign it to these users, then link the new custom role to a proper group of permissions (e.g. SKILL_USE) that allow users to act on the resource.

# Built-In Roles

Built-In Roles are roles that are released with the platform and control main tasks in the systems.

Role Description
USER This role is necessary to allow users to log in the platform.
ADMINISTRATOR This is the highest role in the platform. A user with such a role can do everything.
SYSTEM_INTEGRATOR This role identifies the system integrator which is responsible to configure resources (such as connections to neo4j database, to s3 buckets, and so on) and skills (such as extract entities, text rank, and so on).
RESOURCE_MANAGER A user with this role can fully manage the resources.
SKILL_MANAGER A user with this role can fully manage the skill.
KNOWLEDGE_GRAPH_MANAGER This role identifies the users that deal with knowledge graphs creating them from scratch.

The roles described are defined via a set of sub-roles or a set of permissions or both. The full hierarchy is available in the Appendix B.

# System Groups of Permissions

Group of Permissions Target Description
RESOURCE_USE Resource It allows users to access the resources. For example, during a workflow creation.
SKILL_USE Skill It allows people to use the skills. For example, during a workflow creation.
MANAGER Knowledge Graph It which allows users to get full management access to a specific knowledge graph.
OFFICER Knowledge Graph It allows users to explore, which means access to a specific knowledge graph, run workflows (not changing them), creating visualizations.
EXPLORER Knowledge Graph It allows users to just have a look at the content of a knowledge graph creating visualizations on top of it.

The groups of permissions described are defined via a set of sub-roles or a set of permissions or both. The full hierarchy is available in the Appendix B.

# Custom Roles

Custom Roles are roles created ad hoc by administrators to represent types of users that will use the platform. These roles are particularly useful when it is necessary to create a group of people that must have specific access as in the case you have users connected via single sign on from an external system.

# Custom Permissions Groups

Custom Permissions Groups are created ad hoc by administrators to put together various permissions freely. Creating a permission group an administrator must select the target type (e.g. Resource, Skill, Knowledge Graph).

# Single Sign On

Hume provides Single Sign On (SSO) features via integration with Keycloak. Keycloak is an open source identity and access management solution. It is used in Hume as the reference Single Sign On platform when a customer do esn’t want to store any personal information about the users locally in the Hume instance. The advantages of this configurations are:

  • A centralized platform for managing users;
  • Easy support for many existing users management platforms or protocols such as LDAP, Kerberos, and so on.
  • A more secure user management since the users’ details and password are stored and managed following the highest standard in terms of security.

Hume requires Keycloak to be configured properly to work as an identity and access management platform for it. The configuration required can be summarized in the following way:

  • Configuring a Realm
  • Configuring a Keycloak client
  • Creating main Administrative Roles
  • Creating Users
  • Enabling them on the Client
  • Creating an Administrator
  • Creating and assigning Custom Roles

# Configuring a Realm

As first thing, Keycloak requires the administrator to set up a new Realm. A Realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control. The real creation is performed by clicking on the label below the Keycloak logo on the top-left part of the page.

What is necessary to specify is just a name and if it is enabled after the creation. In the next screen the Hume Realm is created.

Realm creation

After the creation of a realm it is possible to edit the settings. In the Hume case no special settings are required. The default configuration satisfies Hume requirements.

Realm settings

All the next steps are accomplished in this Realm that become the reference for the Hume installation. In particular, it is worth noticing here that all the users are defined in this context.

# Configuring a Keycloak Client

Once the Realm is set, Keycloak requires you to configure a client for each platform that will use it as an SSO tool. Clients are entities that can request Keycloak to authenticate a user. Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution. Clients can also be entities that just want to request identity information or an access token so that they can securely invoke other services on the network that are secured by Keycloak.

To configure a new client, as the Keycloak administrator, open the Client page and select “Create” to create a new Client.

New client creation 1

A few information are required at first stage to create a new client:

  • Client ID: A unique identifier of the new client platform. In Hume case can be, for example, hume-web;
  • Client Protocol: Specifies how the authentication will be performed. Select open-id connect. 'OpenID connect' allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server.
  • Root URL: Specifies the url to append to all the relative urls. Leave it empty.
New client creation 2 New client creation 3

Click on Save and the new client will be created. It is possible to edit the configuration clicking on the edit button or on the name of the client.

Client configuration 1

Review the configuration settings from there.

Client configuration 2

At this point it is necessary to define a list of roles related to the current client.

# Configure the Built-In Roles on Keycloak

The next step consists in the creation of the roles defined for the specific client. These defines the set of roles that users allowed on this client can be assigned to and they will be the roles that will be mapped on Hume roles once the user will login.

Depending on the level of details the administrator would like to use in user management this list can change. The following roles MUST be created to map with key roles on Hume:

  • USER
  • ADMINISTRATOR
  • SYSTEM_INTEGRATOR
  • RESOURCE_MANAGER
  • SKILL_MANAGER
  • KNOWLEDGE_GRAPH_MANAGER

They correspond to the highest level roles available in the Hume platform.

In order to create them from the Edit page of the hume client select the Roles tab. To add a new Role click on “Add Role”

Roles tab

By clicking the “Add Role” button on the upper-right side of the roles table, the following form will appear.

New role creation

Add the name, if you prefer also a description and click on save.

At this stage, it is necessary to create all the roles as in the table. Later we will add specific roles to handle specific needs. These roles now have the scope to support all the administrative tasks necessary to bootstrap the application configuration. Later the custom roles are presented and they supports the day by day work.

# Users Management

Hume, when configured with an external identity management platform, is shipped without default local users. All the users MUST be created on Keycloak. Keycloak manages all the users can access to the platform. It allows administrators to create, edit and delete users.

That means that the next step consists in creating the first basic set of admin users and assigning the proper roles to them.

Selecting “Users” on the left panel, the users administration interface appears and it looks like the following.

Users administration

The first user you have to create is the user that manages the Hume platform: the Hume administrator. In the screen above it has as username administrator.

# Create a user

Each user is recognized by a user name, that is the only mandatory field.

User creation

Note the tag in the Required User Actions: “Update Password”. It specifies that the user will be asked to change the password at the first login.

# Edit a user

After the creation, which allows the admin to set up minimum set parameters, the users can be edited. In particular it is possible to reset, change the credentials in the case the user forgets the password.

User editing

From this interface it is also possible to manage the roles a user has on a specific client. In order to properly manage the roles it is necessary to understand the access control mechanisms provided by Hume.

# Managing Users and Roles with Hume and Keycloak

In order to allow users to access and operate in Hume it is necessary to assign Keycloak users after the SSO with specific roles on the platform. In this case it is possible to use both System and Custom roles for the scopes.

The mapping between the Roles assigned by Keycloak to the users and the roles on Hume is based on name match. A role ADMINISTRATOR on Keycloak is matched with ROLE_ADMINISTRATOR once the user will log in the platform.

In order to allow users to access and operate in Hume it is necessary to assign Keycloak users after the SSO with specific roles on the platform. In this case it is possible to use both System and Custom roles for the scopes. The mapping between the Roles assigned by Keycloak to the users and the roles on Hume is based on name match. A role ADMINISTRATOR on Keycloak is matched with ADMINISTRATOR once the user will log in the platform.
As the first task it is necessary to create an Administrator that can deal with the administrative tasks necessary to manage the whole ecosystem provided by Hume.

# Create the administrator on Keycloak

The first user to be created must be an administrator since such user will be able to administer the Hume platform.

In order to do so, once the user has been created in the user detail panel, select the Role Mappings tab. In the Client Roles combo box select the client created for hume (hume-web in our examples). The list of roles allowed for that client will appear (see the step before) and from the list select ADMINISTRATOR and click on “Add Selected”.

User's roles editing

At this point the administrator has been created. Let’s try now to login on the platform. Opening the Hume url the system will automatically redirect the users to the Keycloak login page that will appear like the following.

Login

The first time the system will ask the user to change the password (if you specify the specific tag with such action).

Change password

Once inserted the username and password (and eventually changed the password) the user will be redirected to the hume homepage.

Hume homepage

Clicking on the icon on the bottom left and then on “My Profile” the user is able to verify the list of permission. In the case of an administrator it should look like the following.

Permissions list

From this page it is possible to change the password. Clicking on the “Change Password” button the user is redirected to the Keycloak page of the change password. The list of permissions can change as the platform evolves with new features that have to be properly protected. Once checked that in the list of Roles appears ADMINISTRATOR it means that the configuration has been fully achieved. The administrator has logged in and has been recognized on the Hume platform.

As an administrator now it is possible to manage the whole platform. Nevertheless, it would be the case to create other users with key roles such as system integrator, knowledge graph manager and so on.

# Assign a System Role to a user

The approach necessary for assigning all the Built-In Roles to a Keycloak user follows the same approach as for the administrator change just the value selected for the role as in the next screenshot.

Roles panel

In this case it has been assigned the role of System administrator to the user alessandro.

# Create a custom Role

There are cases in which the Built-In Roles don’t satisfy the requirements of minimum access for a user or a group of users. Custom roles play a key role in defining groups of responsibilities. More in details a custom role has to be used when the administrator would like to:

  • Assign a custom set of permissions to a group of users
  • The set of available roles doesn’t cover a specific need

Suppose that in your company you have doctors that should be able to create and manage knowledge graphs with full access to all the patient data and researchers that can access specific knowledge graphs and related visualizations but cannot start any workflow.

As administrator, you can create new roles on Hume by clicking on the “Access Management” icon.

Access management button

The Role Management interface will appear where you can create a new role clicking on “Create Role”.

Roles panel

Then it is necessary to create the two new roles

New role 1 New role 2

They will appear now in the list.

New roles

At this point, as administrator on Keycloak, it is necessary to create the two new roles. From the hume-web client select the tab “Roles” as done for creating the administrative roles and add the two new roles:

New role on Keycloak 1 New role on Keycloak 2

They will be automatically mapped to the roles created on Hume due to the name matching, so be careful to avoid misspelling or typos.

At this point it is necessary to assign roles to the users on Keycloak, selecting the users who should receive the Doctor roles and assign them the right set of roles as in the following example.

Assigning roles to user 1

The doctors receive then the roles DOCTOR, KNOWLEDGE_GRAPH_MANAGER and USER. Note how also the USER role has to be assigned. This is very useful when it is necessary to disable temporarily the user without removing the full list of roles.

For the researchers, instead, the list of roles are: RESEARCHER, USER. The following image shows an example.

Assigning roles to user 2

Doctors at this point can log in, create knowledge graphs and get access to all the resources and skills they have access to. By default Doctors cannot access any resource or skill so it is necessary to give them access to proper objects to accomplish their job. This has to be done by an ADMINISTRATOR, a SYSTEM_INTEGRATOR, a RESOURCE_MANAGER or a SKILL_MANAGER.

After the creation of a resource the doctors can access to, the resource manager has to grant proper rights to the DOCTOR role as in the following image:

Granting access to a resource

The same can be done for all the resources and skills doctors have to use for their purposes.

At this point all the doctors can create knowledge graphs, use Orchestra for creating workflows and visualize their data.

Researchers cannot do anything yet. The doctors, once they create the knowledge graph, can assign rights on their knowledge graphs as follows. From the list of knowledge graphs clicking on the “Edit” icon it is possible to change the access rights on the selected knowledge graph.

Granting access to a knowledge graph

The doctor, owner of the knowledge graph, can decide the set of rights to assign to the researches for the specific knowledge graph. For the details, see the Appendix B.

At this point researchers can access the knowledge graph and operate on them.

# Appendix A - List of permissions

In order to assign the right set of roles to the users, it is critical to understand what are the low level permissions on top of which the roles are built. The following list contains the full set of permissions currently available in the system. They control all the critical operations on the platform.

Permission Name Description
CUSTOM_ROLE_CREATE This permission allows users to create custom roles.
CUSTOM_ROLE_DELETE This permission allows users to delete custom roles.
CUSTOM_ROLE_UPDATE This permission allows users to edit custom roles.
CUSTOM_ROLE_VIEW This permission allows users to access the list of available custom roles.
ECOSYSTEM_ACCESS This permission allows users to access the ecosystem area.
KNOWLEDGE_GRAPH_ACCESS_GRANT This permission allows users to grant the KNOWLEDGE_GRAPH_* permissions they have to other users.
KNOWLEDGE_GRAPH_CREATE This permission allows users to create knowledge graphs.
KNOWLEDGE_GRAPH_DELETE This permission allows users to delete knowledge graphs.
KNOWLEDGE_GRAPH_UPDATE This permission allows users to edit knowledge graphs.
KNOWLEDGE_GRAPH_VIEW This permission allows users to access in read only mode to knowledge graphs.
RESOURCE_ACCESS_GRANT This permission allows users to grant the RESOURCE_* permissions they have to other users.
RESOURCE_CREATE This permission allows users to create resources.
RESOURCE_DELETE This permission allows users to delete resources.
RESOURCE_UPDATE This permission allows users to edit resources.
RESOURCE_VIEW This permission allows users to access in read only mode to the resources.
SCHEMA_INDEX_MANAGE This permission allows users to manage the index schema.
SKILL_ACCESS_GRANT This permission allows users to grant the SKILL_* permissions they have to other users.
SKILL_CREATE This permission allows users to create skills.
SKILL_DELETE This permission allows users to delete skills.
SKILL_UPDATE This permission allows users to edit skills.
SKILL_VIEW This permission allows users to access in read only mode to skills.
VISUALISATION_CREATE This permission allows users to create visualisations.
VISUALISATION_DELETE This permission allows users to delete visualisations.
VISUALISATION_UPDATE This permission allows users to edit visualizations.
VISUALISATION_VIEW This permission allows users to access in read only mode to visualisations.
ACTION_CREATE This permission allows users to create actions.
ACTION_DELETE This permission allows users to delete actions.
ACTION_UPDATE This permission allows users to edit actions.
ACTION_VIEW This permission allows users to access in read only mode to actions and run them.
WORKFLOW_CREATE This permission allows users to create workflows.
WORKFLOW_DELETE This permission allows users to delete workflows.
WORKFLOW_UPDATE This permission allows users to edit workflows.
WORKFLOW_VIEW This permission allows users to access in read only mode to workflows.

# Appendix B - Roles Hierarchy

Role Sub-roles/permissions
ROLE_ADMINISTRATOR ROLE_SYSTEM_INTEGRATOR
ROLE_KNOWLEDGE_GRAPH_MANAGER
SYSTEM_INTEGRATOR RESOURCE_MANAGER
SKILL_MANAGER
RESOURCE_MANAGER RESOURCE_USE
RESOURCE_CREATE
RESOURCE_UPDATE
RESOURCE_DELETE
RESOURCE_ACCESS_GRANT
USER_VIEW
ECOSYSTEM_ACCESS
RESOURCE_USE RESOURCE_VIEW
SKILL_MANAGER SKILL_USE
SKILL_CREATE
SKILL_UPDATE
SKILL_DELETE
SKILL_ACCESS_GRANT
USER_VIEW
ECOSYSTEM_ACCESS
SKILL_USE SKILL_VIEW
KNOWLEDGE_GRAPH_MANAGER KNOWLEDGE_GRAPH_USE
KNOWLEDGE_GRAPH_CREATE
KNOWLEDGE_GRAPH_UPDATE
KNOWLEDGE_GRAPH_DELETE
KNOWLEDGE_GRAPH_ACCESS_GRANT
USER_VIEW
SCHEMA_INDEX_MANAGE
KNOWLEDGE_GRAPH_USE KNOWLEDGE_GRAPH_VIEW
WORKFLOW_USE WORKFLOW_VIEW
WORKFLOW_MANAGE WORKFLOW_USE
WORKFLOW_CREATE
WORKFLOW_UPDATE
WORKFLOW_DELETE
VISUALISATION_CREATE VISUALISATION_CREATE
VISUALISATION_USE VISUALISATION_VIEW
VISUALISATION_MANAGE VISUALISATION_USE
VISUALISATION_UPDATE
VISUALISATION_DELETE
ACTION_USE ACTION_VIEW
ACTION_MANAGE ACTION_USE
ACTION_CREATE
ACTION_UPDATE
ACTION_DELETE
CUSTOM_ROLE_MANAGER CUSTOM_ROLE_USE
CUSTOM_ROLE_CREATE
CUSTOM_ROLE_UPDATE
CUSTOM_ROLE_DELETE
CUSTOM_ROLE_USE CUSTOM_ROLE_VIEW
MANAGER KNOWLEDGE_GRAPH_USE
VISUALISATION_CREATE
VISUALISATION_MANAGE
ACTION_MANAGE
WORKFLOW_MANAGE
SCHEMA_INDEX_MANAGE
OFFICER KNOWLEDGE_GRAPH_USE
VISUALISATION_CREATE
VISUALISATION_MANAGE
ACTION_MANAGE 
WORKFLOW_USE
EXPLORER KNOWLEDGE_GRAPH_USE
VISUALISATION_CREATE