# Setup Keycloak

UDiTH Portal now uses Keycloak as an identity provider.

Keycloak is an open-source software product that provides single sign-on together with identity and access management for modern applications and services.

This document is intended as a quick reference for setting up a basic Keycloak instance in practice. For a more detailed explanation of Keycloak features, please refer to the official documentation at <https://www.keycloak.org/guides>.

If you already have a running Keycloak instance, it can also be used.
The UDiTH Portal setup creates a new realm in the selected Keycloak instance with the basic configuration required to get started. The realm name is configurable during installation.

## Requirements

See the [Requirements](/UDiTH%20Portal/Requirements) page for the Keycloak requirements.

## Install prerequisites

### Download Keycloak

UDiTH Portal supports Keycloak version `26.6.1`.

For example, you can download it here:
<https://github.com/keycloak/keycloak/releases/download/26.6.1/keycloak-26.6.1.zip>

Extract the archive.

### Install Java JDK

Java JDK/JRE or OpenJDK/JRE is required, using LTS 21 or LTS 25.

Alternative versions such as Corretto (Amazon), Adoptium (Eclipse) or Microsoft and others also work.

#### OpenJDK installation

Whichever option you choose for installing Java, OpenJDK, Corretto, or Adoptium, ensure that the `JAVA_HOME` environment variable is set and points 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.

> **Note:** The default `keycloak.conf` that ships with the Keycloak package contains a large number of commented-out settings using different key names than those shown in this guide. This may cause confusion when comparing the file to the examples below. If you prefer a clean starting point, you can delete the contents of `keycloak.conf` and add only the settings you need.

### Database options

Keycloak supports multiple database providers.

The example below shows the setup for MSSQL:

#### MSSQL Server
```
db=mssql
db-username=username
db-password=pw
db-url=jdbc:sqlserver://hostname:port;databaseName=database;encrypt=true;trustServerCertificate=true;

transaction-xa-enabled=false
```

To use MS SQL, first create a new user and a new database schema in SQL Server. Ensure that the user has administrative access to the database and is allowed to create tables in that schema.

In SQL Server Management Studio, open the login properties for the user, go to **User Mapping**, select the Keycloak database, and check **db_owner** under database role membership.

![MSSQL DB Owner](media/Keycloak_MSSQL_DBOwner.png)

Please ensure that MSSQL is configured to listen:

`SQL Server Configuration Manager -> SQL Server Network Configuration -> <ServerName> -> TCP/IP = Enabled`

![Enable TCP/IP](media/Keycloak_MSSQL_EnableTCPIP.png)

`Properties -> IP Addresses -> IPAll -> TCP Port = 1433`

![Set TCP Port](media/Keycloak_MSSQL_SetPort.png)

### Production configuration

For production use, some additional configuration is required.

Extended documentation is available 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 this setup, the following is used:
- 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 based on the Keycloak base directory.

You therefore need to copy the certificate file there. Absolute paths to a different location are also possible.

##### Others

The official documentation also describes several other ways to provide certificate information to Keycloak.

See <https://www.keycloak.org/server/enabletls> for the alternatives that best fit your use case.

##### Set up hostname

Set the hostname at which the instance can be reached:
```
hostname=https://<server>:<port>
```
For security reasons, the general Keycloak admin UI can be hosted separately. If this is not required, you can use the same URL here:
```
hostname-admin=https://<server>:<port>
```

If you access the server via port `443`, remove the port number from the URLs, as this can otherwise cause issues.

##### Set cache mode

`.../keycloak/conf/keycloak.conf`
```
cache=local
```

##### Add ingoing firewall rule for port

Allow incoming traffic on the port on which Keycloak is running.

### Start

Open a command line with administrator permissions in `.../keycloak/bin`.
`kc.bat start`

Building the server may take some time. After that, Keycloak should be available on the specified port.

### Security
As with any web server, it is recommended to keep it updated with the latest security fixes.

On Keycloak servers, after installing or updating Java, it is recommended to increase key sizes to a minimum of `2048`, for example by modifying `JAVA_HOME\conf\security\java.security`.

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