Support authorization to resources and resource content based on server defined permissions

[vincent-karuri]

This is a broad issue that includes support for login on the device, ACLs for users and general user administration support. This is supported on OpenSRP core through OAuth/Keycloak. This is a requirement on G6PD.

[pld]

We're planning to use Keycloak as well for this, and have a Keycloak to HAPI integration behind the scenes, here's draft architecture, we're planning to go with option 1 in this document for now then move to 3 when it's relevant/useful, since 1 is a prereq anyhow to 3

CC @manutarus

[vincent-karuri]

Cool, I see 1 is marked as low effort and seems like much of the work may be defining ACL rules. Do we have a strategy for that? Are we going with something basic at first?

[pld]

I think ACL is handled by what FHIR teams and locations a practitioner or client is linked to

@manutarus @dubdabasoduba is that correct?

[pld]

This handles the authn, #40

If we confirm authz is handled by associating fhir resources, this issues sounds covered

[vincent-karuri]

Authentication is two-fold (client and server) so we might still need to consider how we handle authentication on the client (most likely using AccountManager similar to OpenSRP).

[pld]

Cool true, we also need to define what parts of this are SDK vs fhircore, from discussion some of the authn logic will go in SDK

[dubdabasoduba]

I think ACL is handled by what FHIR teams and locations a practitioner or client is linked to

@manutarus @dubdabasoduba is that correct?

1. I think this association (between practitioners & teams/locations) just controls access to patient data a practitioner can access.
2. We also need to restrict the specific resources endpoints. i.e if someone is just assigned roles to access patient and any other patient-related resources then they can't access the locations resource endpoints or the teams' resource endpoints.

[dubdabasoduba]

For point 2 above
I think we need the following.

1. Functionality to checks roles assigned to a user/practitionerner on keycloak
2. Functionality to check whether the user/practitioner has the correct roles required to access a particular resource

[pld]

I'm also going rename this issue to be about authz, we can add any additional notes on authn here, #40

Hmm, yea good points, I think this relates to a discussion yesterday and these notes here, #23 (comment)

My bias was that authz be handled by server, the client says give me all my data the server figures out what "all" means, including deciding "all" is a subset because of bandwidth constraints.

[f-odhiambo]

Location mapping being tracked here

[maimoonak]

Does this also include restrictions over a particular type of data of a resource? For e.g. visit-types including/excluding (type1, type2, type3...). For example we may want to give a caregiver access to all people in a catchment with only specific visit/encounter types.

[vincent-karuri]

The way I see it, there are two layers to this:

1. ACLs that provide rules about what roles are allowed to access certain endpoints
2. If a user is allowed to access a certain endpoint, what are the filter parameters that they can specify to get data e.g. are they allowed to access data outside of their team, location etc.

I don't think we've considered fine-grained control at the level what type of visit/encounter it is though but this could possibly be an extension if we provide a general framework for defining 2.

[maimoonak]

FHIR defines a very thorough security protocol https://www.hl7.org/fhir/security.html#6.1.0.5.1 . Apologies if it seems repetitive or has been discussed already. I am still exploring it.

[vincent-karuri]

no worries, please add any findings missing here.

[maimoonak]

Since authz is to be implemented on both sides i.e. client and server we need to consider following as well when implementing on client side

FHIR divides resources under 5 categories https://www.hl7.org/fhir/security.html#SecPrivConsiderations

1. Anonymous READ Access Resources
2. Business Sensitive Resources
3. Individual Sensitive
4. Patient Sensitive
5. Not classified

We need a mapping/tag where we know what resource falls into what category. The mapping could be via Keycloak Policy OR FHIR security labels https://www.hl7.org/fhir/security-labels.html.

As soon as request reaches server it is validated and gets a response of 403 which would be handled by client. (Failures should be logged and sent as stats to dev team so that they can know if any policy has changed and device is not handling it)

# 1 , # 4 | Metadata : For # 1 and and # 4 we need to make sure to mark all metadata resources (Types, Codes, etc) with this so these are never rejected or evaluated for further ACL rules.

# 2 | Questionnaires, Careplans, Structures or Households: # 2 These should be shared based on certain attributes of logged in user Attributes based Policy of Keycloak.

# 3 | Users, Caregivers , The full info is available to only self OR specific roles (admin, office worker, web app user, Supervisor etc).
Basic info is available to any user reviewing particular record. Ex. A user should not be able to see full caregiver info from patient resource, however, he should be able to see who was caregiver i.e. firstName, lastName etc

# 4 | Patient, Encounters, Observations, etc. This one is complex and we need to implement a complex mechanism. Each data should be validated by type, location, team, and the type of property itself.

Just a thought - We can also add a post processor where we can trim down the info which is no relevant to user i.e. replace data with text < not authorized >.

We need to make sure that

• Server does not allow anyone get extra info
• Client does not request for info he is not supposed to

Starting with Keycloak and basic login and would further add here

[maimoonak]

Since we are working on relying on Keycloak for fhir-auth. Keycloak is very powerful and can provide complex ACL as well which we can make use of. There are multiple approaches towards this

1 . Use keycloak out of the box and rely fully on this
-makes fhir module dependent on Keycloak
-directly call keycloak api - client managing two tool
+can save alot of effort rightnow (adding a complete ACL on fhir)

2 . Use Keycloak for auth and token only
-alot of effort on development of ACL
+no dependency on keycloak and it can changed later on
+allows for handling custom logic if needed in future but it can still be implemented by add further interceptors

3 . Use keaycloak but route everything via fhir-auth-module
-duplication and an extra effort
-maintaining policies would need changes on both sides
+in future it can be replaced with any other oauth server

[pld]

thanks @maimoonak! A keycloak dependency is not something we're worried about, we already have that as a hard dependencies because of how users and locations are managed through the web UI.

In (1) how is the ACL coded in keycloak enforced on against HAPI resources?

@dubdabasoduba what are your thoughts on this?

[dubdabasoduba]

thanks @maimoonak! A keycloak dependency is not something we're worried about, we already have that as a hard dependency because of how users and locations are managed through the web UI.

In (1) how is the ACL coded in keycloak enforced on against HAPI resources?

@dubdabasoduba what are your thoughts on this?

We could do it in a 2 ways

1. Write a microservice that has ROLES/PERMISSIONS coded against specific endpoints. This means we intercept a request check the endpoints against the list provided by the microservice then check for the permissions required for the endpoint to resolve.
2. Extend the auth interceptor and add the same functionality mentioned above.

In both scenarios, we kinda lose the fine grain role restrictions we had for OpenSRP server. We can only achieve this if we agree to updating the HAPI FHIR server code and adding some of these role restrictions in there. examples of this were the ability to filter the data returned to a certain user during a search.

Questions to answer.

• Will we at any point consider pushing back any of our changes to the upstream HAPI FHIR repo? if no I would say we have this functionality in a microservice for easy maintenance.

[pld]

For that question, can we check the HAPI repo and see if that's on their roadmap? And if not ask if it's something they'd be interested in adding if we work on it?

If no and no, then I'd agree microservice is best

[f-odhiambo]

It would also be worth checking out and knowing what to return as a payload post OAuth authentication is complete and returning success to the app plus other details such as user creds/permissions etc. . This sequence diagram may be worth checking out based more details in link

[dubdabasoduba]

@maimoonak here is the doc that describes how we handled ACL on OpenSRP server using keycloak.

We use OpenSRP web to help in assigning the user groups and roles to the users.