Version: 8.0.x

Adding Users

In order to configure the OpenHIM you have to be a registered user account with relevant permissions. A default super/admin user is provided when you first run the OpenHIM.

The default admin user is as follows:

password: openhim-password

Note: Change these as soon as you have installed the openhim to avoid abuse. The OpenHIM console should prompt you to do this on first login.

Using the default admin user, you may create other users. These too may belong to the admin group or custom groups. Non-admin users cannot create clients and channels, however, they may view transactions for certain channels that they are given access to.

Note: Users that belong to the admin group are Super Users.

User accounts are created in order to give users of the system certain features depending on the groups to which they belong. Users can access these features through the OpenHIM console.

How are users different from clients#

Clients are different from users, they represent systems that can route transactions through the OpenHIM. Users are people accessing and configuring the OpenHIM and clients are systems that are allowed to send requests to the OpenHIM.

User Groups#

Groups are created automatically by just adding a new group name in the user form. You do not need to add a group explicitly. When you go on to create the channel, you just need to make sure the group name matches the one specified when you created the user.

There are 2 kinds of groups

  1. The admin group: this is a special group that grants users all permissions.
  2. The rest are defined by the system administrator and in the channels, an admin can set whether the group has any of the permissions below.


Users belonging to a certain group can be assigned certain permissions on a channel. This is done by adding the group to which they belong to that particular permission.

The permissions themselves are pretty self explanatory and are listed below with some brief explanations.

  1. Can view channel transactions
  2. Can view channel transaction bodies - bodies may contain private patient data
  3. Can re-run transactions - enabling this permission needs to be done with care because it may cause downstream duplicates and data corruption if they users doesn't know what they are doing

Also on the users page, there is a matrix that shows these permissions. This can be viewed by clicking the button above the list of users.

Walk through and examples#

To add a user as an admin user, navigate to the admin section and click the button to add the user.

Required fields, are as follows:

  1. Email - This needs to be a valid and unique email address
  2. First Name
  3. Last Name
  4. Groups
  5. Password and Confirm Password

Optional Fields are as follows:

  1. MSISDN - the users cellphone number in the MSISDN format (eg. 27825555555) should you want to receive sms alerts
  2. Receive daily reports, via email
  3. Receive weekly reports, via email
  4. Filter & List settings: here you may pre-define how you want to view your transactions


The two kinds of reports mentioned above send transaction metrics aggregated over a period. In these reports, you can see the number of transactions that went through as well as their statuses.

The statuses are as follows:

  1. Failed
  2. Processing
  3. Completed
  4. Completed with errors
  5. Successful

Filter and list settings#

  1. Filter settings: Here you set how you want to view transactions on the Transactions page by default. You can default it to show transactions by status, by channel, as well as limit the number of transactions per page.

  2. List settings: Upon clicking on a transaction in the transactions page, you can choose whether to view the transaction on the same page (default), or to open it in a new window altogether.

If you find a field that is not described here, please let us know by filing an issue on github with the 'documentation' label.

Keycloak Single Sign-On (SSO)#

Openhim console and core are supporting SSO authentication (Keycloak identity manager). Enabling SSO in the openhim console and core will allow:

  1. Authentication: A user can be logged in using keycloak credentials.
  2. Profile setup: The user authenticated using Keycloak will have his profile filled automatically with info provided by Keycloak. The User group of that user is also provided and managed through Keycloak. The optional fields can still be editable.
  3. Single sign-on and single sign-out.