Show only results for:











UniversalPlantViewer WebServices Keycloak setup guide

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 diffrent port then 443 (Webservice) or that a seperate IP address is used. Currently its seems not possible to use a reverse proxy like IIS to have both on the same IP and Port.

Install prequisites

Download keycloak

UWS supports keycloak version 22.0.5

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

Extract the archive

Install Java JDK

Java JDK(JRE) or OpenJDK(JRE) is required (minimum version 17, maximum 20)

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 highlighting following options:

db=dev-file

Data is stored inside the .../keycloak/data/ folder. This folder can be deleted to reset the Keycloak instance or you can copy it for a backup. While easy to use this has multiple disadvantages as there is no real database in the background.

Disadvantages are for example: - Performance - Scheduling database backups - Common approaches to improve database performance and scaling not possible

Therefor while not recommended it is possible to use in production for a medium amount of users as well.

MSSQL Server (for production use)

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 //TODO add Pictures

Test run

The previous settings are sufficient to start Keycloak for testing purpose. Running it in combination with the UWS is also possible at this stage.

When using the UWS Setup for installation you might have to change the endpoints inside the Settings/sharedsettings.json when switching to production usage though.

Open command line with administrator rights in .../keycloak/bin

kc.bat start-dev

This will take some time building the keycloak instance with provided settings for the first time.

After this is finished, Keycloak should be available at http://localhost:8080

If you want to use UWS in this configuration, make sure to pass the Keycloak url without localhost but a full qualifying servername. You probably have to open the Inbound port 8080 for this to be available from the outside as well.

//TODO: when port 8080 is used f.e. by IIS specify different port

Production configuration

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

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-url=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-url=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.

Troubleshooting

Common use cases

Reset keycloak realm configuration

Delete realm uws in keycloak administrator UI

Now execute following command to recreate the realm.

Commmandline at .../AdminUtil

AdminUtil.exe apply-keycloak

Common errors