Olvid Keycloak Configuration Guide - Installation of Keycloak

Installation of Keycloak

The official Keycloak Server Administration Guide can be found here:

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

Please refer to it whenever you believe your configuration might differ from the standard configuration we describe here.

If you intend to run Keycloak natively on your server, please read on.
If you would rather run Keycloak in a container, please read the Running Keycloak in a Container page.

1. Download the Keycloak + Olvid bundle

The Olvid Plugin is bundled with a complete Keycloak (Quarkus version) distribution.

From your linux server, download the latest bundle from:

https://static.olvid.io/keycloak/keycloak_olvid_23.0.6_3.1.0.tar.gz
Check that the SHA-256 hash of the bundle is:
15b5ed5567cdc97899e650893e4ebaeb30ebd3548bc79b161d70cb05c88ab798
Uncompress the archive to obtain a keycloak_olvid_23.0.6_3.1.0 folder.

All the following steps are executed from within this folder.

> wget https://static.olvid.io/keycloak/keycloak_olvid_23.0.6_3.1.0.tar.gz
> sha256sum keycloak_olvid_23.0.6_3.1.0.tar.gz
> tar xvf keycloak_olvid_23.0.6_3.1.0.tar.gz
> cd keycloak_olvid_23.0.6_3.1.0/

2. Modify the configuration file

The Keycloak configuration file can be found in:
keycloak_olvid_23.0.6_3.1.0/conf/keycloak.conf

Open it in your favorite text editor to configure the database connection (the parts in red below). You do not need to configure the other options from this file, they are already properly set in the bundled startup script (through command line options).

# Basic settings for running in production. Change accordingly before deploying the server.

# Database

# The database vendor.
db=postgres

# The username of the database user.
db-username=keycloak

# The password of the database user.
db-password=password

# The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor.
db-url=jdbc:postgresql://postgres.local.ip/keycloak

[...]

For the db field, the value should be the vendor of the database system (see the official documentation):

postgres for PostgreSQL
mysql for MySQL
mssql for Microsoft SQL Server

3. Start Keycloak

Now that Keycloak is configured, you may:

Start the server. The first launch will be used to create the first Keycloak Admin’s Credentials.
The keycloak_olvid_23.0.6_3.1.0/1.olvid_scripts/ folder contains a special script for this.
Provide the admin username and password of your choice:

> keycloak_olvid_23.0.6_3.1.0/1.olvid_scripts/first-launch-keycloak.sh -u <username> -p <password>
Check the standard output logs for errors.

If everything goes well, you may:
Connect to the internal IP/localhost on port 8080 and should see the Welcome to Keycloak front page.

The connection URL should look something like this http://10.1.2.3:8080/auth/. Once we set up the reverse proxy we can add a redirection, but for now the URL must end with /auth/.

4. Check connectivity with the Olvid distribution server

You can check if your Keycloak server can reach the API point it needs to query on the Olvid server with the command:

> wget -q --post-data="" https://server.olvid.io/keycloakQuery -O -

If you get the output {"error":3}, everything is fine 😀

4.1 Configuring an outgoing proxy

If your server needs to go through an HTTP proxy for outgoing connections, this is possible! The official documentation explains different solutions for this, but the one we found to be the simplest is the use of a proxy mapping in the Keycloak startup command line.

⚠️ Warning ⚠️ there are various typos in the Keycloak documentation, regular expressions should use .* and not simply *, and you should not add double quotes " around the expression.

To add a proxy mapping, open the file keycloak_olvid_23.0.6_3.1.0/1.olvid_scripts/run-keycloak.sh and modify the command line by adding something like --spi-connections-http-client-default-proxy-mappings='server\\\.olvid\\\.io;http://proxy.local.ip:3128'. Pay close attention to the ' in the command line, be sure not to use double quotes as they could cause some shell expansion to happen! And three \ are required for an actual .

#!/bin/sh
`dirname $0`/../bin/kc.sh --config-file=`dirname $0`/../conf/keycloak.conf start --proxy edge --hostname-strict=false \
     --http-relative-path=/auth --log=console,file --spi-connections-http-client-default-proxy-mappings='server\\\.olvid\\\.io;http://proxy.local.ip:3128'

This adds the proxy only for connections to server.olvid.io. If you want to use the proxy for any outgoing keycloak connection, you can use a wildcard with something like --spi-connections-http-client-default-proxy-mappings='.*;http://proxy.local.ip:3128'.

5. Create a startup service to autostart Keycloak

In order for Keycloak to automatically start with your server, you may create a startup script and add it to the default services. If your server uses systemd (this is the case for Ubuntu or CentOS), you can create a /etc/systemd/system/keycloak.service file containing the following lines (replace the part in red with the actual path to the keycloak-olvid folder):

[Unit]
Description=Keycloak
After=syslog.target network.target
Before=httpd.service

