Installation of Keycloak (legacy)

This version of Keycloak is no longer maintained, and is no longer supported by the latest versions of the Olvid Plugin. If planning on a new Keycloak installation, or if upgrading an old installation, we strongly recommend using the latest version of Keycloak, as documented in our installation guide

The official Keycloak legacy installation documentation can be found here:

https://www.keycloak.org/docs/19.0.3/server_installation/#installation

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

1. Download the latest version of Keycloak Legacy

From your linux server, download the last version of Keycloak legacy, choosing the .tar.gz version, from:

https://github.com/keycloak/keycloak/releases/

And uncompress the archive to obtain a keycloak-19.0.3 folder. All the following steps are executed from within this folder.

> wget https://github.com/keycloak/keycloak/releases/download/19.0.3/keycloak-legacy-19.0.3.tar.gz
> tar xvf keycloak-legacy-19.0.3.tar.gz
> cd keycloak-19.0.3/

2. Download the Olvid Plugin

The latest version of the Olvid Plugin is available here:

https://olvid.io/olvid_keycloak_plugin_v2.1.1.tar.gz

It consists of a set of files to be installed in the right places so that Keycloak finds them at startup:

the Olvid Plugin itself, implementing a REST API to which the smartphones connect. It consists of a .jar file and an associated configuration module.xml
the Olvid Management Console, implemented in Vue.JS and served statically by Keycloak
the Olvid themes, used to customize some part of the Keycloak interface

If you decompress the archive inside the keycloak-19.0.3 folder, everything should be at the right location automatically!

> wget https://olvid.io/olvid_keycloak_plugin_v2.1.1.tar.gz
> tar xvf olvid_keycloak_plugin_v2.1.1.tar.gz

3. Modify the standalone-ha.xml configuration file

The standalone-ha.xml configuration file (ha stands for high availability, the Keycloak version able to run with multiple replicas) is used to configure everything about the Keycloak startup. The default template is located in the standalone/configuration folder and should not require too much modification, apart from adding Olvid related things and configuring the database.

3.1 Configuration of the database

Keycloak can run out of the box with an internal H2 database, which is enough for testing purposes, but is not recommended for production. At Olvid, we have used both MySQL and PostgreSQL without any problem and you will find below the procedure for both systems.

Some users have run into issues when using MariaDB: the Keycloak database initialization uses queries that are too long for MariaDB. Even if these issues can certainly be circumvented, we recommend avoiding MariaDB for Keycloak.

For PostgreSQL

First, you need to download and install the correct driver so that Keycloak can access your PostgreSQL database. From the keycloak-19.0.3 folder, do the following

> wget https://repo1.maven.org/maven2/org/postgresql/postgresql/42.5.0/postgresql-42.5.0.jar
> mkdir -p modules/org/postgresql/jdbc/main/
> mv postgresql-42.5.0.jar modules/org/postgresql/jdbc/main/

Then, create a module.xml file inside the modules/org/postgresql/jdbc/main/ folder, containing:

<module xmlns="urn:jboss:module:1.0" name="org.postgresql.jdbc">
  <resources>
	<resource-root path="postgresql-42.5.0.jar"/>
  </resources>
  <dependencies>
	<module name="javax.api"/>
	<module name="javax.transaction.api"/>
  </dependencies>
</module>

Now, open the standalone/configuration/standalone-ha.xml in your favorite editor and change the following lines. The lines in grey are here to indicate where in the xml hierarchy the elements should be added. Striked-through lines should be removed, black lines inserted. Parts in red should be customized by you.

