This document is to illustrate how access control will be enforced on OpenSRP. Currently, access control is not enforced and as long as a user has access they can access any API’s. This is a major security flaw as it can lead to illegal access to information

Assumptions

• Keycloak is used for user and identity management

• OpenSRP team management is used to control which teams a user belongs to

• OpenSRP locations are used

Roles and permissions

Users will be granted roles or permissions on Keycloak.

Users can also be assigned to a group on keycloak which have been assigned roles and permissions. Users will automatically have access to roles and permissions assigned to groups.

Roles are high-level permissions that can be assigned. A role is made of several permissions.

We may have a role called Provider, Administrator which is mapped to several permissions.

Permissions are an abstract grant for a resource e.g View Events, Add Events, etc

Role and permissions Mapping

For the MVP it would be ideal if there is no mapping of permissions and roles between OpenSRP and keycloak. This would imply that those roles assigned in keycloak are the ones OpenSRP expects there is no mapping e.g where in Keycloak we define roles that are implemented as permissions on OpenSRP

Use Keycloak composite roles to ease the administration of roles.

Fine-Grained Access Roles and Permissions

Each resource will have fine-grained permissions that are required to interact with the resource. By default we should have 2 roles or 4 roles per resource for the CRUD operations.

2 roles per Resource

• Have a View Role and Manage role

• View Role allows one to view data

• Manage Role allows one to create, edit and delete data

4 roles per resource

• Create a role that allows one to create data

• Update role that allows one to edit data

• Delete role that allows one to archive/delete data

• View role that allows

Roles that not CRUD related need to be defined by resource e.g

• Sync Role that allows access to sync APIs for supported APIs

• Custom permissions depending on possible operations on a resource e.g

  • Organization resource has to assign Jurisdiction permission

  • Location resource has filter/search permission that is used to search locations

  • Plan resource has a generate tasks permissions

The permissions or roles will control access to APIs

Nifi and external systems access

A user will be created for each external system that needs to access data from OpenSRP. The user will be assigned the roles or permissions needed to access only the resources necessary.

A Nifi user will for example be assigned with permissions for the Get All endpoints which enables NIFI to get all data for ETL.

If Nifi or an external user is posting data to OpenSRP these permissions will need to be assigned

Access control via Organizations, Provider and Locations,

Separation users from practitioners

Permissions should be defined on Users and groups of users and not practitioners. This will enable users who are not practitioners to have access to OpenSRP.

Users should still be tied to a location which will be used to enforce they only see data that belongs to that location.

Practitioners will be tied to the location via the Organization that they belong. There should be superuser access that allows privileged users to bypass location checks.

Organizations, Locations and Providers

Organizations, locations and providers will be used to filter access to APIs.

APIs that filter with Organizations, locations and providers will be checked to confirm that the parameters are valid and the user has access to the data requested.

• If a user requests data for location X while they belong to location Y then the request will be denied.

• If a user searches for data e.g using names then the data will be filtered by user assigned organizations and/or assigned locations. This will mean credentials will only access that belongs to the managed/assigned organizations only.

Superuser privileges will be added to enable a global search on some API’s used on the client-side.

Flow chart detailing how access control

OpenSRP permission table

Role management in Deployment scripts

Permissions that OpenSRP expects will be many to manually define in keycloak. We need to be able to automate role definition so that we are able to import roles using deployment or configuration scripts in keycloak.

Exporting and importing will not work effectively whenever new roles are added.

Custom Roles

Using keycloak it shall be possible to add custom roles. These roles should be composite and should import the roles required to ease the administration of roles.

• If a project wants to define a role called CHW that is mapped to EVENT_SYNC, UNIQUE_ID_GENERATE, etc this should be possible in keycloak. Users or groups can then be assigned this role instead of the fine-grained permissions.

Naming conventions

It's important to have a naming convention that will make it easier to differentiate between permissions, OpenSRP roles, and Custom Composite roles

Suggestions

• Permissions to have a suffix PERMISSION

• Roles to have prefix ROLE

• Custom Roles to have prefix CUSTOM_ROLE

Implementation

• For each role, we shall have admin permission that will be used to provide superuser access

• CRUD Roles will be required to create, read, update and delete entities

• Permissions will be enforced at the individual object/entity level e.g if a user has a role to View plans, they will only view plans that they have access to

• Admin privileges will be used to override access for object permissions above