Introducing Positions for Granting Permissions over Users via Organisational Units

1 Initial Problem

The standard system for granting permission in ILIAS is the Role Based Access Control (RBAC) system. The three basic building blocks of that system are Users, Roles and Permissions. A User gets a Permission by having a Role that grants said Permission. For every ILIAS object it can be configured which Role grants which Permissions on the given object. Every User can get multiple assignments of Roles, where the Permissions granted for the User by this Roles are added up.

The current system in ILIAS is complicated by to the tree structure of the ILIAS object system. This deeply nested structure requires the user to have the correct permissions not only on the object he wants or needs to take actions on, but also on the path from the root node of the tree to the object. The Roles which grant the Permissions come in the fashion of global roles, which are available on every object in ILIAS and local roles, which are only available in subtrees of ILIAS. For some ILIAS objects the local roles also act as an indicator for the membership of users at the object. The system is further complicated by the rules for permission inheritances and permissions templates.

With ILIAS 4.4 the concept of Organisational Units was introduced to ILIAS to model the hierarchical structure of organisations in ILIAS. This structure is model by means of the ILIAS tree structure[1], i.e. organisational units are modeled as container objects that can contain other organisational units, thus building the hierarchical structure. Users are assigned to local roles on said container objects, where for every container there are two default local roles “Superior” and “Employee”. The relation between a superior and and employee thus is established via local roles on the same container (user A → has role superior → on orgu XYZ → with local role employees assigned to → user B). The role system of ILIAS also allows the creation of further local roles at every organisational unit to e.g. express the fact that someone is the deputy of the superior. Akin to every other ILIAS object the local and global roles can be configured to have permissions on the objects modeling the organisational units.

A difference of the roles as they are used in the organisational units compared to the standard usage in ILIAS is, that local roles are not only used to express permissions on the objects where these Permissions are configured. Currently there are three Permissions that, in fact, express permissions over the users in the same organisational units (“View Learning Progress of Unit”, “View Learning Progress of Unit incl. Subunits”, “Read Access to User Accounts”). This differs from the ordinary understanding of Permissions in ILIAS as these Permissions do not enable actions at the organisational unit object itself, but in potentially distant locations in the ILIAS system. The key observation here is that for every permission a superior should have over its employees at any location in ILIAS, a new Permission would need to be introduced at the organisational unit object. The duplication of “View Learning Progress of Unit” into a second version (“… incl. Subunits”) for performance reasons implies that this might also happen for any other permission for superiors over users, leading to even more configurable Permissions at the organisational units.

Besides that potentially very large set of available Permissions at organisational units there are more drawbacks that need to be considered for the current solution for modeling organisational units, superiors, employees and their relations:

Since the Permissions are granted at the organisational units it is only possible to grant the according permission for every other object in ILIAS. With the current system one can only say “Allow the superior to view the Learning Progress for its Employees everywhere.” and not “Allow the superior to view the Learning Progress for its Employees at this course but not at that course.”

Local roles for superiors and employees are created at the organisational units although in fact most of the users assigned to this roles will never actually visit the organisational unit objects in ILIAS directly. Besides the three Permissions granting permissions on users in the organisational unit, the local roles are merely created to express statements like “This user is the employee of that user.”.

The numerous local roles for employees and superiors that exist in the system hide the fact, that the real organisations often have a rather unified understanding of what a superior is allowed to do with its employees that does not depend on the organisational unit both belong to. To apply changes in this understanding to the configuration in ILIAS, Permissions for local roles have to be changed on many organisational units. It is impossible to just “Allow superiors to see the learning progresses of their employees.”.

The increasing usage of the organisational units feature in ILIAS spawned feature requests to integrate the relations expressed in the organisational units to more of the existing features in ILIAS:

• Support of OrgUnits in Tests: http://www.ilias.de/docu/goto_docu_wiki_wpage_3793_1357.html
• Support of OrgUnits in Courses and Groups: http://www.ilias.de/docu/goto_docu_wiki_wpage_3564_1357.html
• Use Org Units to Classify External Users: http://www.ilias.de/docu/goto_docu_wiki_wpage_3575_1357.html
• Allow superiors of participants to enter and view results: http://www.ilias.de/docu/goto_docu_wiki_wpage_4500_1357.html

The approach outlined in “Support of OrgUnits in Courses and Groups” introduces a special mode “Show Member Data According to Access Rights within Organisational Unit“ for objects of said types and a new Permission “Edit Members” on organisational units. If the mode is activated on a course, administrators and tutors of the course only have access to members for whom they get the Permission “Edit Members” via an organisational unit. Besides the aforementioned drawback of creating new and possibly duplicated permissions for other objects on the organisational units, this approach has the problem that there only can be an administrator for all course members if that administrator also has the “Edit Members” Permission over all users via the organisational units. This would mean, that at the organisational unit one would allow that user to edit the members at potentially all ILIAS objects. A positive effect of this solution is, that the control over the course object is at least partially located at the object itself and not in a distant location (the organisational unit).

Another approach is outline in “Allow superiors of participants to enter and view results”. In this approach, two settings “Superior can examinate” and “Superior can view results” are introduced for the individual assessment that would grant superiors these two permissions over their employees at the individual assessment. Akin to the former approach, this moves the control over the object to the object itself. Since the solution does not involve the RBAC, no new permissions are introduced at the organisational unit. There is the drawback that permissions on the object are granted via settings and not by means of the RBAC. Another drawback is that superiors are explicitly mentioned in the settings, thus new local roles in the organisational units (e.g. for deputies) won’t be covered by the settings. In contrast to the former approach it is easily possible to have administrators for all members of the object without introducing the possible effect that these administrators can edit the members on all other objects too via the organisational units.

The general problem that all approaches need to deal with is, that in order to use the existing RBAC system for expressing permissions of superiors over employees at certain objects, the current two dimensional role-permission-matrix at objects becomes a three dimensional role-orgunit-permission-matrix when taking relations defined via organisational units into account. This is the complexity that all the aforementioned approaches deal with in a different manner, creating different trade offs. The RBAC system in general seems to be sufficiently powerful if one drops one of the three dimensions by either granting users the same permissions over all users at some object without taking their memberships in organisational units into account (standard RBAC) or granting users the same permissions over users in an organisational units for all objects in the system (RBAC in organisational units). The current approaches that try to handle the full complexity (special mode at object, special superior setting at object) do not seem to be powerful enough to express all desired permission scenarios and also bear other problems.

The questions, that every approach to the problem “How to grant permissions for superiors over their employees at certain objects?” need to answer could be summerarized as such:

• Is the approach powerful enough to express to be actually useful for a wide range of real world scenarios?
• Is the approach comprehensible enough to be actually used in real world?
• Where is the configuration for the permission located in the system? At the organisational unit or at the object or at both? If configuration is located at both, how do the configurations interact?
• How is the complexity of the relation user-orgunit-object-permission presented to an administrator? Can the user understand what the possible influence on the permissions of a user is when a certain configuration is made?
• Which side effects are introduced by the solution and what are their effects?

2 Conceptual Summary

The general idea of the approach presented hereby is to get closer to the way that people talk about relations in their organisation. Instead of saying “Jane Doe is superior in the organisational unit I am an employee in.” they more often say things like “Jane Doe is my superior”. Hierarchical relations in an organisation are understood as personal relations.

The names for such relations that exist in the real world are not the same for every organisation and the variety of corresponding tasks is also understood differently. The currently used term “superior” is a very general term for “team leads”, “division managers”, “supervisors” and “department heads”.

The first step for this new approach therefore is to introduce the concept of Functions to ILIAS. Functions are globally defined for the whole organisation on a new tab on the root node of the organisational units. In contrast to Roles, that define permissions on objects, Functions are aimed to define permissions over users by establishing relations between the users. Every Function has a name and a list of Rules that define to which users it relates. A Rule consists of another function or the token “everyone” and one of the tokens “same organisational unit” or “subsequent organisational units”. There are two functions “superior” and “employee” defined per default as such:

• Superior:
  for “Employee” in the “same organisational unit”
  for “everyone” in the “subsequent organisational unit”
• Employee

If one would like to introduce a deputy for the superiors, the configuration of functions could be augmented as such:

• Superior:
  for “Employee” in the “same organisational unit”
  for “Deputy” in the “same organisational unit”
  for “everyone” in the “subsequent organisational units”
• Deputy:
  for “Employee” in the “same organisational unit”
  for “everyone” in the “subsequent organisational unit”
• Employee

Second step for this new approach would be to change the membership administration of the organisational units in a way that takes the defined Functions into account. Therefore, instead of assigning a user to a local role of the organisational unit to make her a member of the unit, one would assign a function in an organisational unit to users. E.g.:

• My Company:
  Belinda Boss : Superior
  Alfred Assistant: Employee
  • Department A:
    Herman A. Head: Superior
    Erna Employee: Employee
    Ernest Employee: Employee
  • Department B:
    Hillary B. Head: Superior
    Edgar Employee: Employee
    Edith Employee: Employees

With the functions defined above this would establish the following relations:

• Belinda is the superior of Alfred, Herman, Erna, Ernest, Hillary, Edgar and Edith.
• Herman is the superior of Erna and Ernest.
• Hillary is the superior of Edgar and Edith.

Third step for the approach proposed here is, to introduce a new subtab in the permissions screen of objects that should take user relations created by the hierarchy in the organisational units into account. The screen would look similar to the current permission screen where permissions for roles can be configured. Instead of the roles the screen would list the functions defined in the organisation. Instead of all permissions available at the object, the screen would only list permissions that apply to users. For a course this would for example be:

• View Learning Progress
• Manage Members
• Set Learning Progress

2.1 Defaults

To make it easily possible to express defaults for permissions over users, the option “Use defaults” is introduced per function to the permission screen for functions. When this option is checked, it is impossible to configure the permissions for the function and instead the defaults for this function are used. The defaults for the functions are configured per function and object in the configuration for functions at the organisational units.

2.2 Visibility

To make it possible for administrators to understand which functions a user has for which other users and vice versa, a “Functions” tab is introduced to the “User” screen in the administration. The screen lists the functions that a user has and the relations of a user that are established by functions the user has itself or by functions other users have.

In the permission screen for functions, a functionality similar to “Permissions of User” can be introduced, that allows to examine which permissions of a user are granted for another user.

2.3 Considerations

The proposed solution would introduce a completely new system for granting permissions to ILIAS and therefore needs to be considered carefully. The discussions about the already proposed solutions in the JF show that this is indeed true for all possible solutions and that a general solution for the outlined problems is desired. The problems outlined in the “Initial Problem” section present a problem to real world scenarios anyway and good answers to the problems in the RBAC scheme seem to be hard to find.

The initial idea to express permissions over users in a different way (Functions in organisational units) than permissions over objects (Roles in objects) is sound. As shown in “Initial Problem” both problems are in fact different from each other and the current scheme of using the RBAC for memberships in organisational units leads to unwanted complexity and configuration problems.

The proposed idea of managing permissions from users over other users seems to align with real world concepts (how people think of relations in a hierarchical organisation) better than the current RBAC approach. People seem to think of a “Superior” as being the same thing in all organisational units, not different ones as the currently used RBAC schema implies.