[Service]
User=root
Group=root
LimitNOFILE=102642
PIDFile=/var/run/keycloak/keycloak.pid
ExecStart=/opt/keycloak_olvid_23.0.6_3.1.0/1.olvid_scripts/run-keycloak.sh
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=keycloak

[Install]
WantedBy=multi-user.target

You may then start the service and add it to the default startup service with:

> systemctl start keycloak
> systemctl enable keycloak

Contrary to the manual startup where the logs go to the standard output, when starting this way, the Keycloak logs are both sent to syslog and written in the file data/log/keycloak.log inside the keycloak-olvid folder.

6. Configure a reverse proxy

The Keycloak server is configured to run behind a reverse proxy taking care of SSL/TLS and redirecting connections on the public DNS of Keycloak towards the keycloak server, on port 8080. Contrary to Keycloak legacy that had to run in HTTPS with a self-signed certificate, the latest Keycloak can run in plain HTTP.

If you only need Olvid users to authenticate through this reverse proxy (and can access the Management Console through a local address), you will need to forward the paths:

/auth/resources/
/auth/js/
/auth/realms/olvid/ (the final /olvid/ may change if you decide to use another name for your Olvid users realm)

If you wish to access the Olvid Management Console from an external IP, you should also forward the paths:

/auth/realms/master/olvid-rest/authenticationDiscovery
/olvid
/auth/olvid/
/auth/realms/olvid_admin/ (the final /olvid_admin/ may change if you decide to use another name for your Olvid admin realm)

Please have a look at the example nginx configuration file below to see how this can be done.

Also, the reverse proxy must send some required headers for Keycloak to properly work:

X-Forwarded-For
X-Forwarded-Proto
X-Forwarded-Host

And some buffer sizes might need to be adjusted (the default nginx buffers are too small). Please see the sample nginx configuration below.

To be able to access Keycloak and the Olvid management console through simple URLs, we recommend adding some simple redirects:

/ redirects to /auth
/olvid redirects to /auth/olvid/#

If you do not already have a reverse proxy in place you may run nginx directly on the Keycloak server. This will also require you to have the SSL certificate for your server. Here are the steps to install certbot (to get a Let’s Encrypt certificate) and nginx on an Ubuntu 20.04 server.

6.1 Install the packages

> apt install certbot nginx-full python3-certbot-nginx

6.2 Request the certificate

Here, we assume your public DNS is keycloak.com, replace it with your actual DNS for the server.

> certbot --nginx -d keycloak.com

When prompted:

enter an email address (that will be communicated to Let’s Encrypt)
accept the terms
decide whether you want to share your email with the EFF
choose to redirect all HTTP traffic to HTTPS (this will modify the default nginx site appropriately)

Normally, the certbot service is already installed and should automatically renew your certificate (which is only valid for 3 months). You can check this with:

> systemctl status certbot.timer

⚠️⚠️ nginx does not auto-reload new certificates ⚠️⚠️

By default, nginx does not automatically reload its configuration when the certificate is renewed by certbot. This might also be the case for other HTTP servers. To make sure your server always uses the most up-to-date certificate, it is recommended to force it to reload its configuration on a regular basis. For nginx you may run the command

> systemctl reload nginx

You may also create a cron task to run this on a daily basis.

6.3 Configure nginx

Now, we need to create the nginx configuration file that will actually redirect HTTPS requests towards Keycloak. Create /etc/nginx/sites-available/keycloak.conf containing:

server {
  server_name keycloak.com;

  # To only redirect a specific set of paths, you may replace the line below with something of the form
  # location ~ ^(/auth/resources/|/auth/js/|/auth/realms/olvid/) {
  location /auth {
	proxy_set_header X-Forwarded-For $remote_addr;
	proxy_set_header X-Forwarded-Proto $scheme;
	proxy_set_header X-Forwarded-Host $host;

	proxy_buffer_size       128k;
	proxy_buffers           4 256k;
	proxy_busy_buffers_size 256k;

	proxy_pass http://127.0.0.1:8080;
  }

  location /olvid {
	return 302 /auth/olvid/#;
  }

  location = / {
	return 302 /auth;
  }

  client_max_body_size 10M;

  listen [::]:443 ssl ipv6only=on;
  listen 443 ssl;

  ssl_certificate /etc/letsencrypt/live/keycloak.public.dns/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/keycloak.public.dns/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
  
server {
  server_name keycloak.public.dns;
  listen [::]:80;
  listen 80;

  return 301 https://$host$request_uri;
}

Now, to activate this configuration and deactivate the default configuration:

> cd /etc/nginx/sites-enabled
> rm default
> ln -s ../sites-available/keycloak.conf .
> systemctl restart nginx

That’s it, you should now be able to connect to your keycloak server through its public DNS.

You can now continue with the Configuration of Keycloak