Location Based Access Control — GSoC 2018 with OpenMRS
Google Summer of Code 2018 — Final Report
I am very excited to work with OpenMRS once again through this year Google Summer of Code(GSoC). Yes, I was selected to work on a project called Location Based access control in OpenMRS under the guidance of Daniel Kayiwa.
A little bit about OpenMRS
OpenMRS is an open source platform which enables the design of a customized medical records system without any of the software development experience (although it required medical and system’s analysis knowledge to use the system). OpenMRS is also a community of people working to apply health information technologies to solve problems, primarily in resource-poor environments.
OpenMRS Core is the baseline of the OpenMRS development and other modules are allowed to integrate with OpenMRS Core to expand their services and features. There are multiple distributions around the world based on the OpenMRS platform.
What is Location Based Access Control?
Currently, OpenMRS has user privileges based access control. So the user needs to have the required privilege to access some of the OpenMRS service. Anyway, OpenMRS doesn’t have any proper location control for their services. Even anyone from any location can access the stored data(eg: Patients information, Encounters, etc)in the OpenMRS. Actually, still, they haven’t concerned about the location management inside the OpenMRS. But we should prepare the OpenMRS to support the access control based on the locations. It will add more value to the data security also and accessibility also.
Like the privileges based access control, we decided to implement a Location based Access control system for the OpenMRS. It will manage the access to all services based on the locations. Some implementations want to register the users and patients (the persons also) in certain selected locations. Then access them based on the location that someone has logged in. That way, if someone is logged in a certain location, they should see only those encounters, observations, and patients registered in that location.
Anyway, the user who has multiple locations access (like Admin in our privilege based access control system) should be able to see patients in all locations. We can allocate multiple locations access to the System Developer or System administrator.
Project Plan and Deliverables
As we planned, I have started to work on this project. As the first step, We decided to implement this feature as a separate module which can be attached to any OpenMRS distributions easily. The first phase of this project is planned to carry out through the Google Summer of Code period, and later on, it will be continued with more features.
These are the deliverables from the first phase of this project through the GSoC time,
- ✅ Assign users to locations on registration
- ✅ Assign patients to locations on registration
- ✅ During an encounter, observation, and patient searches, return only those in the logged in location
- ✅ Ability to move patients from one location to another by an administrator
- ✅ Ability to assign locations to already existing patients
- ✅ Ability to assign locations to already existing users
- ✅ The login screen should not require users to select locations because, on login, you know the location to which a user belongs.
- ✅ When reports and other tools are run by a user in a certain location, they should include only those patients registered in the logged in location
- ✅ REST calls while in a certain location should return only those results in the logged in location
Implementation
I have to work for 12 weeks to complete the goal of Google Summer of Code program with OpenMRS. As the first step, I have worked on the Spring Aspect-Oriented programming(AOP) with OpenMRS which is the core part of our module. We decided to track the OpenMRS major services methods which are dealing with patients, users, persons, encounters, and cohorts to restrict by the locations.
1. Restrict the patients by the locations
The first plan of our project is to restrict the patients by their locations. So I wanted to allow the users to register the patients with the location property which will be used to track them by the locations later. OpenMRS patient dashboard can be customized to include more fields using the app definition properties. So I used this feature to attach a location selector with the Patient Registration dashboard. After this, I worked to bring this feature for the Patient EditSection which can allow users to assign the location to the existing patients. So We have provided a basic implementation to assign the locations for the patients. Then I have worked to restrict the patients by the locations using the AOP techniques. I have added the AOP Advices to track the PatientService methods which are directly dealing with the patient objects.
So as the result,
- Super Admin can only access the patients from different locations since he is the only one who responsible for the OpenMRS objects.
- Daemon threads also can access the patients from different locations since those are used to track the patients in the background to increase the system usability
- The users from Location-1 can only see the patients from the Location-1. They can’t get the information from the Location-2
2. Restrict the users by the locations
The second phase of this project was to restrict the users by the locations. The ultimate target of this goal is to avoid the location selector from the login screens while logging-in to the OpenMRS. The user registration was done in the OpenMRS AdminUI module, and I can’t make any required changes on that dashboard to assign the locations during the registrations. So we decided to add more feasibility to the user registration dashboard to customize the registration fields using the OpenMRS extension configurations which can easily decouple the modules from the AdminUI. So I worked to implement this feature in the AdminUI module — User registration dashboard, and added support to autosave the field values with the dashboard updates for Person Attributes and User properties (the third party module doesn’t need to handle the update of that field information if it configured as a personAttribute or user property, it will be automatically saved by the Account dashboard itself).
So as the result,
- Modules can create the extensions to include the custom field to the user registration dashboard(person info section or user info section)
- Modules can create the separate extensions to include the custom view fragments to view the custom field information.
Finally, I have used this feature to include a custom location selector in the user registration dashboard to allow the users for selecting the locations during the registrations. I configured to save that location information as the user property for that respected user.
3. Login without location selection
Currently, OpenMRS requires to select the locations during each user logins and that location is kept as a session variable in the web layer for the future usage. Since I have already added the feature to assign the locations to the users by the location properties, It can be able to fetch the user location again from the user property. So no more requirement to select the locations during each login. Finally, I have removed the location selection from the login screen.
So as the results,
- If the user contains the location user property, the login method will fetch that location as the session location
- If the user doesn’t contain the location user property(for existing users who haven’t the location user property) will be redirected to select the locations again.
4. Add more restrictions to the objects
So I have almost completed the location assignment part for the patients and users during the registrations. Now the time to add more restrictions for those objects by the location properties. So I wanted to figure out the solutions for,
- Restrict the encounters and observations by the locations
- Restrict the OpenMRS Reporting by the locations
- Restrict the OpenMRS Cohorts by the locations
- Restrict the OpenMRS REST Service by the locations
- OpenMRS Data Export feature should only export the information from the logged in location.
So I have worked with my mentor to analyze those scenarios and added solutions to restrict those by the locations.
5. Module First Release — v0.1.0-beta
As we completed the first phase of this project, we decided to release the very first beta version of this module for the public usage. You can get the module from the OpenMRS Add-Ons or Bintray using this following link,
Deployment
Detail module deployment guidelines can be found from this link,
JIRA Tickets and Pull Requests
Location based access control project Link to the OpenMRS JIRA : LBAC
I wanted to work on multiple components in the OpenMRS to address the location based control implementation. I have listed those tickets below,
LBAC — Location Based Access Control
RA — Reference Application
EA — EMR API module
RCM — Reporting Compatibility module
We had a brief discussion about each and every pull requests for the tickets and my mentor reviewed those pull requests as soon as possible to hurry the project implementation. Actually, he worked me to review each and every line of the pull requests to improve the code quality. I was able to learn much about the code quality and the techniques through those pull request reviews.
- LBAC-1 : Abstract design for the location based access control project.
- LBAC-2 : Assign users to the locations on registration
- LBAC-3 : Assign patients to locations on registration
- LBAC-4 : Create basic module structure for the project
- LBAC-5 : Allow to edit the patient’s locations through the patient dashboard
- LBAC-7 : Select the session location as default to the fragment location selector
- LBAC-8 : Failed to filer the patients who listed in the findPatients page before searching
- LBAC-9 : Failed to restrict the patient by location when searched using the UUID
- LBAC-10 : Failed to get the location property from the Daemon thread user
- LBAC-11 : Allow system administrator to access all the patients in the system
- LBAC-12 : Indicate the patient location information in the patient dashboard
- LBAC-13 : Create RefApp Location Global property while starting the module to change the login screen
- LBAC-14 : Add restrictions to the PersonService methods to restrict them by the locations
- LBAC-15 : Add restrictions to the UserService methods to restrict them by the location
- LBAC-16 : Failed to restrict the encounters of the patients from other locations
- RA-1503 : [AppUI] Store the session location information into the UserContext to extend the API usage
- RA-1511 : [Registration App]Allow users to customize the info message while editing the patients through section
- EA-138 : Failed to load all the patients if one patient is missing in the lastViewedPatient list.
- RA-1513 : [Admin UI] Add new account/Edit account dashboards should allow the extensions to add the custom fragments to the dashboard
- RA-1516 : [Reference Application] Add support to select the location from the userProperty in the Login Screen
- RCM-108 : Add restrictions to the ReportService methods to restrict them by the location
- RCM-109 : Need to add patient verification to return Cohorts objects for the serviceMethods
Weekly Reports and Presentation
This is the mid-term presentation for OpenMRS about the project. I have added some demonstrations about the project in this video.
Weekly Reports are listed below,
- Week-1 : Introduction to Location Based Access Control
- Week-2 : Aspect Oriented Programming (AOP)
- Week-3 : Customizing the OpenMRS Patient Dashboard with Access Location Information
- Week-4 : Location based access control for patients
- Week-5 : First Evaluations — GSoC 2018
- Week-6 : Touching the Target of Phase — 1 for Location Based access control to the Patients
- Week-7 : Adding restrictions to the users to view the patient without location
- Week-8 : Allow users to edit the patient location through the patient dashboard
- Week-9 : Second Evaluations — GSoC 2018
- Week-10 : Assign Locations to the Users through the Location Based Access Control Module — OpenMRS
- Week-11 : Say Goodbye to OpenMRS login location selection
- Week-12 : Adding more location restrictions to the OpenMRS Services — Location Based Access Control
Learning through the GSoC
Not like last, This time I was able to dive more into the OpenMRS. Yes, I had a chance to make a new module for OpenMRS this time. I have worked with Java, Spring, and Angular during the project time, and got a lot of experience for the better programming and about the quality of the code. I would like to thank my awesome mentor Daniel Kayiwa who helped me a lot during the last three months. I never felt about the remove working during the GSoC time, Since I was able to get the reply for each questions and discussions quickly from my mentor.
The OpenMRS community also helped me a lot to clarify my problems and issues during the development time in the multiple components of OpenMRS.
Again a change to…. Write Code, Save Lives….!
