Permissions Granularity

A LibLime customer requires Koha be able to limit staff user access to specific functions available on the Tools page. At present, the permissions model can only specify that a staff user can access all Tools functions, or none of them.

To meet the requirement, the existing permissions model will be extended so that each top-level permission can have subordinate permissions for specific functions. For example, the tools permission will have a set of child permissions, one for each specific tool.

Currently, a Koha staff user can have one or more “userflags” set that grant permission to a more or less broad area of Koha functionality. The 17 flags defined at present are:

Although some of the flags (e.g., borrowers, reserveforothers, updatecharges) could be considered subordinate functions of a broader category (e.g., circulate), the existing flags can serve as the top level of a two-level function/sub-function hierarchy.

The existing user flags are referred to in the user interface as “permissions” or “privileges”. In the user interface and documentation, the second-level permissions should also be referred to as “permissions” except when it is necessary to distinguish between a top-level permission and a second-level, specific permission, in which case “subpermission” could be used.

Because of the due date for the development, granular permissions will be implemented in Koha 3.0. However, in order to not force libraries who are using Koha 3 alpha or beta to have to revise their permissions, the subpermissions will be checked only if a new Boolean system preference “GranularPermissions” is ON. “GranularPermissions” will have a default value of OFF for 3.0; I recommend that the default value change to ON for 3.2.

Two tables will be added to the schema. The interpretation of one column in an existing table will change.

The permissions table will store a list of all possible second-level permissions defined for Koha.

