/
Developer Documentation: Single Sign On

Developer Documentation: Single Sign On

1. Introduction

1.1 Feature Overview

Configure users and permissions via a Single Sign on provider

1.2 Audience

Developers that need an understanding of how the SSO is implemented in OpenELIS-Global

2. Technical Specifications

2.1 SAML Specification

2.1.1 Expected Behaviour

Configure OpenELIS-Global to use SAML via a supported SAML provider (ex. keycloak). A button for SSO appears on the login screen that takes you to the SSO provider’s login screen, and on login, the permissions from the SSO provider are used instead of the OpenELIS-Global configured permissions.

2.1.2 Dependencies

2.1.2.1 Libraries

  • Spring Security

  • OpenSAML

2.1.2.2 Services

  • Keycloak

2.1.3 API Specifications

2.1.3.1 SAML Role Information

SAML role information is shared from the SSO provider and corresponds with the roles in OpenELIS-Global. The roles are either Global roles, or Laboratory roles and will come from the SSO as an assertion token of the form oeg-<globalrole> or oeg-<labrole>-<labunit>. Examples would be: oeg-Global Administrator, oeg-Results-Molecular Biology, oeg-Results-AllLabUnits

2.1.3.2 Endpoints

2.1.3.2.1 System Roles

  • Endpoint: /api/OpenELIS-Global/rest/systemroles

  • Method: GET

  • Description: A list of all active roles and a short description

  • Response Format:

    • a JSON list of objects with a label and a value. Label corresponds to system_role.description, and value corresponds to system_role.name in the database.

    • ex. [{"label":"Change tests, panels etc.","value":"Global Administrator"},{"label":"A person who can validate results","value":"Validation"}, ...]

2.1.3.2.1 System Roles With Test Sections

  • Endpoint: /api/OpenELIS-Global/rest/systemroles-testsections

  • Method: GET

  • Description: A list of all active roles with test section information where relevant and a short description

  • Response Format:

    • a JSON list of objects with a label and a value. Label corresponds to system_role.description, and value corresponds to oeg-system_role.name-test_section.name in the database for lab roles, and oeg-system_role.name for global roles

    • ex. [{"label":"Change tests, panels etc.","value":"oeg-Global Administrator"},{"label":"Add/remove users and assign roles.","value":"oeg-User Account Administrator"},{"label":"Generate reports.","value":"oeg-Reports-AllLabUnits"},{"label":"Sample entry and patient management.","value":"oeg-Reception-Biochemistry"}, ...]

2.1.4 Configuration Options

Property

Description

Default

Property

Description

Default

org.itech.login.saml

Boolean value of whether SAML should be enabled or not

false

org.itech.login.saml.registrationId

The ID of the SSO provider

keycloak

org.itech.login.saml.entityId

The name of the client service that is connecting to SSO (OpenELIS-Global)

OpenELIS-Global_saml

 

server.ssl.key-store

the keystore to use for communication with the SSO service

 

server.ssl.key-store-password

The password to the keystore

 

org.itech.login.saml.metadatalocation

The metadata location for the SAML endpint in the SSO provider.

This will override several configuration options with values supplied from the SSO provider and is the recommended way of setting up the connection.

ex. http://localhost:8089/realms/OpenELIS/protocol/saml/descriptor

 

org.itech.login.saml.idpEntityId

SSO entity ID

(overridden by metadatalocation)

ex. http://localhost:8089/realms/OpenELIS

 

org.itech.login.saml.webSSOEndpoint

SSO address for login/logout (overridden by metadatalocation)

ex. http://localhost:8089/realms/OpenELIS/protocol/saml

 

org.itech.login.saml.idpVerificationCertificateLocation

SSO address for fetching the SSO certificate (overridden by metadatalocation)

 

2.2 OpenID Connect (OAuth) Specification

TODO

3. Code Implementation

3.1 Directory Structure

OpenELIS standard directory structure

3.2 Key Files

3.2.1 Java Classes

  • org.openelisglobal.security.SecurityConfig

  • org.openelisglobal.security.login.CustomSSOAuthenticationSuccessHandler

  • org.openelisglobal.systemuser.service.UserServiceImpl.java

3.2.2 Java Resource Files

  • None

3.2.3 System Files (In docker container)

  • /run/secrets/common.properties

  • /run/secrets/extra.properties