Version:
Date: 2024-09-26
Author: Caleb Steele-Lane
1. Introduction
1.1 Feature Overview
Login via a central Single Sign On location
1.2 Audience
Users for OpenELIS who need to log-on via SSO
2. Getting Started
2.1 Prerequisites
Must be running a version of OpenELIS-Global > 3.0
Must have an username and password setup through keycloak via an administrator
3. Using the Feature
How to add a single sign-on provider
The key cloak image is added to the docker container file build.dockey-compose.yml In the illustration below, the quey image is used on port 8089 in a development environment. Therefore http will be used on the local host. The docker compose up command is used to startup the container.
Key cloak image
The environment variables are set as follows:
Environment variables
Upon successful setting up of the single sign on provider a login page is displayed. Upon login using the credentials in the environment variables the session page is displayed by default.
Session page
How to set up a realm role for an individual user.
Click on the drop-down menu then click on the Create Realm button
Add a realm name and toggle on the button to enable the Realm. In this illustration an OpenELIS Realm is created and enabled.
Realm name and enabling the realm
Once the realm is created, select the Realm and click under the Realm roles. The illustration below displays different roles that we have created for OpenELIS.
Realm roles
Note: The following end-point is used for different OpenELIS roles that map roles to roles combinations. Below is an example of a role that is associated with a test function.
Role mapping endpoint
This end point is responsible for mapping roles that can then be created under the Realm Role
Realm roles
Once the role realm is created, click on Clients.
Create a client
Note: below is an illustration of a created client under the settings tab. These details entails;
Client ID
Name
Root URL
Home URL
Client details
The client signature under keys is set to off
Client Signature
Click on the save button upon filling the settings tab.
Save settings
Note; At this juncture, OpenELIS Global can communicate with Key Cloak theoretically. In reality OpenELIS does not know where to communicate with Key Cloak if this is not yet setup. The total system configuration file is where OpenELIS Key Cloak is setup
Total system configurations
The saml authentication is also setup to true
Saml set to true
The metadata location is specified. This enables OpenELIS to pull from Key Cloak its information about the saml exchange as opposed to setting up all the individual properties. At this juncture, the OpenELIS Global image should be restarted.
Note; in the production environment, the http will be replaced with https for security and the keycloak would be replaced with the front end name of the Key Cloak service using an official certificate.
Metadata locator
Upon restart of the OpenELIS docker container, the login page will display the single sign on. To sign on, Click on the Single Sign On button.
Click on SSO button
In this illustration, the sign on is done using an admin user.
Admin Sign on
Close the SSO true page upon sign on.
Close sign on confirmation page
Click on the admin module upon sign on. The admin sections will be displayed.
Click admin
Admin sections
Click on a test section. Access will be denied since the single sign on was not configured to allow access to test functionalities for an admin user
Add order
Access denied
Logout from OpenELIS. This will only end the OpenELIS session. Similarly, you will either need to logout of Key Cloak or the session for it to time out. The ideal is to prompt the user to also sign out of Key cloak as well when they click on logout under OpenELIS.
End session
Sign out of Key Cloak under sessions to end the admin session.
Sign out a session
Login using a user with test functionality roles
User sign on
Note; Key cloak configuration allows a user to change their password
Click on a test functionality under the menu items upon successful login. In this illustration, order is clicked.
Click on tests functionality
Note; tests for samples related to assigned roles under Keycloak.
Role assignment
realm role assigned to test user
Serology and biochemistry tests
How to set up a realm role via group
The illustration below shows the addition of Realm roles via groups. The administrator only has the default role that was created when creating the OpenELIS Realm.
Default admin role
4. Troubleshooting
4.1 Common Issues
You are not redirected to the OpenELIS-Global home page on a successful login
contact an administrator to fix the communication between SSo provider and OpenELIS-GLobal
Password rejected
Ensure you are using a valid username and password combination
Contact an administrator to reset your password
0 Comments