Global

# Authorization module: core design

The authorization module uses a set of rules in a rulebase to decide who can perform what action on what object. "Who" here is a human user, "what action" is an operation performed on a computer system like a voucher entry, a report viewing, or the adding of a new task in a task tracker. "What object" here means an information entity like a salary record, a voucher, a task list, *etc*.

{{>toc}}

This page describes a design which we can use for any traditional business application.

## Features

* *Application independent*: can be used with any business application

* *Useful for front and back*: it is useful for web service calls to decide whether the curent caller can be permitted to execute the call, and is also useful for Javascript code in the front-end to decide whether to display certain buttons or sections of screens at run-time, depending on a common set of access rules. The set of access rules which apply to a user session are described in-memory in a JSON tree data structure.

* *Supports access per object instance*: it supports access controls for specific operations on specific object instances too, *e.g.* can User `rohit` update rates and terms on a specific Purchase Order? This is very powerful for large, critical and long-lasting object instances like tender bids, project plans for large projects, *etc*

* *Associate an access rule with a part of an object*: an access rule can carry additional information which associates a part of an object with a permission, *e.g.* this edit permission applies to Section Two of a specific bid document.

* *Language independent*: may be implemented in any programming language

* *High performance*: requires some data structure processing at user login time, but can then be accessed for very fast go-no-go lookups with each operation or web service call

## The basic entities

Any authorisation system deals with the following entities:

* **user**: the human user

* **data objects**: the item, or set of items, or class of items, on which operations are being performed

* **operations**: the operations being attempted

* **permissions**: rules which specify which combinations of the above three entities are permitted. All else are blocked.

Additional derived entities, defined for convenience, are

* a group of users, called **user groups**

* a group of permissions, sometimes called **roles**

This design assumes that there is a user master table, a group master table, and a groupusersmap table which maps users to groups of which they are members.

## The structure of an access rule

We need to understand the demands on the access rule.

In its simplest form, a rule will just have three parts:

* which user the rule applies to: *e.g.* "user `sanjeev`"

* which entity the rule applies to: *e.g.* "vouchers" (a class of objects, not just a single object)

* which operation is being permitted by the rule: *e.g.* "create"

This three-part rule says "User `sanjeev` can create vouchers".

For simple designs, this can even be combined to a two-part rule:

* the user (`sanjeev`)

* the privilege (`vouchercreate`)

where you combine the class of objects with the operation name and call this combined thing the privilege being given.

We need more sophistication than this for more complex business applications.

* **Access to a specific object**: we may want to give User `sanjeev` access to modify a specific indent or purchase order, but not give him the right to do the same with all indents or purchase orders. In our language we are giving a user *ad hoc* access to a specific *object instance*, not a *class of objects*.

* **Access to a sub-object**: we may want to give User `sanjeev` access to the Vendor Details section of a specific purchase order, not all sections. We may want to give User `galahad` access to Tax Computations section of the same purchase order. This requires our access rule to have the ability to refer to a sub-object.

* **Relationship based access**: we may want to give a specific access to a user if he has a specific relationship with the object instance, for instance the user who created a new Purchase Order has edit rights to it, but others in his department only have read-only access.

Note that the complexity of a sub-object reference only comes when we need to give a user rights to a specific sub-object of a *specific object instance*. If we had to give the user rights to a sub-object of a whole class of objects, then we would just have re-defined our object definition to refer to a specific section of the object, not the whole object. For instance, if we needed to give `sanjeev` access to the Vendor Details section of *all Purchase Orders*, we would simply have re-defined our object to refer to "`povendorsection`" instead of the entire "`po`". And then we would have given `sanjeev` the access to all `povendorsection`. The real complexity comes when we want to give `sanjeev` the access to the Vendor Details section of *a specific Purchase Order*. In that case, we need to add a new attribute to the access rule.

So, the final structure of an access rule can be as follows:

* **ID**: a mandatory, unique ID, the primary key for database access and cross-reference purposes.

* **usertype**: one char, with "`U`" for user and "`G`" for user-group. Mandatory, non-NULL

* **who**: string, will contain a username or a groupname. Mandatory non-NULL. A "`*`" here means that this rule applies to all users without exception.

* **resource**: string, will specify the resource on which the access control will apply. This may have a path notation to identify a module or sub-module in a hierarchy. This allows us to specify an access control at any level of a hierarchy. Possible values could be "`ui/fa`" meaning the UI components of the Financial Accounting system, or "`ws/fa`" meaning the web services of the FA system, or "`ws/fa/vouchers`" to indicate web services of voucher management within the FA system, and so on. Mandatory, non-NULL.

* **instance**: string, may contain the ID of a specific resource instance of the type or class indicated by **`resource`**. For instances, if the **`resource`** fields specified "`ws/fa/vouchers`" and the **`instance`** has the value "`20a00bce`", then this is the unique ID of a specific voucher on which the access control is being applied. Optional, may be empty.

* **part**: a value indicating a section or part of the object instance on which the access control is being applied. The object instance itself is identified in the **`instance`** attribute above. Examples could be "`vendordetails`", "`candidate[02]`" (for the second candidate in a list of candidates), and so on. Optional, may be NULL.

* **relationship**: a value indicating the relationship the user must have with the object for this access to be applicable. This value should be from an enumerated set of possible values. Optional, may be NULL.

