5. Database configuration

Keycloak uses an external database to store configurations and settings. By default, the Keycloak app installs and configures a PostgreSQL database. In case you want to use your own database backend, you can change the database settings for Keycloak prior or after the app installation.

5.1. Default database

The Keycloak app installation procedure automatically installs and configures the PostgreSQL database during the initial installation of the app in the UCS domain. Keycloak uses this database for all additional installations of the app in the UCS domain. The default PostgreSQL database on UCS doesn’t configure high availability, load balancing, and replication.

However, it’s not mandatory to use the default PostgreSQL database instance. Administrators may decide to use another one, for example, if there is a need to use an already existing or clustered database.

Tip

If you need database replication and failover, you must use a database cluster setup. Then, you configure the database connection in the Keycloak app, as described in Changing the database configuration, to use the database cluster instead of the local single database instance.

Examples:

For PostgreSQL you need to set up your own database cluster and cover the topics high availability, load balancing, and replication. Describing this setup is beyond the scope of this document.

For MariaDB you need to set up a MariaDB Galera Cluster. Describing this setup is beyond the scope of this document.

5.2. Custom database

Keycloak supports a wide range of different databases as backend. For detailed information, see Supported databases in Configuring the database [7].

Note

On the contrary to the official Keycloak container image, the custom image that the Keycloak App provides, doesn’t contain the drivers that support an Oracle Database. Using an Oracle Database as a backend for Keycloak isn’t supported.

The Keycloak app provides app settings for the configuration of the database backend. For the available settings, see the Settings section.

Important

Changing these settings doesn’t affect the database itself, no matter if you use the command line tools or the App Center. The database settings only tell Keycloak where and how to connect to the database. Ensure that you first perform the needed changes on the database itself.

5.3. Changing the database configuration

The following sections explain how to change the database settings. The example uses the MariaDB database and the following assumptions:

• The database for Keycloak exists.

• The Keycloak server can connect to the database.

• A user account with the appropriate permissions for the database exists.

Note

The database user needs the following minimum privileges to work in a single machine setup. Use the GRANT command:

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, REFERENCES, INDEX, DROP
ON `<database>`.* TO `<user>`@`<host>`;

5.3.1. Initial installation

This section explains how to setup the Keycloak app to use a different database, such as MariaDB in this example, during the initial and first installation of the Keycloak app in the UCS domain.

To specify an existing MariaDB database during the initial installation, you can either run the following installation command from the command line:

Listing 5.1 Install Keycloak with alternative database settings

$ univention-app install keycloak --set \
    kc/db/url="jdbc:mariadb://database-server:3306/database-name" \
    kc/db/password="database-password" \
    kc/db/username="database-username"

Or alternatively, you can set the corresponding app settings kc/db/url, kc/db/password and kc/db/username during the installation in the Univention App Center.

Additional installations of the Keycloak app automatically use these database settings without any further database configuration.

5.3.2. After initial installation

After you completed the app installation in the UCS domain, Keycloak stores the database settings in a domain wide settings object. Subsequent installations of the Keycloak app use these settings, regardless of the database settings during the installation.

Warning

Changing the database settings after the installations means loosing every existing configuration settings and session.

You have to manually backup Keycloak before and restore the settings after changing the database backend. For more information, see Backup and restore.

To change the database settings for existing Keycloak instances you have to use the following steps:

1. Change the domain wide database settings with the following command on one of the UCS systems that has Keycloak installed:

   $ univention-keycloak domain-config \
     --set username="database-username" \
     --set uri="jdbc:mariadb://database-server:3306/database-name" \
     --set password="database-password" \
     --set driver="org.mariadb.jdbc.Driver" \
     --set ping_datatype="VARBINARY(255)"
   

2. Re-configure one of the Keycloak instances and verify that it works:

   $ univention-app configure keycloak
   

3. Re-configure the rest of the Keycloak instances.