Location Based Access Control Module

OpenMRS has the privilege based access control implementations. Like that one, we implemented a Location based Access control system. It will manage the access to the 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. This project was initiated into the Google Summer of Code 2018.

Module Code Repository: https://github.com/openmrs/openmrs-module-locationbasedaccess

Initially, the Location Based Access Control module provides a feature to track the patients based on the given locations. Other features will be extended and will be added into this module soon. Read the following Deployment Steps to install and run the location based access control module in your OpenMRS distribution.

Required Modules

1. OpenMRS Location based access module - v0.2.0

   Once Reference application is installed, Go to System Administration → Advanced Administration t→ Manage Modules → Add or Upgrade Module → Search for Location based access module and install it.

2. OpenMRS Core - v2.0.5 or later 

   The minimum required version of the OpenMRS Core is version 1.9. If you haven't updated version of OpenMRS Core, you should update the OpenMRS Core before using Location based access control module.

3. App UI Module - v1.9 or later (Required)

   The minimum required version of the App UI module is version 1.9. If you haven't updated version of App UI module, you should update the App UI module before using Location based access control module.

4. UI Framework Module - v3.9 or later (Required)

   The minimum required version of the UI Framework module is version 3.9. If you haven't updated version of UI Framework module, you should update the UI Framework module before using Location based access control module.

5. Admin UI Module - v1.2.4 or later (Optional)

   The minimum required version of the Admin UI module is version 1.2.4. If you haven't updated version of Admin UI module, you should update the Admin UI module before using Location based access control module.

6. Reference Application Module - v2.9.0 or later (Optional)

   The minimum required version of the Reference Application module is version 2.9.0. If you haven't updated version of Reference Application module, you should update the Reference Application module before using Location based access control module.

Deployment Steps

1. Configure Patient Registration App with Location Fragment

Patients should be allocated with the locations when they are registering into the OpenMRS to track them by Location Based Access Control module. OpenMRS Administrator or the privileged user should do some changes in the Patient Registration Dashboard to allow the locations allocations for the patient registrations. Location Based Access control module provides a fragment for this requirement, and It should be added through the App definition for the Patient Registration Dashboard. 

Please follow these steps to change the App definition of the Patient Registration Dashboard, 

1. Navigate to System Administration-->Manage Apps
2. Click the square disable button beside "referenceapplication.registrationapp.registerPatient" to disable the integrated Registration App configuration.
3. Add a new App Definition by clicking "Add App Definition".
4. Give App ID(required) as "referenceapplication.registrationapp.myRegWithLoc"
5. Then copy the following custom definition for Location Selection, and paste it to the Definition (required) field. This will be used for adding location selection fragment into the registration dashboard with some other required fragments.

6. Save the new App configuration.

If you have any issues on Registration App Configuration, please read this detail documentation.

Custom Registration App Configuration with Location Selection App Definition