With the proposed approach, the configuration of the permissions over users is split into two distinct parts. In the organisational units one defines the functions and the corresponding relations between the users. The permissions the functions grant are then defined at the objects. The possibility to name the functions allows to introduce the common understanding of the existing functions of an organisation into the system. This seems to be easier to understand as the anonymous naming “Superior”/“Employee” that is currently used and the mixture of permissions for organisational units and other objects that is implied by the current RBAC schema.
The complexity of the user-orgunit-object-permission-relation is partly moved into the Rules that define how a relation between users is established. We expect the possible rules to grow in the future to accommodate more scenarios. This complexity seems to be manageable better than in the RBAC schema, as it is focused in a global administration and administrators on a local level (organisational units or learning objects) do not need to understand the rules that establish the relations, as they use the names that are given to the functions.

Finding compelling solutions to the problems that arise when representing organisational units and their hierarchies in ILIAS are a key factor for a wide adoption of ILIAS in companies. While universities tend to focus on their learning resources, a lot of problems in companies are focused around organisational hierarchies. The tools currently available in ILIAS for these problems need to improve.

2.4 Further Steps

With the proposed system of Functions there are possible further developments that could be made:

• Currently the users matched by the Rules for Functions are considered to be additional. That means the Function targets users matched by any of the of the given Rules. This could be complemented by rules that target users that are matched by all given rules or by rules that express exceptions.
• The possibility of deputies seems not to be thought through completely. To accommodate deputies correctly, one might need rules to express something like: “Exactly like this function.”. One also might want to introduce functionality that accomodates temporary replacement of superiors or people with other functions.
• At some point it might be required to define the functions only for some subtrees of the organizational units.
• The proposed system could be enhanced by functionality for holiday replacements, where a function at some organizational unit could be given to another user temporarily.

3 User Interface Modifications

3.1 List of Affected Views

A new tab "Functions" should be added to the Organisational Unit node. It provides the administration for the global administration of the functions.

A new subtab "Permissions for Functions" should be added to the "Permissions" tab of the objects that should use this feature. The subtab "Object Permission Settings" should be renamed to "Permissions for Roles" in all locations. An example for a possible set of permissions at a Course is given below. The concrete implementation of the functions feature at certain objects should be subject to single feature requests.

3.2 User Interface Details

The Administration of OrgUnits will be extended with a new Tab "Positions":

3.3 New User Interface Concepts

{If the proposal introduces any completely new user interface elements, please provide a link to separate feature wiki entries for each of them according to the kitchen sink template.}

4 Technical Information

The implementation of this feature will require changes in the AccessControl. The feature should be implemented as an additional source for permissions, so interference with the existing RBAC can be minimized. The main change in the ilAccessControl thus will be an extension of the checkAccessOfUser-method by a check that works via the to be created function machinery over the organisational units.

Moreover we propose to introduce a new method in the ilAccessControl-class that returns an array of user(-id) per permission. In the default case (without functions) this should fall back to "all members" or a similar notion depending on the object the method is called for. For the case where functions are used, the members (or similar) of the object are filtered according to the permissions that are given via functions. This method then can be used in every scenario where some function could either be permitted by means of the existing RBAC or the to be implemented functions.

A proposal for the according modification of the ilAccessControl class will be made via PR.

5 Contact

• Author of the Request: Richard Klees
• Maintainer: Studer, Martin [mstuder]
• Implementation of the feature is done by: {The maintainer must add the name of the implementing developer.}

6 Funding

If you are interest in funding this feature, please add your name and institution to this list.

• CaT Concepts and Training GmbH

7 Discussion

AT 2017-06-19: The feature request Presentation of User Data abides by Orgunit-Affiliation makes use of this new concept. 

• We should give it a different label. Function is a get-together, a rule of correspondance between sets (only known to educated people), or indication occupational position. 
  • Consider "definition" instead of "rule" 
  • Consider "affiliation" instead of "function" (not excellent either) 
• Please outline what will happen if I delete the "deputy" (or any other) definition? How is secured that a deputy is left with some position? 
• Please outline what will happen if I change the scope of a definition (from all subsequent to same or vice versa)? If I change "defaults" will this affect existing objects on only new objects? 

