Olvid Keycloak Configuration Guide

Final setup steps

1. 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 Connection successful, everything is fine 😀

2. 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-19.0.3 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-19.0.3/bin/standalone.sh -c standalone-ha.xml -b=0.0.0.0
StandardOutput=null

[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 can be found at standalone/log/server.log inside the keycloak-19.0.3 folder.

3. Configure a reverse proxy

The recommended setup is to have an independent reverse proxy that redirects connections to the public DNS of Keycloak towards the keycloak server, on port 8443 (HTTPS with self-signed certificate). Do not redirect towards port 8080 (HTTP) as this will cause issues with Keycloak mixing up HTTPS and 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
/olvid/
/auth/realms/olvid_admin/ (the final /olvid_admin/ may change if you decide to use another name for your Olvid admin realm)

If you do not have such a reverse proxy, 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.

3.1 Install the packages

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

3.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

3.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;
  location / {
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_pass https://127.0.0.1:8443;
  }
  client_max_body_size 10M;

  listen [::]:443 ssl ipv6only=on;
  listen 443 ssl;
  ssl_certificate /etc/letsencrypt/live/keycloak.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/keycloak.com/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

server {
  server_name keycloak.com;
  listen [::]:80;
  listen 80;
  if ($host = keycloak.com) {
    return 301 https://$host$request_uri;
  }
  return 404;
}

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 be able to connect to your keycloak server through its public DNS.