Authorization module 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.

• Table of contents
• Authorization module design
  • The basic entities
  • The structure of an access rule
  • Supporting the idea of roles
  • Summary of tables
  • Loading an access profile
  • The access-rules tree
  • Checking access

This module is not specific to any business application. It can be used anywhere. It can be implemented as a web service, with its own small set of web service calls, and therefore can be deployed as a standalone sub-module with very clean separation from the rest of your business application. It has its own database, and can be installed in its own Docker container too if needed.

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, 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. The string format shown in these examples are built into the design, but the string content is not. In other words, you don't need to start with /ws/ or /ui/ -- you can start with /acct/ for the Accounts module or /ho/ to define a sub-tree related to all Head Office operations. It's entirely up to you.

• 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. One can always a fourth column, optional, to hold a human-readable description of the role. Plus, there are the administrative and audit columns...

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 perform the operation.

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 to separate the key-value pairs.

The access-rules tree¶

Shown below is a sample of the rulestree generated in the previous section.

The tag or label against each node is the value of the resource attribute of the access rules attached with that node. The root node is labelled "/".

All access rules associated with the current logged-in user will be in this rulestree, attached with one or other node in the tree. All access rules with resource == "/hr/payroll" will be attached with the node shown here, labelled "/hr/payroll". It is implicit, therefore, that the value of the resource attribute must always be in the form of a path, whose components are alphanumeric and the separator is the "/" character. This syntax must be followed for the tree to be created from the rules correctly.

We look at three example access rules below. Unique ID and optional NULL attributes omitted from examples.

usertype: U, who: sanjeev, resource: /hr/payroll, action: create

usertype: G, who: hrteam, resource: /hr/payroll/tds, action: get

usertype: U, who: sanjeev, resource: /hr/payroll/tds, action: update

The second rule grants TDS (Tax Deducted At Source) data viewing rights to all members of the hrteam user-group. The first and third access rules are specifically for one user, sanjeev.

If we assume that the user-group hrteam includes the user sanjeev, then all three access rules will be present in the rulestree created when user sanjeev logs in. The first access rule will be attached to the node labelled "/hr/payroll", and the other two to the node labelled "/hr/payroll/tds".

Our examples above have shown each rule with three attributes, to illustrate a simple sub-set of possibilities. The full-fledged design actually works with five attributes per rule: the "relation" and the "part" are also supposed to be there as optional attributes of a rule.

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 all 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.

The tree will be traversed from the root downwards, by matching the resource value passed as parameter to is_allowed() with the labels or tags of each node. At each node of the tree, any access rules which match the current call to is_allowed() at the current node will be acted upon first. If no matching access rule is found in the current node, then the traversal will move to the next node one level down in the tree. This will continue till a matching access rule is found, or the full path of the input resource parameter is complete and no match is found, or there are no further matching nodes in the tree as per the path indicated by the resource parameter.

We look once again at the earlier three example access rules below.

usertype: U, who: sanjeev, resource: /hr/payroll, action: create

usertype: G, who: hrteam, resource: /hr/payroll/tds, action: get

usertype: U, who: sanjeev, resource: /hr/payroll/tds, action: update

Once again, we assume that user sanjeev is a member of the user-group hrteam, therefore all three rules will be part of the rulestree of sanjeev.

Now some example calls to is_allowed() will be applied to this set of access rules.

Example 1

is_allowed(rahul, /hr/payroll/tds, NULL, NULL, NULL, get)

where user rahul is part of the hrteam user-group. In this case, the second access rule will result in is_allowed()
returning TRUE.

Example 2

is_allowed(rahul, /hr/payroll/tds, 8a3a8509, NULL, NULL, get)

In this case too, is_allowed() will return TRUE, because a specific instance ID in the call will match a rule which is instance-agnostic (i.e. where the instance attribute is NULL, thus indicating that the rule applies irrespective of any instance-ID). The second access rule would therefore apply.

The same result would have been seen if the relationship parameter in is_allowed() had specified a value. This is because the access rule is relationship-agnostic, since its own relationship attribute is NULL.

Example 3

is_allowed(sanjeev, /hr/payroll/tds, NULL, NULL, NULL, create)

In this case, the traversal through the tree would have returned from the node labelled /hr/payroll, since that node would have the first access rule, and it would have given user sanjeev the create permission to /hr/payroll and all sub-nodes and lower-level resources below it.