Implementing Access control in OpenSRP
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
Resource | Actions | Permission |
All Resources | Create Update Delete View | {ENTITY}_CREATE {ENTITY}_UPDATE {ENTITY}_DELETE {ENTITY}_VIEW |
All Resources that have sync | Sync | SYNC_ENTITY |
All Resources | All actions | MANAGE_ENTITY(composite role in Keycloak) |
Organization | Assign location View assigned Locations | ORGANIZATION_ASSIGN_LOCATION ORANIZATION_VIEW_LOCATIONS |
|
|
|
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
This site is no longer maintained. Please visit docs.opensrp.io for current documentation.