Show only results for:












Setup Keycloak

The UniversalPlantViewer WebServices are now using Keycloak as an IdentityProvider.

Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services.

The following documentation article is supposed to be a quick reference on how to set up a basic Keycloak instance in practice. For a more detailed explanation of Keycloaks features please refer to the official documentation at https://www.keycloak.org/guides

If you have a running Keycloak instance set up already it can be used as well. The UWS Setup will create a new realm named uws in the given Keycloak instance with the basic configuration for getting started.

Requirements

  • Ensure that Keycloak can either:
    • Run on a different port than 443 (used by the web service), or
    • Use a separate IP address/server.
  • Currently, it seems not possible to use a reverse proxy like IIS to host both Keycloak and the web service on the same subdomain and port.
  • Accurate server time configuration (using NTP is recommended).
  • Microsoft Windows SQL Server 2016 or later is required.

Install prequisites

Download keycloak

UWS supports keycloak version 25.0.6

Download f.e. here: https://github.com/keycloak/keycloak/releases/download/25.0.6/keycloak-25.0.6.zip

Extract the archive

Install Java JDK

Java JDK(JRE) or OpenJDK(JRE) is required (LTS 21)

Alternative versions like Coretto (Amazon) and Adoptium (Eclipse) also work and provide like Java JDK/JRE an installer.

OpenJDK installation

Ensure that either way you install Java/OpenJDK/Coretto/Adoptium that the JAVA_HOME enviroment variable is set and pointing to the installation folder.

Keycloak configuration

Navigate to your Keycloak file directory and open .../keycloak/conf/keycloak.conf

The settings found here are used when starting Keycloak. Lines starting with a # are ignored.

Database options

Keycloak supports multiple database providers.

We are showing here the setup with MSSQL:

MSSQL Server

db=mssql
db-username=username
db-password=pw
db-url=jdbc:sqlserver://hostname:port;databaseName=databse;encrypt=true;trustServerCertificate=true;

transaction-xa-enabled=false

To use MS SQL first create a new user and a new database schema inside the sql server. Ensure that the user has admin access to the database and is allowed to create tables in the database schema.

Please ensure that MSSQL ist setup to listen SQL Server Configuration Manager - SQL Server Network configuration - Server name - TCP/IP = Enabled

Properties - IP Addresses - IPAll - TCP port = 1433

Production configuration

For production usage it is required to provide some additional configuration.

Please find extended documentation on the keycloak website. https://www.keycloak.org/server/configuration-production

Set up SSL certificates

https://www.keycloak.org/server/enabletls

File based approach

Keycloak supports different certificate formats. In our setup we used following: - a .pfx file containing the certificate and the key

In .../keycloak/conf/keycloak.conf specify the path to your PFX file and the password used when exporting the pfx file.

https-key-store-file=${kc.home.dir}/conf/certificate.pfx
https-key-store-password=password

This is a relative path using the keycloaks base directory.

So you have to copy the certificate files there. Absolute paths to a different location are possible as well.

Others

There are multiple other ways to pass certificate information to Keycloak in the offical documentation.

Check under https://www.keycloak.org/server/enabletls for the alternatives that fit your use case.

Set up hostname

set up hostname where instance is reachable:

hostname=https://<server>:<port>

The general keycloak admin UI can be hosted separately for security reasons. If not required you can use the same url here:

hostname-admin=https://<server>:<port>

If you access the server via 443 remove the portnumber from the urls as this causes issues

Set cache mode

.../keycloak/conf/keycloak.conf

cache=local
Add ingoing firewall rule for port

Allow ingoing traffic for port keycloak is running

Start

Open a command line with administrator permission at .../keycloak/bin kc.bat start

Building the server may take a while. After that keycloak should be available at the specified port.

Security

As with every web server, we recommend to keep it updated with the newest security fixes.

On the Keycloak servers, after installing or updating Java, we recommend to raise keysizes to a minimum of 2048, e.g. by modifying Java_home.security

For example: jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA,
DH keySize < 2048, EC keySize < 224, 3DES_EDE_CBC, anon, NULL