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
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’sidentifier
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
.
This site is no longer maintained. Please visit docs.opensrp.io for current documentation.