Role Based Access Control

Understanding Role Based Access Control in OpenLMIS

UPDATE: Activity, sequence and class diagrams for RBAC implemented in v3

OpenLMIS uses a basic RBAC mechanism for granting access to certain capabilities, called rights, by grouping those capabilities into named buckets called roles.

This basic structure is then further refined by applying basic roles to users by Programs, Supervisory Nodes, ~~Delivery Zones~~ and Facilities. Of these, applying roles to Supervisory Nodes is the most complex as the hierarchical nature of supervisory nodes leads to rights applied to a supervisory node potentially effecting the capabilities a user has with all children supervisory nodes and facilities.

From a user's perspective these rights when applied to the other structures described above allow a user to either interact with general operations of OpenLMIS or more typically specific roles within the supply chain.

This is seen on a User's Profile as roles assigned under various headers / buckets:

As well as the Roles management screen as rights grouped into various buckets:

These general buckets are:

Example RBAC Class Diagram

Role types and their associated rights

Supervision

Supervision Rights are used in a variety of situations where we'd like to give a user some capabilities within an administrative hierarchy, typically to some aspect of the supply chain focused at Facilities, divided by Program. While this type of right grew out of the supervisory nature of most requisition processes, it has expanded to apply to equipment management, stock management, and fulfillment.

While Supervision Rights typically need to be associated to a user by a Supervisory Node and Program, if a user has a Home Facility, then rights of this type can actually be applied directly to that Facility by Program. When these rights are applied directly to a User's Home Facility, then we don't have to reason about any administrative hierarchies. However most of the time we consider supervisory rights, we have to reason about the hierarchy they might apply to given the structure defined by the Supervisory Nodes and Programs they are assigned by.

This role type allows users rights to requisition, stock management, CCE, and orders processes.

Must be associated with a Facility (Home Facility and/or Supervised Facilities)
Assigning a Home Facility associates Supervision rights to the facility designated. The user's home facility will determine their access in Requisition and Stock Management
To enable Supervision related rights for other facilities a Supervisory Node must be assigned
Must be associated with a Program and a Role for Home Facility supervision
Must be associated with a Program, Supervisory Node, and Role for other facility supervision

Supervision rights in Requisition

If a right isn’t assigned within a role, the user will not have access to complete that specific function. For example, assigning a Supervision role to a user will not give them access to approve requisitions unless the Approve Requisitions right is checked within the Supervision role. A user may have the rights to delete a requisition, but the system checks whether the status of the requisition will allow for the requisition to be deleted. If a requisition has been Authorized, a user cannot delete the requisition even if they have the rights assigned. This requisition would need to be rejected by a user that has the role and right to approve a requisition.

View requisition (REQUISITION_VIEW):

Any user that needs to access requisitions should have the View requisition right. A user that may only need to view requisitions and not make any edits or take any actions on the requisition should be assigned this right.

Authorize requisition (REQUISITION_AUTHORIZE):

A user with this right can authorize a requisition once its been submitted. If a user has the Authorize requisition right, they should also be assigned the View Requisition right.

Create requisition (REQUISITION_CREATE):

A user with this right can initiate and submit a requisition based on their facility and program assigned. They also have the right to edit an initiated requisition until it has reached the Authorized status. If a user has the Create requisition right, they should also be assigned the View Requisition right.

Delete requisition (REQUISITION_DELETE):

Most users with access to requisitions will have this right, but the ability to delete a requisition is also based on the requisition status (as explained in the Requisition States and Workflow diagram above). If a user has the Delete requisition right, they should also be assigned the View Requisition right.

Approve requisition (REQUISITION_APPROVE):

Users with this right can approve requisitions once they have been submitted, and they will also have the right to Reject a requisition that is in the submitted status. If a requisition is in the authorized status, this right allows the user to edit the approved quantities in the requisition. If a user has the Approve requisition right, they should also be assigned the View Requisition right.

Example of Supervision rights relating to Nodes and Facilities in a Requisition:

The following diagram attempts to show a simple structure and how Supervision Rights apply within that structure, note that this is all in one program:

Supervision Rights Diagram

Storeroom Assistant: supervisory rights create and view requisition on his/her Home Facility.
W. Clinic Director has supervisory rights on his/her Home Facility to authorize the requisition.
D. Supervisor has supervisory rights to approve the requisition on the supervisory node D. Supervision. This is enabled as D. Supervision supervises the Requisition Group of which W. Clinic is apart of.
R. Supervisor has supervisory rights to approve the requisition on the supervisory node R. Supervision. This is possible as R. Supervision is the parent/supervisor of the D. Supervision node.
R. Fulfillment Officer has order fulfillment right's on R. Hospital. This now leaves the requisition process so the diagram stops, however note that this is enabled as the R. Supervision node is associated with R. Hospital.

