Permissions mechanism

Info

Mechanism of dependencies between objects and access roles to objects in the Mercury DB system. The assumption is to meet the requirement that the system has an advanced mechanism for managing user permissions to perform operations on individual types of cases with granulation of permissions to individual fields of case objects.

The assumption is to meet the requirement that the system has an advanced mechanism for managing user permissions to perform operations on individual types of cases with granulation of permissions to individual fields of case objects.

Assumptions of the permission mechanism

Assumptions of the mechanism:

1. Possibility to grant permissions to specific types of cases. In the case where the user role requires permissions to all types of cases, in order to solve the problem related to the burdensome definition of many connections, the character * is entered to represent all types available in the database.
2. Possibility to grant permissions to specific parameters (fields) of a given type of case. In the case where the user role requires permissions to all fields of a case, in order to solve the problem related to the burdensome definition of many connections, the character * is entered to represent all fields of a given type.
3. There are three levels of authorization:
   1. RW (read/write) – authorization to read and write values
   2. RO (read only) – authorization to read values only
   3. WO (write only) – authorization to write values only – in practice, authorization comes down to the ability to only enter new data – there is no possibility of modifying data, because modification assumes prior reading of data and obtaining access to read it.
4. No individual authorizations, directly granted to users. Users obtain access to data via the roles they hold.
5. The mechanism does not act as an authentication mechanism. External systems are to perform the task of identifying the user and assigning them appropriate roles. The mechanism only authorizes access to data, verifies whether the set of roles held by the user meets the requirements for access to data.

Authorization mechanism

The authorization mechanism is based on entities stored in a relational database:

• TypeParamRole – linking the type, its fields with the authorization and the user role they perform.
• Role – list of roles to which appropriate permissions are granted
• Case – case objects have fields informing about the user's role used when making changes:
  • createdByRoleName – field with the name of the role the user was performing when adding the case.
  • lastModifiedByRoleName – field with the name of the role the user was performing when modifying the case

Operation context

User data, their name, default role name, and a set of roles are passed to the permission verification mechanism via the Context object (see the article SOAP/REST service request context). The context parameter (context) is required for all SOAP/REST service operations of the system and it is necessary to define the following parameters:

Parameter	Description	Type
userName	User name	String
currentRole	Current user role (needed to register the team in which the user is making changes. Required for case updates.	String
userRoles	List of user roles (names). Based on this list, permissions to perform operations/invoked services are verified.	Set<String>

Below is an example of a defined context in a request sent to the REST service:

Mechanism operation algorithm

Below is the mechanism operation algorithm:

Retrieving user permissions

During the action of retrieving user permissions, the following operations are performed:

1. Reading user data from the SOAP/REST request context object
2. If the external system has obtained a connection to the Mercury system services via the OAuth mechanism, the scope (list of roles) for which the session token was issued is verified. If the scope does not match, an exception is thrown, informing about the lack of a valid session token and that it must be refreshed.
3. Based on the data from the context, the available permissions for types and their fields are retrieved from the TypeParamRole entity.
4. A SecurityContext object is built for the user, containing:
   1. A list of types that they have write access to
   2. A list of types that they have read access to
   3. A list of parameters associated with types that they have write access to
   4. A list of parameters associated with types that they have read access to
   5. A context identifier based on the username and a set of their roles. The built object is sent to the cache and is used multiple times within the active user session. Below is the code for building the identifier:

pro.ibpm.mercury.context.SecurityContext.java

/**
* Generates a unique security context identifier from username and roles.
*
* @return The unique security context identifier.
*/
@Override
public int hashCode() {
  final int prime = 31;
  int result = 1;
  result = prime * result + ((userName == null) ? 0 : userName.hashCode());
  if (userRoles != null && !userRoles.isEmpty()) {
    for (String role : userRoles) {
      result = prime * result + role.hashCode();
    }
  }
  return result;
}

Authorization of the performed operation

Based on the security context, depending on the performed operation, the permissions to perform operations on case objects are verified:

1. For the search operation, the list of search criteria is verified (whether the user has the right to read the fields they want to search on), and the list of found cases is presented depending on the fields the user has permissions to. If the search criteria do not contain a criterion regarding the type of case, it will be automatically added based on the data stored in the user's security context (does not apply to situations where the user has permissions to all types of cases).
2. For the case object download operation:
   1. Does the user have the right to download the given case type?
   2. Only the values of the parameters that the user has the right to read are returned
3. For the case object change operation:
   1. Does the user have the right to write the given case type?
   2. Does the user have the right to write the given case type field?

TypeParamRole

Layers used	Logic
Type	Entity
complexType	TypeParamRole

An entity that binds user roles to case type definitions, individual definitions of their fields, and permissions to them.

List and meaning of individual fields

Parameter	Description	Type	Required	Allowed values
id	Binding identifier between user role and field name (Attribute)	Long	Yes
typeCode	Type code	String	Yes	Type codes or the * character indicating the definition of privileges for all types of issues.
paramName	The name of the issue field to which the privilege is associated	String	Yes	Parameter names defined for the ParamDefinition entity or the * character indicating privileges for all field names included in the type whose code was provided in the typeCode field
role	The user role to which the privilege is associated	Role	Yes
privilegeName	The name of the privilege/privilege.	String	Yes	RW – read/write RO – read only WO – write only
publishVersion	Version changed with each update - needed to identify whether the entry has already been published.	String	Yes
createDate	Date of entry creation	Calendar	Yes
createdBy	System user (operator) creating the entry. Field automatically updated based on context data (userName) sent during the authorization adding operation.	String	Yes
lastModifyDate	Data modification date	Calendar	Yes
lastModifedBy	System user (operator) who last modified the entry. Field automatically completed based on context data (userName) sent during the authorization updating/adding.	String	Yes
modifyComment	Comment on the change	String	No

Example of the contents of a table representing entity data in a relational database:

Roles

Layers used in	Logic
Type	Entity
complexType	Role, RoleDto

An entity that is a dictionary of user role names.

List and meaning of individual fields

Parameter	Description	Type	Required	Allowed values
name	Role identifier (name)	String	Yes
description	Role description	String	No