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

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.

Click on clients on the sidebar menu
Click on the client we are adding this to
Click on the mappers tab
Click on the create button
On the form change the Mapper type Property to User Property
Choose the Boolean option for Claim Json Type
Then have Add to ID token as OFF
Ensure that Add to User Info is ON
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.

Documentation

Setting up Keycloak