Setting up Keycloak

After installing Keycloak from  https://www.keycloak.org/downloads and running it, the following are the steps required for a manual set up of the server requirements for authentication.

NB: When running Keycloak, it may be preferable to create an offset for all ports that Keycloak uses. This is to avoid conflicts with other running apps e.g. those running on port 8080. For instance to offset by 100 and have Keycloak running on port 8180 use:

./standalone.sh -Djboss.socket.binding.port-offset=100

Create Realm

  • Select Add realm at the top left-hand corner

  • Enter a name for the realm

 

Keycloak Realm Home Screen Menu

Add Client

  • Under Clients on the left-hand-side menu, select Create

  • Enter a name for the client

  • After client is created, more details are displayed. Follow steps below to enable credentials configuration

    • Modify Access Type dropdown value from the default Public to Confidential

    • Modify Valid Redirect URIs value from blank to *

    • Save the changes

    • Select Credentials tab to view (or regenerate the secret)
      Note the Secret value for use in configuring oauth client

 

Add Client Roles

  • Under Roles on the left-hand-side menu in Configure section, select Add role

  • Enter a name, a description of the role (recommended for documentation purposes)

  • Create some roles

 

Add Group

  • Under Groups on the left-hand-side menu in Manage section, select New

  • Enter a name for the group

  • Create some groups

 

Add User

  • Under Users on the left-hand-side menu in Manage section, select Add User

  • Enter a username (and optionally an email address, first and last names), ensure the user is enabled

  • Save the user

  • Under Credentials, set a password for the account. The password can be set to be changed on first-time login by leaving the Temporary flag set to ON. Set the Temporary flag to OFF so that the password is not an OTP

  • Take note of the user’s ID value

  • Under Role Mappings tab, assign the user some roles. Most users will need the OPENMRS role.

  • Under Groups tab, assign the user to one or more existing groups or add roles that the user should have. Adding a user to a group means he inherits all roles that the group is assigned. In the groups tab click view all Groups to view all groups.

  • Under available Groups, click the group the user should be added and the click Join button

 

Running on OpenSRP

In your WEB-INF folder, add the key cloak config file keycloak.json with the values corresponding to your set up

{ "realm": "xyz-server", "auth-server-url": "https://xyz-server/auth/", "ssl-required": "external", "resource": "opensrp-server", "credentials": { "secret": "the client secret" }, "confidential-port": 0 }

 

NOTE
Ensure that the OAuth server host configured in keycloak.json, opensrp.properties and in your Postman under *Access Token URL* are the same.

Example
For local machine setup, if the keycloak-configured host is 127.0.0.1, keycloak.json, opensrp.properties and the Postman entry must have 127.0.0.1 and not localhost.

Testing on Postman

Get the configuration from OpenID configuration end-point

http://localhost:8080/auth/realms/xyz-realm-name/.well-known/openid-configuration

  • While running on local, make sure the realm is the same one mentioned in the keycloak.json file.

  • Also change your secret key accordingly!

To get access token from Postman (Local testing)

 

Manual Migration

  1. Create Location Tags

  • POST: https://xyz-server.smartregister.org/opensrp/rest/location-tag

  • Sample request body

{   "name": "Country",   "active": true,   "description": "Country Location Tag" }

 

2. Create Locations

  • To fetch location tags
    GET: https://xyz-server.smartregister.org/opensrp/rest/location-tag

  • To create the locations

    POST: https://xyz-server.smartregister.org/opensrp/rest/location?is_jurisdiction=true

  • Sample request body

{ "type": "Feature", "id": "ac7ba751-35e8-4b46-9e53-3cbaad193697", "properties": { "status": "Active", "parentId": "07b09ec1-0589-4a98-9480-4c403ac24d59", "name": "TwoTwoTwo_03", "geographicLevel": 0, "version": 0 }, "locationTags": [ { "id": 2, "active": true, "name": "Facility", "description": "Health Facility" } ] }

 

3. Create Organizations (Teams)

  • POST: https://xyz-server.smartregister.org/opensrp/rest/organization

  • Sample request body

 

4. Assign Organizations to Locations and Plans

  • POST: https://xyz-server.smartregister.org/opensrp/rest/organization/assignLocationsAndPlans

  • Sample request body

 

5. Create Practitioners

A practitioner in OpenSRP maps to a Keycloak user in a realm.

  • POST: https://xyz-server.smartregister.org/opensrp/rest/practitioner

  • Sample request body

    NOTE: Take note userId is keycloak user ID

 

6. Create Practitioner Roles

A practitioner belongs to an organization/team. It is through the organisation that the practitioner is tied to a location/jurisdiction.

  • POST: https://xyz-server.smartregister.org/opensrp/rest/practitionerRole

  • Sample request body
    NOTE: practitioner is the practioner’s identifier from Create Practitioners section

7. Add Account Status Mapper

To authorize the application during manual or background sync, the OpenSRP Android client needs to confirm that the current user has the authority to do so. It does this by hitting the /protocol/openid-connect/userinfo endpoint on Keycloak to check whether the current user is still active or had been disabled by the Keycloak admin. However, this information is not there by default. If you make a request like the one below you will find that the property userinfo.enabled is missing.

 

 

To fix this issue of userinfo.enabled being empty, a protocol mapper has to be created which returns the enabled User property by going through the following steps.

  1. Click on clients on the sidebar menu

  2. Click on the client we are adding this to

  3. Click on the mappers tab

  4. Click on the create button

  5. On the form change the Mapper type Property to User Property

  6. Choose the Boolean option for Claim Json Type

  7. Then have Add to ID token as OFF

  8. Ensure that Add to User Info is ON

  9. Ensure that Add to ID access token is ON

The form should look like below. Finally click save.

If we now make the request we should have the enabled property as part of the user information as so

 

8. Session and token timeouts

The OpenSRP client app kicks a user out when the refresh token expires. The consequence being that you have to login while online to access the app or for sync to happen in the background. Therefore, it is recommended to set your OpenSRP applications' refresh and access token to 14 days and 1 day respectively.

You can manipulate the access token and refresh token values by either using the Tokens tab of the Realm settings or by going to the Advanced Settings section of the Client’s setting page.

To change the access token value, go to Clients > Choose the client > Settings Tab > Expand Advanced Settings> Change Access Token Lifespan to 1. Ensure that the value is in Days.

Navigation to Clients settings

 

 

Refresh token timeout is determined as the lowest of SSO Session Max (Realm setting) , SSO Session Idle (Realm setting), Client Session Max (Client setting) and Client Session Idle (Client setting). In our case we have to ensure that at least on of the values is 14 days. The rest should be the same or higher.

 

The refresh token is returned in the fieldrefresh_expires_in that is returned by the fetch token endpoint {keyloak_url}/auth/realms/opensrp/protocol/openid-connect/token.