1. Introduction

1.1 Feature Overview

Configure users and permissions via a Single Sign on provider

1.2 Audience

Administrators in charge of setting up and configuring OpenELIS-Global instances that want to configure Single Sign On via Keycloak

2. Getting Started

2.1 Prerequisites

Must be running a version of OpenELIS-Global > 3.0

3. Using the Feature

3.1 Step-by-Step Instructions

The instructions provided here are for reference. There are many ways to go about setting this connection up (ie if you already have an existing Keycloak instance, you can use that instead of making a new service). These instructions do not go into setting it up via ssl, but it is recommended to do so either via an https proxy or configuring Keycloak for https directly.

3.1.1 Task 1: Creating a Keycloak instance

Open your projects docker-compose.yml in a text editor
Add a service keycloak like below

keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:25.0.1
    ports:
      - <server port>:8080
    command: start-dev
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: <default admin password>
      KC_HOSTNAME: <address of the keycloak server frontend or https proxy>
      KC_HOSTNAME_STRICT: false
      KC_HOSTNAME_STRICT_HTTPS: false
      KC_HEALTH_ENABLED: true
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://database:5432/clinlims
      KC_DB_USERNAME: clinlims
      KC_DB_PASSWORD: <clinlims password>
    networks:
      - <openELIS-Global network>

Run a docker compose up -d
Ensure the keycloak container is running successfully and that you can log in

3.1.2 Task 2: Configure Keycloak

Login to Keycloak from the frontend location
Create a Realm and fill out the Realm information before clicking save or create
1. Realm Name: OpenELIS
2. Enabled: On
Create Client and fill out the client information before clicking save or create
1. Type: SAML
2. Name: OpenELIS-Global_saml
3. Client ID: OpenELIS-Global_saml
4. Valid Redirect URIs: <OpenELIS-Global address>
Edit Keys for the client
1. client signature required: off
Create Realm Roles and fill out the roles you want to use
1. ex. Role Name: oeg-Global Administrator
2. the full list of roles can be found at the OE endpoint <server-address>/api/OpenELIS-Global/rest/systemroles-testsections
Optionally, Create Group
1. Name: <Group Name>
Optionally, go into group and Role Mapping > Assign Role
1. Filter by realm roles
2. Add the roles
Create User and fill out the user information before clicking save or create
1. User Name: admin
Edit the Credentials of the user, temporary or not
Add Realm Roles directly to the user, or add a Group with Realm Roles to the User

3.1.3 Task 3: Linking OpenELIS-Global with the Keycloak server

Edit a configuration file like /var/lib/openelis-global/secrets/extra.properties
Add the following configuration options to enable SAML login

org.itech.login.saml=true
org.itech.login.saml.metadatalocation=<keycloak address>/realms/<Realm>/protocol/saml/descriptor

Bring the OpenELIS-Global container down and up for the change to take
1. sudo docker compose down
2. sudo docker compose up -d
Confirm that the SSO button appears in the frontend of OpenELIS-Global

4. Troubleshooting

4.1 Common Issues

Requests to the SSO are rejected:
- Ensure trust between the platforms is configured well if you’re using SSL for the connection (which is recommended)
- Ensure the KC_HOSTNAME value points to the frontend of the keycloak service outside of the docker network, whether it be a proxy or the keycloak address directly
- Ensure the realm in keycloak matches the realm in the metadata location that is passed to OpenELIS-Global
User doesn’t have their configured permissions
- Ensure the names of the permissions are correct maintaining capitalization, spacing, and prefix oeg-

OpenELIS Global

Administrator Documentation: Single Sign On