Commit b37d1382 authored by Sandro Eiler's avatar Sandro Eiler 🐌

Updated documentation.

parent 1785480e
Programming conventions
=======================
Implementation is done according to flake8 and black.
Requirements
============
Functional
----------
### System integrability
The developer has to have the possibility to integrate the roles in the preferred location.
Adding new roles to the system must not be limited on a specific development environment.
**Implementation modules:**
- API
- Framework configuration option (e.g. where to locate files)
### Project management
This includes setting paths or names for _karmantra_'s provided files.
This allows the developers to be more flexible when including _karmantra_ into
their project.
**Implementation modules:**
- configuration file generation+update
- Change of config file leads to restructuring _karmantra_'s files within the devs project.
### Role management
There has to be the possibility to add, remove or modify roles.
**Implementation modules:**
- Abstract role class
- Role management options (delete, add, modify)
### Rule management
There has to be the possibility to add, remove or modify rules.
**Implementation modules:**
- Abstract rule class
- Rule management options (delete, add, modify)
### Trigger-Mapping
Triggers within the applying system have to be mapped to role's rules.
**Implementation modules:**
- Trigger mapping class
- Trigger management options (delete, add, modify)
### Interface
Applying changes for roles, rules and triggers has to be possible within a guiding interface provided.
**Implementation modules:**
- CLI: Get the user inputs for _karmantra_ tasks.
### Testing
The required modules are testable.
**Implementation modules:**
- Tests for the functional requirements concerning the execution of karmantra as a tool.
- Tests for the outcome in the form of a importable module.
Non-functional
---------------
- Documentation
- Reusability
- Robustness
- Effectiveness (resulting performance in relation to effort)
- Open Source
- Transparency
- Low complexity
- Ideally purely functional, not having any external state
Implementation
==============
Design decisions
----------------
- Only check rules that are triggered (efficiency)
- also depends on how rules are connected
- not making sense because a trigger might be wanted to lead to a check of
the whole role?
- Not just make devs work with one config file:
- Leaving devs only with one config file to fill information in leads to a
bad modifiability and makes it harder to alter devs code, provided to the
module through the config file.
Decision: Use the config file for backup and overview purposes. Generate
finalized python files (with the help of templates) instead of templating.
- A system might want to check how connected users are to evaluate roles. Such calculations can happen for every trigger activation (potentially too much cost) or regularly and independet from triggers (potentially implementation overhead and evaluation not completely "up to date").
- Weighted role assignment can take place in rules.
### Open questions
- Seperate rules from their roles?
- It's not necessary to keep rules seperate, inheriting from an abstract rule class.
Nevertheless it's useful to do so because of following reasons:
1) Code becomes more clear and modular
e.g. rules can be connected to each other more clearly through logical operators if wished
2) users can more easily be informed about which rules are not met, after their role status changed
- Have the possibility to keep a role for at least N time? Sometimes a role shall not be lost at all after getting it? How to make it persistant?
- Group dependent roles: The idea of allowing groups to have their own is much more complex. For now it is not included. Nevertheless it should be kept in mind so that through another abstraction it should generally be implementable in the future.
......@@ -4,7 +4,7 @@ Understanding karmantra in detail
When to use karmantra
---------------------
- You want to allow your system to give roles to users in groups without the need of admins help or hierarchic structures
- You want to allow your system to assign roles to users autamically (based on rules)
- You are developing a system that allows groups to have users with different roles.
- You want to adapt your system's roles over time.
- You want your admins and users to be notified about changes.
......@@ -73,9 +73,6 @@ A project is updated whenever a developer wants to add/remove/modify roles, rule
> :memo: **Behind the scenes...**
... _karmantra_ has to read the current state and write back the altered version of the project. Writing python code with all needed input from the developers is implemented through templates. Reading existing generated static python code for modification has to be done with a different approach since it's not trivial to reverse engineer paramters from ([stackoverflow](https://stackoverflow.com/questions/37813550/is-it-possible-to-use-a-jinja2-template-to-reverse-engineer-the-parameters-from)). Knowing this, the generated python code includes a behaviour of an interface returning the values that we might need to change ([stackoverflow](https://stackoverflow.com/questions/37303036/load-source-file-without-a-module)).
Backups
-------
TODO
### Configuration file
......
Apply your model
================
Before getting started, we have to spend some thoughts on our model, we want to apply using _karmantra_.
Models for automated role assignment
-------------------------------------
Basically our model consists of roles that a user can obtain.
Every role has one or more rules, defining the conditions of being entitled to have the role as a user.
![](img/basic.png)
In the image above you can find such an example model. It proivides the possibility to automate role assignments.
The triggers form the interface between system and _karmantra_.
The advantages are, that:
* No administrators are needed.
* Power (in form of permissions) is set by the model and not by a priviledged user
* Through the decoupling of role evaluation from the system's other modules, documentation and transparency of the systems beaviour can be improved.
* Through models, _karmantra_ can reflect the real world more naturally.
**Hierarchical vs non-hierarchical**
The example from above shows a non-hierarchical role model.
Of course, _karmantra_ also allows hierarchical or mixed models as following figure shows.
Hierarchical roles are implemented by defining having one role to be a rule to another role in order to get it.
![](img/hierarchical.png)
With this software we explicitly want to support development of more non-hierarchical role models. 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.
To enable more user-centric software, it's advisable to promote a democratic evolution of the systems model.
This is is possible if the users:
1. have the feeling, that they can participate and that their comments are taken seriously;
2. trust in the system's model impementation rather that stiff social structures.
Of course there are endless scenarios for environments, where hierarchical role models are unavoidable. Too often this kind of model is used only because it seems to be the easier way.
Modeling asides groups
----------------------
Besides well known models that come from roles and rules, we want to show further fields of application.
### Reward System
![](img/reward.png)
This image shows, how a model of a reward system can look like. It could be implemented with a points system. In this case users can only get higher roles if the respective rules apply. it's conceivable that roles can be lost also.
### Include Processes
![](img/process.png)
Sometimes a role is not depending on attributes only, but on complex (democratic) processes or work flows. In this case a role's rule can represent one step of a process of gaining (or losing) a role.
### Notifications
![](img/notification.png)
A completely different scenario would be 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.
### Ticket System
Karmantra could also support a system, where tickets are automatically assigned to people, fitting the best.
A role then would represent a task or ticket. The rules define the conditions to become an assignee to the ticket.
Groups
-------
For _karmantra_ it's not important whether you want to apply your model for all groups or to have one model per group.
In case you have multiple groups and want to apply one model per group, just create one module for each group, containing its model.
Including administration use cases
-----------------------------------
In case, a mixed approach is wanted where roles are evaluated automatically but administrators have to be possible too, we suggest the following.
An administrator can be seen as a person with a role, allowing to set flags for other users.
These flags can then be used as a condition for rule to (not) apply.
Conceptual example for Karrot
=============================
How Karrot Roles work
--------------------------
### Querying role
![](img/karrot01.png)
Let's assume, Karrot wants to find out if a user has the _editor_. To find this out, the function _is_editor(user)_ of a _group_ instance is called. The function again calls the function _is_member_with_role(user,rolename)_ from the class _GroupMembership_.
### Updating Role
![](img/karrot02.png)
At the moment there's only one trigger for the change of roles: Giving trust carrots. Whenever a trust carrot is given by a user _A_ to a user _B_, Karrot will check if the change will affect user B's role. If so, the new role will be made persistent.
Proposal for change
--------------------
1) Instead of one trigger (trust carrots), there can be many
2) Instead of two roles, there can be any amount
3) A role can be defined on the basis of one or multiple _rules_
![](img/karrot03.png)
Updating a users role can be triggered through different actions in a system.
Additionally, it is possible to register triggers that are then mapped to roles:
![](img/triggers.png)
This allows to have a centralized trigger mapping within the system, which is intended to reduce development mistakes.
### Example
A user gets the _editor_ role, after receiving 5 trust carrots and not being inactive for 30 days. In this example we have two triggers - giving trust carrots and doing a login. The groups roles then have to be checked again for the user that just signed in or the user that received a trust carrot. The role will be confirmed or rejected by the role classes.
### Realisation
![](img/model01.png)
Every role in the system inherits from the abstract class _Trust_Role_:
rules
: This attribute keeps a list of rules that are needed to fulfill the roles condition
keep_Role_At_Least_For
: Not fulfilling conditions of a role anymore doesn't mean the role has to get removed immediately. There might be a countdown to allow users to refulfill the role conditions. Also it might be wanted to not lose a role at all whenever the role is obtained.
evaluate_changes()
: This function connects the rules with a specific logic. It might be necessary to fulfill rule A _OR_ B, or both have to be fulfilled to have a role. If a role change took place, the notification of the user has to take place.
![](img/model02.png)
applies()
: This function gives back a boolean depending on whether the rules requirements are met or not.
### Advantages
- Generic framework providing roles that are modular and described through rules
- New roles can be implemented fast and easy (through skeletons)
- Existing roles can easily be edited
Overall Contribution
---------------------
### Contribution parts
1) Service for skeleton creation (including code "validation")
2) User notification tool based on the roles (this will run within the system)
3) Notifications / statistics for system administrators (this will run within the system)
4) Testing
5) Practically implementing current Karrot roles with new approach
### Flow of Role Creation
#### Developer view
1) Give rolename, number of rules and the functions for role checking and the roles rules checking
2) Verify that the given code has been approved
3) Include the result into the project
#### Framework view
1) Get rolename, number of rules and the functions for role checking and the roles rules checking
2) Verify that the given code is valid code or return an error
3) Include the code into a skeleton
White Paper
===========
The master thesis behind this documentation [can be viewed here](thesis.pdf "thesis behind karmantra").
The main concepts are explained here.
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.
![](img/basic.png)
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:
![](img/hierarchical.png)
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
![](img/reward.png)
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
![](img/process.png)
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
![](img/notification.png)
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
![](img/modeling.png)
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.
![](img/evaluation.png)
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
-------------------
![](img/layers.png)
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.
![](img/structure.png)
......@@ -2,10 +2,8 @@ site_name: karmantra
nav:
- Home: index.md
- Quickstart: quickstart.md
- Modeling: modeling.md
- Tutorial: detail.md
- White Paper: contribution.md
- Case Study: proof-of-concept.md
- In Detail: detail.md
- White Paper: whitepaper.md
- Licence: licence.md
theme:
name: 'material'
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment