White Paper

The master thesis behind this documentation can be viewed here. The main concepts are explained below.

Contribution

To contribute to karmantra, read the relevant section in the git repository.

Definitions

• karmantra
  The developed tool, being the contribution of this master thesis, is called karmantra. karmantra originates from Karrotish Managed Trustbased Role Assignment. It was inspired by the online platform Karrot. The original idea was to develop a tool for trust based role assignment. This concept became more generalized within this master thesis and is not limited to trust anymore.
• context
  A context defines the environment in which a role model is being used. An example could be, having python3.7 as a context. Contexts can inherit from others. For example the Django framework can be a context inheriting from a python context. karmantra uses a context to deploy a role model customized for the target system.
• user / DevUser
  A user is person that can have memberships in system’s groups. A person using karmantra to generate and alter a role model is called DevUser.
• member
  A member is a system’s entity and part of a group. A member can be a human user or another entity.
• role
  A role is a status for members of a group. Usually roles are mapped to permissions.
• rule
  A rule is a condition that has to be met to have a role as a group member. A role can have multiple rules. A rule can imply the need of computing a result instead of only comparing values against each other.
• trigger
  Triggers are a mechanism to initiate the role evaluation process. A trigger can be fired for one or more rules.

Models for automated role assignment

There are infinite possibilities for rule-based role models, depending on the system using roles. This section gives an idea of how role models can look like. Every mentioned model consists of roles that a user can obtain within a group. Every role has one or more rules, defining the conditions of being entitled to have the role as a user.

The figure above shows an example model that allows automating through triggers. These triggers form the interface between tho role model instance and the rest of the system. Advantages of this approach of having roles, rules and triggers are, that:

• Administrators are not necessary.
• Power (in form of permissions) is set by the model and not by a privileged user. Thus power is potentially less likely to be abused.
• Through the decoupling of role evaluation from the system’s other modules, documentation and transparency of the systems behavior can be improved.
• The real world can be reflected more naturally through models that allow self-managed role assignment instead of having rigid role assignment.

Hierarchical vs non-hierarchical

In the figure above we have seen a non-hierarchical role model. Since we don’t want to focus on specific types of role models, also hierarchical or mixed models are examined. Following figure shows a mixed model with partial hierarchy:

While hierarchical models are easy to implement if the task of role assignment is left to administrative users, they have the disadvantage of providing ground for misuse and rigid distribution of roles. Since administration permissions can lead to subjective role assignment, hierarchical role models do not necessarily reflect power structures and the possibilities to get roles may depend on the persons having administrative roles. Of course there are endless scenarios for environments, where hierarchical role models are unavoidable. But this kind of model may seem to be the easier way for some developers to be implemented. Role models, without being strictly hierarchical, have further possibilities like representing democratic decision processes.

Modeling asides groups

Besides well known models that come from roles and rules, there are further fields of application.

Reward System

This figure shows, how a reward system’s model can look like. It could e.g., be implemented with a points system. In this case users can only get higher roles if the respective rules apply. It is conceivable that roles can be lost also.

Include Processes

Sometimes a role is not depending on attributes only, but on complex (possibly demo- cratic) processes or work flows. In this case a role’s rule can represent one step of a process of gaining (or losing) a role. This figure shows how rules can be used to represent process steps.

Notifications

This figure shows a completely different scenario. Here the use case is the regulation of sending notifications. For this we replace the roles with notifications. A notification can have one or more rules for being sent. This still perfectly fits to our environment of users and groups.

Application specification

We have to differentiate between role provisioning and role-based assignment of permissions. We focus on provisioning only.

A rule-based provisioning can be split into two domains:

1. Role and rule modeling
2. rule-based role evaluation

Modeling flow

Creating, modifying or removing a role model includes the steps role model deployment (including the integration into the target system) and rule implementation for the DevUser. Initially, a DevUser wants to create a role model. The modeling tool receives all necessary information on roles, rules, role evaluation triggers and how these are connected to build the role model. The latter is then deployed to the DevUser’s target system. The remaining task for the DevUser is to implement the following components:

• wrapper [mandatory] The wrapper ensures that arbitrary group and user objects can be used with the role evaluation framework (described in 4.2.2). The DevUser has to specify how the role evaluation framework can extract the needed information in the required way.
• rules [mandatory] The DevUser has to implement the rule functions which are needed to check if the rules apply for a user. A rule can be, for example, that the user has a specific attribute value or that a system event occurred.
• module globals [mandatory] To check if a rule applies might require access to resources of the embedding system.
• trigger firing [mandatory] Wherever triggers have to be fired, the role evaluation tool has to be indicated as trigger receiver.
• result format [optional] If the default result format does not fit the DevUser’s needs, it can be replaced.
• role’s evaluation behaviour [optional] If a role’s behavior has to be adjusted, its inherited functions can be overwritten. A DevUser might like to order rules that are about to be checked in a specific order.

The components which are mentioned earlier, namely the role model and the role evaluation mechanism are tied together as importable module and deployed into the target system. The DevUser of course has to import this module in the correct locations. To minimize the DevUser’s costs of time and implementation complexity, all components within the importable framework can easily be prepared with templates, that just have to be filled with missing code. It is indispensable that the DevUser has to contribute some code. Because the modeling tool has to deal with arbitrary systems, it is not possible to generate code for all existing possibilities of target systems.

Role evaluation

Role model elements

Role models can be described with the three element types role, rule and trigger. Between different element types, edges can be defined. Following, an edge is also called "connection". The relation of these elements can be described through following rules:

• a role can have multiple rules
• a rule can be used by multiple roles
• one rule can have one trigger
• a trigger can be mapped to multiple rules

The question remains whether we can model relations between roles. E.g., hierarchical roles have to be used. With the definitions above we can also describe dependencies between roles indirectly: The dependency of one role to another can be defined as a rule.

Role evaluation mechanism

The role evaluation mechanism is started whenever a trigger in the system is fired.

The role evaluation framework provides an interface for firing the triggers. The module will expect

• a trigger identifier
• the affected user
• and the user’s group as scope

for the role evaluation. Stating the group is necessary because a user’s roles can vary for different groups. Smaller systems may not need to have multiple groups and thereby can keep all users within one group. karmantra provides the option to select all users from a group for the evaluation process if no user is specified.

Architecture layers

karmantra’s implementation layers (blue) with supporting and needed components (white). Upper box: CLI and the modeling tool. Lower box: Deployed role model with role evaluation mechanism.

Project structure

In the root directory for development, there is a folder for the source code (src), a folder for the documentation (docs) and files related to the development workflow (such as hooks for git). Following figure shows the directory structure for karmantra. Within the src folder, the code for running karmantra can be found in folder main. Test implementations can be found in folder tests.