<server xmlns="urn:jboss:domain:16.0">
  <profile>
    <subsystem xmlns="urn:jboss:domain:datasources:6.0">
      <datasources>
        <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="[...]">
          <connection-url>jdbc:h2:[...]</connection-url>
          <driver>h2</driver>
          <security>
            <user-name>sa</user-name>
            <password>sa</password>
          </security>
          <connection-url>jdbc:postgresql://postgresql:5432/keycloak</connection-url>
          <driver>postgresql</driver>
          <pool>
            <flush-strategy>IdleConnections</flush-strategy>
          </pool>
          <security>
            <user-name>keycloak</user-name>
            <password>password</password>
          </security>
          <validation>
            <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
            <background-validation>true</background-validation>
            <background-validation-millis>60000</background-validation-millis>
          </validation>
        </datasource>
        <drivers>
          <driver name="postgresql" module="org.postgresql.jdbc">
            <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
          </driver>
        </drivers>
      </datasources>
    </subsystem>
  </profile>
</server>

This example assumes you have a user name keycloak on PostgreSQL and that Keycloak data is stored in the keycloak database.

For MySQL

First, you need to download and install the correct driver so that Keycloak can access your MySQL database. From the keycloak-19.0.3 folder, do the following

> wget https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.31/mysql-connector-java-8.0.31.jar
> mkdir -p modules/com/mysql/jdbc/main/
> mv mysql-connector-java-8.0.31.jar modules/com/mysql/jdbc/main/

Then, create a module.xml file inside the modules/com/mysql/jdbc/main/ folder, containing:

<module xmlns="urn:jboss:module:1.0" name="com.mysql.jdbc">
  <resources>
	<resource-root path="mysql-connector-java-8.0.31.jar"/>
  </resources>
  <dependencies>
	<module name="javax.api"/>
	<module name="javax.transaction.api"/>
  </dependencies>
</module>

<server xmlns="urn:jboss:domain:16.0">
  <profile>
    <subsystem xmlns="urn:jboss:domain:datasources:6.0">
      <datasources>
        <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="[...]">
          <connection-url>jdbc:h2:[...]</connection-url>
          <driver>h2</driver>
          <security>
            <user-name>sa</user-name>
            <password>sa</password>
          </security>
          <connection-url>jdbc:mysql://mysql:3306/keycloak</connection-url>
          <driver>mysql</driver>
          <pool>
            <flush-strategy>IdleConnections</flush-strategy>
          </pool>
          <security>
            <user-name>keycloak</user-name>
            <password>password</password>
          </security>
          <validation>
            <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
            <background-validation>true</background-validation>
            <background-validation-millis>60000</background-validation-millis>
          </validation>
        </datasource>
        <drivers>
          <driver name="mysql" module="com.mysql.jdbc">
            <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
          </driver>
        </drivers>
      </datasources>
    </subsystem>
  </profile>
</server>

This example assumes you have a user name keycloak on MySQL and that Keycloak data is stored in the keycloak database.

Now re-open the standalone/configuration/standalone-ha.xml in your favorite editor and add the following line to load the keycloak module:

<server xmlns="urn:jboss:domain:16.0">
  <profile>
    <subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
      <providers>
        <provider>module:io.olvid.keycloak</provider>
      </providers>
    </subsystem>
  </profile>
</server>

Add the following lines to automatically load the Olvid themes:

<server xmlns="urn:jboss:domain:16.0">
  <profile>
    <subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
      <spi name="themeSelector">
        <default-provider>OlvidThemeSelector</default-provider>
        <provider name="OlvidThemeSelector" enabled="true"/>
      </spi>
    </subsystem>
  </profile>
</server>

Add the following lines to allow serving the Olvid administration console from within Keycloak:

<server xmlns="urn:jboss:domain:16.0">
  <profile>
    <subsystem xmlns="urn:jboss:domain:undertow:12.0" [...]>
      <server name="default-server">
        <host name="default-host" alias="localhost">
          <location name="/olvid" handler="olvid-console"/>
        </host>
      </server>
      <handlers>
        <file name="olvid-console" path="${jboss.home.dir}/olvid-console"/>
      </handlers>
    </subsystem>
  </profile>
</server>

Next step, start Keycloak.