Implementing API RBAC (Role Based Access Control) & Remote Sync ( from the server) for FHIR Core -- Permission Checker

[dubdabasoduba]

Implementing API RBAC (Role Based Access Control) & Remote Sync ( from the server) for FHIR Core -- Permission Checker

Context

• FHIR Core is a health workflow-oriented app. This means it collects & stores health data which is sensitive in nature. Due to this reason, data should only be accessible to the users with correct permissions.
• This documentation is to highlight the approach we would be taking to secure the HAPI API & filter the data a user has access to based on their user assignments.
• This will piece of work will involve the following systems.
  • Keycloak -- The authentication and Authorization server used by FHIR Core
  • FHIR Proxy server -- This is a middleware to provide authentication & authorization services between a FHIR Store and Authentication providers
  • HAPI FHIR -- This is the FHIR store of choice for FHIR Core.

Permissions Checking (PermissionChecker)

Context

• Permissions -- The authorization given to a specific user that enables them to access certain resources or performs certain actions on an electronic system.
• In the case of the HAPI FHIR server these permissions will determine what resources a user can access.
• Permissions in Keycloak are referred to as Roles.

Implementation

• The implementation is broken down into 3 categories.
  • How are the permissions created and assigned to a user?
  • How are the permissions used during authorization checks.

How are the permissions created and assigned to a user?

• FHIR has a couple of resources which translate to the different ways data could be represented and retrieved. Each of these resources has an endpoint that accepts at least 4 HTTP method requests. These are POST, GET, PUT & DELETE.
• These methods will educate the permissions a user can have on any endpoint. We also have an additional Manage role
  which is a composite of the 4 HTTP methods-related roles.

HTTP Methods	Keycloak Roles	Examples
GET	GET Resource	GET_PATIENT
POST	POST Resource	CREATE_PATIENT
PUT	PUT Resource	UPDATE_PATIENT
DELETE	DELETE Resource	DELETE_PATIENT
	MANAGE Resource	MANAGE_PATIENT

• The above table shows how the HTTP methods will be mapped to the Keycloak roles. The role names are in the format of HTTP_METHOD_RESOURCE_NAME. This will be used to create the roles in Keycloak.
• These roles will be added to keycloak during deployment of the HAPI FHIR instance.
• We will use the Kycloak console to create any new roles created after the initial deployment.
• These permissions will be assigned via FHIR web during user creation.

How are the permissions used during authorization checks?

• We will be writing a permissions checker on the FHIR Proxy server. This will be a middleware that will be used to
  check the permissions of a user before allowing them to access the HAPI FHIR server.
• The workflow will be as follows.
  • The user tries to access a certain endpoint e.g GET https://fhir.labs.smartregister.org/fhir/Patient
  • The permission checker then gets the user's roles from the authentication token on the authorization header. This
    is found on the realm_access.roles key.
    • Here is a sample of the roles in the authentication token.

  {
    "realm_access": {
      "roles": [
        "realm-admin",
        "OPENMRS",
        "EDIT_KEYCLOAK_USERS",
        "VIEW_KEYCLOAK_USERS",
        "PLANS_FOR_USER",
        "offline_access",
        "default-roles-fhir_android",
        "uma_authorization",
        "ALL_EVENTS"
      ]
    }
  }

  • The permission checker then gets the resource in question from the endpoint e.g Patient
  • Using the resource name, the permission checker then checks if the user has the GET_PATIENT role.
    • If the user has the role, the request is allowed to proceed to the HAPI FHIR server. If not, the request is denied
      and a 403 Permissions denied error is returned to the user.

Workflow UML Diagram

Pre-requisites

• The user authentication should have happened for the user to receive the authentication token.

[pld]

lgtm! what is the MANAGE resource KeyCloak role?

[dubdabasoduba]

It's a composite role of all the 4 roles a resource can have.

[peterMuriuki]

HTTP Methods Keycloak Roles Examples
GET GET Resource GET_PATIENT
POST POST Resource CREATE_PATIENT
PUT PUT Resource UPDATE_PATIENT
DELETE DELETE Resource DELETE_PATIENT
MANAGE Resource MANAGE_PATIENT

[DRAFT] Proposal for enhanced keycloak role definition syntax.

the current role definition structure is <FHIR_RESOURCE>_<GET|UPDATE|POST|DELETE|MANAGE>.

This works, so this is more of an enhancement to the ux when dealing and developing role based functionality.

I propose a structure that looks like the following: <fhirResource>.<[cruds]>. Where c -> create, r -> read, u -> update, d -> delete, s-> search.

The upside here will be the ease of creating composite roles.
For instance if we are to create a role to fetch,create or delete organizations. We would need to create 3 roles as follows: GET_ORGANIZATION, POST_ORGANIZATION, and DELETE_ORGANIZATION.
Under the new scheme this can be compressed to one single role i.e Organization.rcd.

everything is now in small-case so that its not scary to look at. The FHIR resource name should be as it appears on the FHIR spec i.e using PascalCase.

A trivial advantage is that this could potentially reduce the size of tokens for users with the same roles assigned. (inadvertently reducing size of request packets data that needs to be sent for each authenticated request).

cc @dubdabasoduba @pld

[pld]

Re-reading through the table above, I realize it wasn't clear to me what exactly is created in keycloak, I thought it was a 4 roles, but on re-reading, it looks like it was all the resource_method combos.

Why search instead of manage?

Wouldn't we then need keycloak roles for all the possible combinations of cruds?

Whichever method we use, is there a way we can avoid need to create all these combos?

[peterMuriuki]

Re-reading through the table above, I realize it wasn't clear to me what exactly is created in keycloak, I thought it was a 4 roles, but on re-reading, it looks like it was all the resource_method combos.

Yeap, currently we would have at-most 5 roles for each resource.

Why search instead of manage?

Added search because its a distinction that several apis with rbac make, for instance keycloak itself has roles for view_users, and query_users, such that:

• view-users role provides basic viewing access to user details and attributes.
• query-users role allows for more advanced querying and searching capabilities to find specific user information within the Keycloak admin console.

It could be q -> query or s -> search or just leave it out if its not a distinction we need to make for our services.

Manage directive would no longer be necessary, its equivalent would be to specify all [cruds] actions e.g Organization.cruds

Wouldn't we then need keycloak roles for all the possible combinations of cruds?

yes, though not necessarily, worst case this would require the same number of roles as we currently have.
In the best case, you could end up with just a single role per resource. for instance if one need's to represent only 2 permissions for the same resource.

Whichever method we use, is there a way we can avoid need to create all these combos?

🤔 , I'll stew on this for a while, and revert back.