You can use this following custom fragment section to add the Location Selection Fragment for the Location Based Access Control Module. 

          {
        "id": "referenceapplication.registrationapp.myRegWithLoc",
        "instanceOf": "registrationapp.registerPatient",
        "label": "Register Patient",
        "description": "Create a new Patient Record",
        "extensions": [
            {
                "id": "referenceapplication.registrationapp.registerPatient.homepageLink",
                "extensionPointId": "org.openmrs.referenceapplication.homepageLink",
                "type": "link",
                "label": "referenceapplication.app.registerPatient.label",
                "url": "registrationapp/registerPatient.page?appId=referenceapplication.registrationapp.myRegWithLoc",
                "icon": "icon-user",
                "order": 1,
                "requiredPrivilege": "App: registrationapp.registerPatient"
            }
        ],
        "config": {
            "afterCreatedUrl": "/coreapps/clinicianfacing/patient.page?patientId={{patientId}}",
            "sections": [
                {
                    "id": "contactInfo",
                    "label": "registrationapp.patient.contactInfo.label",
                    "questions": [
                        {
                            "legend": "Person.address",
                            "fields": [
                                {
                                    "type": "personAddress",
                                    "label": "registrationapp.patient.address.question",
                                    "widget": {
                                        "providerName": "uicommons",
                                        "fragmentId": "field/personAddress"
                                    }
                                }
                            ]
                        },
                        {
                            "legend": "registrationapp.patient.phone.label",
                            "id": "phoneNumberLabel",
                            "fields": [
                                {
                                    "type": "personAttribute",
                                    "label": "registrationapp.patient.phone.question",
                                    "formFieldName": "phoneNumber",
                                    "uuid": "14d4f066-15f5-102d-96e4-000c29c2a5d7",
                                    "widget": {
                                        "providerName": "uicommons",
                                        "fragmentId": "field/text"
                                    },
                                    "cssClasses": ["phone"]
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": "relationships-info",
                    "label": "registrationapp.person.relationship",
                    "questions": [
                        {
                            "legend": "registrationapp.person.relationship.label",
                            "header": "registrationapp.person.relationship.question",
                            "fields": [
                                {
                                    "type": "personRelationships",
                                    "widget": {
                                        "providerName": "registrationapp",
                                        "fragmentId": "field/personRelationship"
                                    }
                                }
                            ]
                        }
                    ]
                },
                {
                    "id": "accesslocation-info",
                    "label": "Access Location",
                    "questions": [
                                  {
                                      "legend": "Patient Location ",
                                      "id": "patientLocationLabel",
                                      "fields": [
                                        {
                                         "type": "personAttribute",
                                         "label": "Select Location",
                                         "formFieldName": "locationId",
                                         "uuid": "0a93cbc6-5d65-4886-8091-47a25d3df944",
                                         "widget": {
                                                    "providerName": "locationbasedaccess",
                                                    "fragmentId": "field/locations"
                                                   }
                                         }
                                        ]
                                  }
                    ]
                }
            ]
        }
    }

Assign the locations to the Users

You can assign the accessible locations to the users through the Manage Account dashboard.

1. Goto the System Administration → Manage Accounts
2. Edit the existing users or Add new users with the accessible locations (Make sure about the assigned privileges for that user while editing)

Login Screen Management

Location selection in the user login screen will be disabled through the Location based access control module since it can be fetched automatically through the location user property. The location based access control module will create a global property with name as "referenceapplication.locationUserPropertyName" and value as "locationUuid" while module starts (if a global property not exists in this name).

It will follow these steps while a user tries to login,

1. It will check for the Global property called "referenceapplication.locationUserPropertyName".
2. If the Global property has the value(shouldn't contains false as the value), then it will hide the location selector from the login screen
3. When users try to log in, it will fetch the location from the user property
4. If the respected user doesn't have the required user property, then it will redirect to the usual login screen(with login selector) to select the location
   
   

• How to disable the 'Login without Location' feature to rollback the location selector?

  If you want to disable this feature to get the login screen with location selector, Go to System Administration → Global Properties, and then delete the global property named as "referenceapplication.locationUserPropertyName" or set the value as "false" to that global property.

How to use Location Based Access Control module

Major features from this module are,

• All Patient, Person, and User objects are restricted by the locations. A user from a location can't get the patient/person/user information from another location.
• Able to assign/edit the locations to the patient during the registration through the patient dashboard.
  
  1. Go to Patient Registration Dashboard. You can see a new section as "Patient Location", and there will be a selection box with all active locations in your distribution. 
  2. Select a location for the patient and complete the patient registration.
  3. Go to Find Patient Dashboard, and search for the patient. You can see that person only when you logged in with the same location of that patient location which was assigned during the registration.
     
     
• Able to assign/edit the accessible location to the users through the Manage Account Page (In User section).
  • Go to Manage Account Dashboard. You can see a new field as "Location" in user section, and there will be a selection box with all active locations in your distribution. 
  • Select a location for the user and save it (Make sure about the user privileges).
    
    
• Users can login with only their credentials (username and password). There will be no need to select the locations from the login.
• Encounters and Observations are restricted by the locations to see only the information which are belongs to the user logged in location.
  
  

How to safety remove the Location based access control module

Please follow these steps to remove the Location based access control module from your system ,

1. Go to  System Administration-->Manage Apps, and Click the Edit button of the app definition(named as "referenceapplication.registrationapp.myRegWithLoc"). Then remove the "accesslocation-info" section from the app definition. Or you can just delete this App Definition, and then press the start button of the app definition which is named as "referenceapplication.registrationapp.registerPatient"
2. Uninstall the module from the system.

Resources

Location Based Access Control GSoC project