Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Current »

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.

  1. Click on the drop-down menu then click on the Create Realm button

  1. 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

  1. 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

  1. 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;

  1. Client ID

  2. Name

  3. Root URL

  4. Home URL

Client details

The client signature under keys is set to off

Client Signature

  1. 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

  1. 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

  1. In this illustration, the sign on is done using an admin user.

Admin Sign on

  1. Close the SSO true page upon sign on.

Close sign on confirmation page

  1. Click on the admin module upon sign on. The admin sections will be displayed.

Click admin

Admin sections

  1. 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

  1. 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

  1. Sign out of Key Cloak under sessions to end the admin session.

Sign out a session

  1. Login using a user with test functionality roles

User sign on

Note; Key cloak configuration allows a user to change their password

  1. 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

  • No labels