Supervision Rights in Stock Management

Edit Stock Inventories (STOCK_INVENTORIES_EDIT):

A user with this right can create a physical inventory and can submit a physical inventory within a specific Program and Home Facility. The STOCK_INVENTORIES_EDIT right only works with a single Program. So if a user should have permissions to conduct physical inventories for multiple programs, you would need to assign the right individually for each program to that user.

Adjust Stock (STOCK_ADJUST):

A user with this right can make a stock adjustment, potentially altering the SOH, for any Orderable that is part of a specific Program and HomeFacility/Node.

View Stock Cards (STOCK_CARDS_VIEW):

Can view all the stock cards and line items for any Orderable that is part of a specified Program and HomeFacility/Node. Viewing the stock card with all its line items, including all historical line items, and printing. Viewing and printing an SOH summary showing a stock card's SOH

Supervision Rights in Cold Chain Equipment Management

View Cold Chain Equipment Inventory (cceInventoryView):

A user with this right can view all CCE equipment inventory for the facilities that they are assigned.

Edit Cold Chain Equipment Inventory (cceInventoryEdit):

A user with this right can make edits to the CCE equipment inventory for the facilities that they are assigned.

Supervision Rights in Orders

View Proofs of Delivery:

A user with this right can view all Proofs of Delivery for the facilities that they are assigned.

Manage Proofs of Delivery:

A user with this can edit all Proofs of Delivery for the facilities that they are assigned. If a user has the Manage right, they should also be assigned the View right.

Fulfillment

Order Fulfillment Rights give capabilities to a user to create orders, view orders, fulfill orders, and view and edit shipments. This type of Right associates a User with a specific Facility for which these capabilities are allowed. The type of facility typically allowed to have fulfillment based rights are ones that supply others.

This role type allows users rights to fulfillment activities, and managing orders once a requisition has been approved.

Must be associated with the facility
Is not associated with a Program because the rights are associated with the facility
Order creation has historically been the capability of the facility that will fulfill the order

Fulfillment Rights in Orders

View Orders:

A user with this right can view all orders for the facilities that they are assigned.

Edit Orders:

A user with this right can create an order or convert to order for the facilities that they are assigned.

Transfer Orders:

A user with this right can retry the FTP transfer for External Fulfillment if the FTP transfer fails and the order status is Transfer Failed.

View Shipments:

A user with this right can view all shipments for the facilities that they are assigned.

Edit Shipments:

A user with this right can fulfill orders by editing or deleting shipments for the facilities that they are assigned. If a user is assigned the Edit shipments right, then they should also be assigned the View Shipments right.

Administration

These rights are generally 1:1 with some administrative or management capability such as Viewing a Facility List or Editing/Managing the Facility list. Rights of this type are granted to a user directly without any other structure such as Program or Facility applied.

This role type allows users rights for administrator functions that make updates system-wide.

Is not associated with a Program or Facility because the rights are system-wide

Administration rights in Stock Management

Manage stock card templates (STOCK_CARD_TEMPLATES_MANAGE):

Can configure the stock card templates by program

Manage stock destinations (STOCK_SOURCES_MANAGE and STOCK_DESTINATIONS_MANAGE):

Can configure the valid sources and destinations for all programs/facilities in the system.
Assumption: since this functionality is not in v3.1 scope, it may be removed or disabled before release.

Manage stock card line items reasons (STOCK_CARD_LINE_ITEM_REASONS_MANAGE):

Can configure the reasons, including which reasons map to which facilityTypes and programs, and which reasons will display in stock management and requsitions for user selection.

Reporting

Like Administration rights, Reporting rights are granted to a user 1:1 with some report that exists in the system. Here report is used to describe an analytical reporting of OpenLMIS configuration, functionality or supply chain operation and therefore having such a right as a user implies you have access to the specific report.

This role type allows users rights for requisition reports, or other system related reports.

Is not associated with a Program or Facility because the rights are system-wide
having the ability to view a report says nothing about the right's that the report has. i.e. a user granted the right to view a report on the functioning of the supply chain means to OpenLMIS that they can retrieve the report. It's up to the report's implementation to ensure that any other RBAC-based permissions, such as limiting a user to only a specific Program, are followed.
Adding reports to and removing them from OpenLMIS is a common occurrence in many deployments. Because of this the functionality that adds a report to OpenLMIS is also responsible for adding a new right to view that report to the RBAC mechanism.