JourFixe, ILIAS [jourfixe], June 26, 2017: We highly appreciate this suggestion and schedule it for 5.3. We would like to have the following changes:

• Please consider another label than 'function' (see Alexandra's comment), e.g. 'position'.
• Object permission labels should be kept for the 'Permissions for Positions' (above still called 'Permissions for Functions') screen to ease the understanding of this feature.
• Please extend chapter 4 to clarify how consumer code has to implement this feature.
• Please define improve the template screen (missing title etc.). Behaviour of changed affiliation templates should be similar to RBAC (later change of template does not affect existing objects, needs additional 'Change existing affiliations'.
• We would like to have a short confirmation message when the deputy or superior position is removed from an org unit to notify that there are still users assigned  "Would you like to assign these person to the position employee?".
• As Fabian Schmid could not join the JF, we ask him as maintainer of the org unit to confirm that he supports the current concept and the requested changes of today's JF.

Schmid, Fabian [fschmid], June 28, 2017: I support the current concept of the feature and the requested changes, thanks a lot for discussing the feature request.

Klees, Richard [rklees], July 06, 2017: I adjusted the three screens for the administration of positions to fit the requirements of the JF.

Haagen, Nils [nlz], August 25, 2017: When deleting positions, imho the message should read "Users assigned to this position will be assigned to Employees. Do you really want to delete the position?" and act accordingly. Otherwise, there would be users in OrgUnits without a position?

Kunkel, Matthias [mkunkel], 28 FEB 2018: Changed title of feature wiki page from 'Introducing a new System for Granting Permissions over Users via Organisational Units' to 'Introducing Positions for Granting Permissions over Users via Organisational Units' to include the name of this new system in the page title. Makes it easier to identify the related request.

8 Implementation

The implementation of the concept has been made as mentioned above. The detailed process of creating and managing Positions is described here:

Creating Positions and managing Permissions

Assign Users to a position in a OrgUnit

Activating Position-related Permissions in Objects

Configure Default Permissions of a Position

Technical Information for Developers

To check permissions related to RBAC and Positions, the ilAccesshandler-Interface is now a combination of these three interfaces:

• ilRBACAccessHandler: Services/AccessControl/interfaces/interface.ilRBACAccessHandler.php
• ilOrgUnitPositionAccessHandler: /Modules/OrgUnit/interfaces/class.ilOrgUnitPositionAccessHandler.php
• ilOrgUnitPositionAndRBACAccessHandler: /Modules/OrgUnit/interfaces/class.ilOrgUnitPositionAndRBACAccessHandler.php

In most cases a developer will check for both a RBAC and a Position-related permission, e.g.:

1
2
3
4
5
6
7
8
9
10
11
12
13

/**
	 * @inheritdoc
	 */
	public function checkAccessToObj($operation) {
		if ($operation == "read_learning_progress") {
			return $this->handler->checkRbacOrPositionPermissionAccess("read_learning_progress", "read_learning_progress", $this->iass->getRefId());
		}
		if ($operation == "edit_learning_progress") {
			return $this->handler->checkRbacOrPositionPermissionAccess("edit_learning_progress", "write_learning_progress", $this->iass->getRefId());
		}
 
		return $this->handler->checkAccessOfUser($this->usr->getId(), $operation, '', $this->iass->getRefId(), 'iass');
	}

Test Cases

Test cases completed at 2017-08-22 by Haagen, Nils [nlz]

• - Positions in OrgUnits
  • C18696 - Default Positions
  • C18699 - Change Authorities
  • C18692 - Introducing a new Position
  • C18691 - Assignment of Users to Positions
  • C18745 - Delete a Position
  • C18748 - Enable Positions-Feature for Courses, static 
  • C18749 - Enable Positions-Feature for Courses, changeable

Approval

Approved at 2017-08-25 by Klees, Richard [rklees].