Skip to main content

Identity Access management

OpenSRP 2 can work with many identity and access management (IAM) systems but has been most widely tested with the open source Keycloak identity and access management platform.

Setting up Keycloak​

  1. Create the user on Keycloak
  2. Create the required groups, e.g. create the PROVIDER and SUPERVISOR groups
    1. Create client groups e.g ANDROID_PRACTITIONER group for practitioners using android devices or WEB_PRACTITIONER group for practitioners using the fhir web.
  3. Create roles for all the resources your application uses, e.g. for permissions on the Patient resource create the roles GET_PATIENT, PUT_PATIENT, POST_PATIENT. The KeyCloak definition is as follows:
    1. HTTP methods define the permissions a user can have on any endpoint. We also use an additional Manage role which is a composite of the 4 HTTP method roles
    2. The Permissions checker plugin currently handles the POST, GET, PUT, DELETE HTTP methods
    3. The permissions use the following format: [HTTP_METHOD]_[RESOURCE_NAME]. Where RESOURCE_NAME is the FHIR resource name, e.g Patient.
    4. Create client roles e.g ANDROID_CLIENT for android clients or WEB_CLIENT for web clients

Note: Keycloak Roles are case sensitive. OpenSRP 2 uses uppercase letters in its role naming.

  1. Assign the roles to the corresponding group, e.g. for the above assign to PROVIDER
    1. For client roles, assign ANDROID_CLIENT to ANDROID_PRACTITIONER or WEB_CLIENT to WEB_PRACTITIONER
  2. Assign the created Group, e.g. Provider to the user
  3. Add a new user attribute with the key fhir_core_app_id and a value corresponding to the user’s assigned android client application id on the Composition resource (composition_config.json).
  4. Create a protocol mapper with Mapper Type User Attribute at the client level, area path (Keycloak v20+) Clients > Client Details > Dedicated Scopes > Add mapper. The User attribute and Token claim name field values should match the attribute key fhir_core_app_id created in the previous step.
    • For keycloak below v20, Clients > your-client-id > Mappers > Create

Keycloak auth token configuration​

When making API requests, the app uses an access token that represent authorization to access resources on the server.

When the access token expires, the app will attempt to renew it using a refresh token.

The access token lifespan is configured on Keycloak as the Access Token Lifespan.

The refresh token lifespan will be equal to the smallest value among (SSO Session Idle, Client Session Idle, SSO Session Max, and Client Session Max).

When setting up identity and access management via Keycloak, the access and refresh token values are required to ensure the access token renewal works as expected in the app.

Configuring Keycloak for fhir-web​

  1. Navigate to the Keycloak Admin UI, e.g http://keycloak:8080
  2. Create realm with name fhir or anything else
  3. In the realm previously created, create new Client Scope "fhir_core_app_id", set it as Default, and add mapper user attribute fhir_core_app_id
  4. Create client for OpenSRP v2.0 client-side application, e.g. opensrp-v2-app-client
    • In "Capability config", turn on "Client authentication".
      • When it is ON, the OIDC type is set to confidential access type. When it is OFF, it is set to public access type)
    • Set "Valid redirect URIs" to * or other as needed
    • Copy & paste the client secret from "Credentials" tab
  5. Create client for fhir-web
    • In "Capability config", turn on "Client authentication".
    • Set "Valid redirect URIs" to the domain name of your fhir-web installation + wildcard as suffix, e.g. https://fhir-web.example.org/* or other as needed
    • Set "Valid post logout redirect URIs" to the domain name of your fhir-web installation + wildcard as suffix, e.g. https://fhir-web.example.org/* or other as needed
    • Set "Web origins" to the domain name of your fhir-web installation, e.g. https://fhir-web.example.org or other as needed
    • Copy the client secret from the "Credentials" tab, paste it wherever needed
  6. Create realm roles based on OpenSRP V2 RBAC ROLES
    • TODO: Add script + payload to load all these to the Keycloak instance
  7. Create the groups "Super Admin" and "Provider"
    • Add roles in the "Role Mapping"
    • Add attribute fhir_core_app_id in the group, or in each user

Notes​

  • Create users via fhir-web. This helps by automatically creating the additional required FHIR resources of "Practitioner" and "PractitionerRole" for new users / healthcare workers.