Olvid Keycloak Configuration Guide

Upgrading

Important: each new version of the Olvid Plugin imposes a minimal version for the iOS, Android and Desktop clients. Before updating, please make sure all your users will have the ability to update to the latest version of Olvid.

This short guide describes the main steps to follow when upgrading Keycloak and the Olvid Plugin. The official Keycloak upgrading guide is available here:

https://www.keycloak.org/docs/latest/upgrading/

Here are the recommended steps when upgrading Keycloak and Olvid. If upgrading from Keycloak legacy to the newest Keycloak, please also read the dedicated section below.

Version specific steps

If upgrading the Olvid Plugin from a version lower than 3.1.0, first check the themes configured for your different realms. This can be accessed from the Keycloak Console, in the Realm settings section, in the Themes tab. For all realms, make sure the base theme is not selected for any Login theme. If unsure, use the olvid theme for Login or leave them on Select a theme. Also, if your server requires a proxy for outgoing connections, make sure to update the syntax in the run-keycloak.sh script by removing double quotes (see the updated documentation)
If upgrading the Olvid Plugin from a version lower than 4.0.0, first check that Java 21 is installed on the server as the latest version of Keycloak require it. Otherwise, update your installed version of Java before proceeding with the update. Older versions of Keycloak should be able to run on Java 21 without any problem.
- the old --proxy=edge option is no longer supported and proxy behaviour depends on the headers sent by the reverse-proxy. Be sure to include all the X-Forwarded... headers specified in the configuration documentation.

Standard upgrade steps

Backup your keycloak database: whenever you launch a newer version of Keycloak or of the Olvid Plugin, it will run a migration process on the database. This migration cannot be undone easily, so if for any reason your upgrade fails, and you want to restart your current Keycloak version, you will need to restore a pre-migration snapshot of the database.
Prepare and independent install of Keycloak: rather than overwriting any current Keycloak files, we recommend using a completely different install, either on the same server in a different folder, or on a new server. If using a new server, make sure it has the same internet access as the current one and remember that the reverse proxy configuration will need to be updated. Here, we suppose you use a different folder on the same server:
1. Create a new install folder next to the current one
2. Unpack the latest Olvid Plugin bundle in this new folder (as in the standard installation guide)
3. Copy your current configuration file to the new installation folder. This file is located in conf/keycloak.conf for Keycloak, or standalone/configuration/standalone-ha.xml for Keycloak legacy. This will copy the database url and credentials required to connect to your current database.
Stop the current Keycloak instance and make sure there is no Keycloak process running on the server:
```
> systemctl stop keycloak
> ps -ef | grep keycloak
```
Keep in mind that while the Keycloak server is stopped, your employees can still use Olvid normally. They only lose the capacity to add new contacts using the directory. So it is usually not a problem to stop the server for a few minutes.
Manually start the new Keycloak instance: contrary to the first launch described in the installation guide, no need to set the first admin username and password, they are already set in the database. You can simply run 1.olvid_scripts/run-keycloak.sh inside the new folder. Have a look at the standard output and check for errors

This will run the database migration step, so from this point, any attempt to return to your old Keycloak instance will require to restore your database snapshot.
Test connectivity with the new instance: using a phone with Olvid installed and bound to Keycloak, open the user directory and make sure the search if functional. If everything works, you can kill the manually started Keycloak instance (a Ctrl+C should work).
Update the keycloak.service systemd service: if you created the keycloak.service as in the installation guide you simply need to update the ExecStart line to reference the new folder.
Start the updated Keycloak instance by reloading all unit files and restarting the keycloak service
```
> systemctl daemon-reload
> systemctl start keycloak
```

That’s it, the update is done! Once you are sure everything is working as expected, you can clean up your old install by deleting the old installation folder.

Upgrading from Keycloak legacy to the newest Keycloak (Quarkus engine)

When upgrading from Keycloak legacy to the Quarkus version of Keycloak, there are some additional steps to take. Keycloak provides an official migration guide here:

https://www.keycloak.org/migration/migrating-to-quarkus

The changes explained in this guide lead us to change the way the Olvid Plugin fopr Keycloak is distributed: it is now bundled with a complete, slightly patched, Keycloak distribution. One consequence is a much simpler installation process, but also:

the configuration file has completely changed: say goodbye to the atrocious standalone-ha.xml file, it has been replaced by a much simpler keycloak.conf file where you only need to modify a few lines to configure your database url and credentials.
Keycloak runs in a new proxy=edge mode, specially designed to be behind a reverse proxy. This implies several changes in the reverse proxy configuration (please see the installation guide):
- Keycloak no longer runs in HTTPS with a self-signed certificate, but in plain HTTP: the default port has changed from 8443 to 8080
- some new paths need to be forwarded to Keycloak
- the reverse proxy must send some additional headers for Keycloak to properly work:
  - X-Forwarded-For
  - X-Forwarded-Proto
  - X-Forwarded-Host
Keycloak removed the default /auth prefix from Keycloak urls: we added the /auth back to maintain compatibility with existing Olvid users, but some default Keycloak redirects are lost in the process. We recommend adding some redirects as explained in installation guide.
if using x509 certificates for authentication, please let us know if you need help. The process to authenticate with user certificates on Keycloak quarkus has not been tested/documented by us yet!