* **action**: a value indicating the operation being permitted, from the enumerated set of all possible operations. For UI related operations, values could be `show`, `edit`, `delete`, *etc*. For web services, operations could be `get`, `update`, `create`, *etc*. There could be any number of possible operations, and a complete set can only be defined in the context of the application and the business operations it supports.

If the system permits it, the **`action`** attribute may be multi-valued, and can carry a list of operations which are permitted. If the system does not support multi-valued attributes, the entire rule will have to be repeated in the database table for each valiue of **`action`**.

## Supporting the idea of roles

A role is a collection of access rules. It's a convenience. If all Sales Executives need to be given a set of 23 access permissions, it's nice to be able to group them into something called a "role", and then assign permission to users based on such roles.

A Roles master can contain the following useful fields:

* **ID**: the mandatory unique ID column

* **descr**: a string description of the role, for human consumption

The access rules table's **`who`** attribute, which is already capable of holding usernames or user-group names, can now be extended to hold role IDs too, and the **usertype** attribute will then contain "`R`". This means that

* an ordinary user can be linked to an access rule,

* a user-group can be associated with the rule, or

* a role can be associated with it

In addition to this, a roles mapping table is needed, to map a role to either individual users or user-groups. This table will have just three columns:

* **role**: the ID of the role record in the Roles master

* **usertype**: a single-character field, holding "`U`" or "`G`"

* **who**: the username of a user, or the groupname of a group

All columns here are mandatory non-NULL, and the uniqueness criterion will apply to the entire 3-tuple.

## Summary of tables

* **`accessrules`**

  * **`ID`**

  * **`usertype`**

  * **`who`**

  * **`resource`**

  * **`instance`**

  * **`part`**

  * **`relationship`**

  * **`action`**

* **`roles`**

  * **`ID`**

  * **`descr`**

* **`rolemembersmap`**

  * **`role`**

  * **`usertype`**

  * **`who`**

## Loading an access profile

When a user logs in to the application, her access profile should be loaded from database into in-core storage or a fast cache so that it can be traversed rapidly at each subsequent request or operation to check whether the user is permitted to do so.

```

load_access_profile(user, rulestree)

    groupslist = load all user-group names from groups table

            where user is a member

    roleslist = load all roles from rolemembersmap where

            (usertype == 'U' and who == username) OR

            (usertype == 'G' and who exists in groupslist)

    ruleIDlist = load the IDs of all rules from accessrules where

            (usertype == 'U' and who == username) OR

            (usertype == 'G' and who exists in groupslist) OR

            (usertype == 'R' and who exists in roleslist) OR

            (who == '*')

    // we now have the IDs of all the rules which apply to this user

    // We now convert the set of lists into a tree data structure,

    // based on the paths in the "resource" attributes of the rules.

    // Any rule with "resource" == "ui" or "ws" or just a one-part

    // path will be associated with a Level 1 node just below the root.

    // Any rule with "resource" == "ui/fa" will be associated with

    // a Level 2 node, labelled "fa", below the "ui" node. And so on.

    //

    // Each node in the tree has a set of one or more access rules and

    // their associated attributes.

    rulestree = rules_list_to_tree(ruleIDlist)

end procedure

```

This process creates an in-memory tree data structure which can be traversed very efficiently whenever a specific access is attempted.

If the tree data structure needs to be kept in a shared network-accessed cache, *e.g. memcached or Redis, then this is possible by using key-value pairs, where the tuple of `(username+resource+seqno)` becomes the key, and the rest of the access rule becomes the value. If there are half a dozen access rules for the same resource and username, there will now be six key-value pairs in Redis for this. The `seqno` will be used, as an incrementing integer, to separate the different key-value pairs. Lookups can be efficient if the cache supports a single call to query all matching key-value pairs which have a common matching key prefix.

## Checking access

Whenever any access is attempted, a function "`is_allowed()`" is called, which traverses the "`rulestree`" created in the loading step, and returns a boolean "`TRUE`" or "`FALSE`". The "`is_allowed()`" function is called with:

* `user`: the username of the user who is attempting the operation

* `resource`: the resource type being operated upon. May in some cases just identify a module or a resource class.

* `instance`: the unique ID of the specific instance of type `resource`, *e.g.* Purchase Order ID or voucher ID. May be null for certain operations, for instance an operation which impacts all or many instances of the resource type

* `part`: a path string indicating the sub-part of the resource which is being operated upon. This may be NULL.

* `relationship`: a value indicating a specific relationship between user and resource. May be NULL.

* `operation`: an identifier indicating what is the operation being attempted.

```

boolean

is_allowed(user, resource, instance, part, relationship, operation)

    patharray[] = break resource into parts at "/"

    thisnode = rulestree    // initialise to the root node of tree

    for each pathstep in patharray[] do

        if any of the rules at thisnode matches the other parameters of the call, then

            return TRUE

        else if thisnode.childnode corresponding to pathstep exists then

            thisnode = thisnode.childnode

        else

            return FALSE

        endif

    endfor

    return FALSE

end function

```

This function will be called by every web service call which requires authentication, and if the `rulestree` data structure is passed to the front-end Javascript code at login time, then it can be used by the front-end code too, to decide which UI segments to display or hide.