-
- Introduction
- Setup
- What's new
- Start Window
- Multi-Window System
- Camera
- Objects
- Tools
- Additional objects
- Custom attributes
- Project tree
- Search tab
- Attributes tab
- Files tab
- 2D to 3D projection
- Animation
- AppControls
- Comment
- Drawing
- Markup
- Package
- P&ID Sketch
- Photo
- Point of Interest
- Report
- Screenshot
- Sketch
- Spraying
- View
- Settings
- Advanced options
- IntelliPID Module
- Linking and API
- Appendix - Custom settings files
- Appendix - Command line parameters
- Appendix - Performance optimisation
- Appendix - How to use 3D PDF files
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:
File-based (not recommended for production usage by Keycloak)
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