CREATE TABLE `permissions` (
  `module_bit` int(11) NOT NULL DEFAULT 0,
  `code` varchar(30) DEFAULT NULL,
  `description` varchar(255) DEFAULT NULL,
  PRIMARY KEY  (`module_bit`, `code`),
  CONSTRAINT `permissions_ibfk_1` FOREIGN KEY (`module_bit`) REFERENCES `userflags` (`bit`)
    ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

The initial content of the permissions table will be

The code value 'all' stands for all functions corresponding to the particular module represented by module_bit.

The user permissions table will store the set of specific permissions that each staff user has:

CREATE TABLE `user_permissions` (
  `borrowernumber` int(11) NOT NULL DEFAULT 0,
  `module_bit` int(11) NOT NULL DEFAULT 0,
  `code` varchar(30) DEFAULT NULL,
  CONSTRAINT `user_permissions_ibfk_1` FOREIGN KEY (`borrowernumber`) REFERENCES `borrowers` (`borrowernumber`)
    ON DELETE CASCADE ON UPDATE CASCADE,
  CONSTRAINT `user_permissions_ibfk_2` FOREIGN KEY (`module_bit`, `code`) REFERENCES `permissions` (`module_bit`, `code`)
    ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

When “GranularPermissions” is ON, if the flag bit for a particular module is on in borrowers.flags, the staff user will have access to *all* functions of the module.

get_user_and_template takes a hashref as its argument, one of whose keys is flaqsrequired. flaqsrequired is in turn a hashref, whose keys are one or more codes from userflags.flag. Currently, get_user_and_template only considers whether a particular userflag key is present or not, and does not check the value associated with the key. Client code currently calls get_user_and_template like this:

my ($template, $loggedinuser, $cookie)
        = get_template_and_user({template_name => "tools/stage-marc-import.tmpl",
                                        query => $input,
                                        type => "intranet",
                                        authnotrequired => 0,
                                        flagsrequired => {tools => 1},
                                        debug => 1,
                                        });

The API will be changed so that when “GranularPermissions” is ON, the flag value is considered. 1 will continue to be a valid value, and will signify that the user must have permission for all functions of the module in question. If the flag value is not 1, it must be either be a string containing a valid permission code for that module, e.g.,

my ($template, $loggedinuser, $cookie)
        = get_template_and_user({template_name => "tools/stage-marc-import.tmpl",
                                        query => $input,
                                        type => "intranet",
                                        authnotrequired => 0,
                                        flagsrequired => {tools => 'stage_marc_import'},
                                        debug => 1,
                                        });

or the string '*', which means that the staff user must have access to at least one subfunction. Using '*' as the required permission would be useful for a modular home page, which the user should have access to as long as they can access at least one of the functions linked to from that page.

get_user_and_template() also adds a set of variables to the HTML template object of the form 'CAN_user_XXX', where 'XXX' is a flag from userflags.flag. This will be extended so that for each specific permission in the permissions table, a variable will be set (based on the staff user's privileges) called 'CAN_user_XXX_YYY', where 'XXX' is the module from userflags.flag and 'YYY' is the code from permissions.code. If a staff user has all permissions for a given module, all of the 'CAN_user' variables will be added to the template; otherwise, only the ones corresponding to privileges that the user specifically has will be set.

The third parameter of checkauth is a hashref that currently functions the same way as the value of the flagsrequired parameter of get_user_and_template(), and will be changed in the same way.

The second parameter of check_api_auth is a hashref that currently functions the same way as the value of the flagsrequired parameter of get_user_and_template(), and will be changed in the same way.

The second parameter of check_cookie_auth is a hashref that currently functions the same way as the value of the flagsrequired parameter of get_user_and_template(), and will be changed in the same way.

When “GranularPermissions” is OFF, the current UI (members/member-flags.pl) for setting staff user permissions will be used.

When “GranularPermissions” is ON, the UI for setting staff user permissions will be changed as follows:

• The permissions list will be represented as a two-level tree. The top level will be the existing user flags, under each of which will be displayed second-level permissions for that module.
• An appropriate JavaScript tree widget will be used to expand and collapse display of the subpermissions.
• When the user permissions page is opened, if a user has permissions for any functions of the module, the part of the tree for the module will be expanded by default.
• Clicking on the checkbox next to the module title will automatically select all subfunctions.
• Next to each module will be a tree control button (e.g., a plus/minus sign) to expand or collapse the tree.
• Subfunctions will be sorted so that the selected ones appear first, then the unselected ones. Within each range, the codes will be sorted in alphabetical order.
• Both code and description will be displayed for each subpermission.

Granular permissions are being extended to various parts of Koha module by module. It will be important to follow a common naming convention to keep intended function clear.

In general, Granular Permission for a module should cover at least 4 (and possibly 5) parts:

• view
• add
• delete
• edit
• remaining_permissions

These can be remembered by the convenient mnemonic VADER. Additional “grains” can be added for specific functions, like in Tools.

The controlling top-level permission for cataloging will be “editcatalogue” (the old-style “viewcatalogue” may eventually be folded in). We will add VADE for several kinds of records:

• bibliographic
• summary/holdings
• authorities
• items

Resulting in 16 subpermissions. The flagsrequired hashref would look like:

• editcatalogue ⇒ “view_bibliographic”
• editcatalogue ⇒ “add_bibliographic”
• editcatalogue ⇒ “delete_bibliographic”
• editcatalogue ⇒ “edit_bibliographic”
• editcatalogue ⇒ “view_summary”
• editcatalogue ⇒ “add_summary”
• editcatalogue ⇒ “delete_summary”
• editcatalogue ⇒ “edit_summary”
• editcatalogue ⇒ “view_authorities”
• editcatalogue ⇒ “add_authorities”
• editcatalogue ⇒ “delete_authorities”
• editcatalogue ⇒ “edit_authorities”
• editcatalogue ⇒ “view_items”
• editcatalogue ⇒ “add_items”
• editcatalogue ⇒ “delete_items”
• editcatalogue ⇒ “edit_items”

These don't follow the view/add/delete/edit structure. The flagsrequired hashref would look like:

• circulate ⇒ “checkout”
• circulate ⇒ “checkin”
• circulate ⇒ “changedatedue”
• circulate ⇒ “changedateissued”
• circulate ⇒ “circreports”

To do…