Olvid - Keycloak Setup Guide (2023)

install the keycloak

You can find the official Keycloak server management documentation here:

Refer to it whenever you think your setup might differ from the default setup we've described here.

If you plan on running Keycloak natively on your server, read on.
If you prefer to run Keycloak in a container, read on.Running Keycloak on a Containerpage.

1. Download the Keycloak + Olvid package

The Olvid plugin isaccumulatedwith full Keycloak distribution (Quarkus version). On the Linux server, download the latest package from:

https://olvid.io/keycloak_olvid_21.1.2_3.0.2.tar.gz

Check that the packet's SHA-256 hash isdeb9d0b3cc91ee8e04f9efe5945049696e5c7dbd6606ad58546efbe94f949209and unzip the file to get akeycloak_olvid_21.1.2_3.0.2folder. All the steps below arerun inside this folder.

> wget https://forget.io/keycloak_forget_21.1.2_3.0.2.tar.gz> sha256sum keycloak_forget_21.1.2_3.0.2.tar.gz> tar xvf keycloak_forget_21.1.2_3.0.2.tar.1ak_1 για cd. _3.0.2/

2. Modify the configuration file

You can find Keycloak's configuration file atkeycloak_olvid_21.1.2_3.0.2/conf/keycloak.conf. Open it in your favorite text editor to configure the database connection (parts in red below). You don't need to configure the other options in this file, they are already configured correctly in the boot package (via command line options).

# Basic settings for running in production. Change accordingly before deploying the server.# Database# The database vendor.db=postgres# The database username user.db-username=keycloak# The database password user.db-password=Password# The full URL of the JDBC database. If not provided, a default URL will be set based on the database vendor.db-url= selectedjdbc:postgresql://postgres.local.ip/keycloak[...]

Fordatabasefield, the value must be the vendor of the database system (seeofficial documentation):

• postgrespara PostgreSQL
• mysqlpara MySQL
• mssqlpara Microsoft SQL Server

3. Start Keycloak

Now that Keycloak is configured, you can start the server. The first launch will be used to create the credentials for the first Keycloak administrator. Okeycloak_olvid_21.1.2_3.0.2/1.olvid_scripts/The folder contains a special script for this. enter adminUser nameePasswordof your choice:

> keycloak_olvid_21.1.2_3.0.2/1.olvid_scripts/first-launch-keycloak.sh -u-PI

Check the standard output logs for errors. If all goes well, you can connect to the internal IP/localhost on the port8080and you should see “Welcome toKeychain" cover. The login URL should look something like thishttp://10.1.2.3:8080/auth/. After configuring the reverse proxy we can add a redirect, but for now the URLhe mustdone with/authentication/.

4. Check connectivity to the Olvid distribution server

You can verify that the Keycloak server can reach the required API point to query the Olvid server with the command:

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

If you get the output{"error":3}, it's okay 😀

4.1 Outbound proxy configuration

If your server needs to go through an HTTP proxy for outgoing connections, this is possible! Oofficial documentationexplains different solutions for this, but the one we found the simplest is to use a proxy mapping on Keycloak's startup command line.

⚠️ Warning ⚠️There is a typo in the Keycloak documentation, regular expressions must be used.*and not simply*.

To add a proxy mapping, open the filekeycloak_olvid_21.1.2_3.0.2/1.olvid_scripts/run-keycloak.shand modify the command line by adding something like--spi-connections-http-client-default-proxy-mappings="'.*;http://proxy.local.ip:3128'". Pay close attention'e"on the command line, all are required!

#!/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,arquivo --spi-connections-http-client-default-proxy-mappings="'.*;http://proxy.local.ip:3128""

5. Create a startup service to start Keycloak automatically

To automatically start Keycloak with your server, you can create a startup script and add it to the default services. If your server usessystem(this applies to Ubuntu or CentOS), you can create a/etc/systemd/system/keycloak.servicefile containing the following lines (replace the part in red with the actual path to thekeycloak-olvidpasta):

[Unit]Description=KeycloakAfter=syslog.target network.targetBefore=httpd.service[Service]User=rootGroup=rootLimitNOFILE=102642PIDFile=/var/run/keycloak/keycloak.pidExecStart=/opt/keycloak_olvid_21.1.2_3.0.2/1.olvid_scripts/run-keycloak.shStandardOutput=syslogStandardError=syslogSyslogIdentifier=keycloak[Install]WantedBy=multi-user.target

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

> systemctl iniciar keycloak> systemctl ativar keycloak

Unlike manual initialization, where the logs go to standard output, when initializing this way, Keycloak logs are sent tosystem logand is written to the filedata/log/keycloak.logWithinkeycloak-olvidpasta.

6. Set up a reverse proxy

The Keycloak server is configured to run behind a reverse proxy that handles SSL/TLS and redirects connections from Keycloak's public DNS to the keycloak server on port 8080.Unlike the legacy Keycloak which needed to run over HTTPS with a self-signed certificate, the newer Keycloak can run over plain HTTP.

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

• X-forwarded to
• X-Forwarded-Proto
• Forwarded host X

And some buffer sizes may need to be adjusted (the defaultnginxbuffers are too small). see the samplenginxconfiguration below.

To access Keycloak and the Olvid admin console via simple URLs, we recommend adding some simple redirects:

• /redirects to/authentication
• /forgotredirects to/auth/olvid/#

If you don't already have a reverse proxy, you can runnginxdirectly to the Keycloak server. This will also require you to have your server's SSL certificate. Here are the installation stepscertifiedbot(to obtain a Let's Encrypt certificate) andnginxon an Ubuntu 20.04 server.

6.1 Install packages

> apt instalar certbot nginx-full python3-certbot-nginx

6.2 Request the certificate

Here, we assume that your public DNS iskeycloak.com, replace it with the server's real DNS.

> certbot --nginx -dkeycloak.com

When solicited:

• enter an email address (which will be shared with Let's Encrypt)
• accept the terms
• decide if you want to share your email with the EFF
• choose to redirect all HTTP traffic to HTTPS (this will modify the default nginx site accordingly)

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

> status systemctl certbot.timer

> systemctl recarrega nginx

6.3 Configuring nginx

Now we need to create thenginxconfig file that will actually redirect HTTPS requests to Keycloak. To create/etc/nginx/sites-available/keycloak.confcontaining:

server { server_namekeycloak.com; # To redirect only a specific set of routes, you can replace the following line with something like # location ~ ^(/auth/resources/|/auth/js/|/auth/realms/olvid/) { location /auth { proxy_set_header proxy_set_header X-Forwarded-Proto $schema; proxy_set_header X-Forwarded-Host $host; proxy_buffer_size 128k; } location /olvid { return 302 /auth/olvid/#; } location = / { return 302 /auth; } cliente_max_body_size 10M; listen [::]:443 ssl ipv6only=on? hear 443 SSL? ssl_certificate /etc/letsencrypt/live/keycloak.public.dns/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/keycloak.public.dns/privkey.pem; does it include /etc/letsencrypt/options-ssl-nginx.conf? ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;} server { server_namekeycloak.public.dns; listen [::]:80; listen 80; return 301 https://$host$request_uri;}

Now to enable this setting and disable the default setting:

> 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 the keycloak server via your public DNS.

Now you can get on with itConfiguring Keycloak