CRDM Keycloak Setup

Docker Setup for the Keycloak instance of the "Center for Research Data Management". The keycloak service maintains separate realms for the main (tu-data realm) and the test instance (tu-data-test realm) of TU Wien Research Data. Further information about Keycloak can be found in the official documentation.

Secrets and Configuration

We all keep secrets.
Similarly, some things such as passwords should be kept secret when deploying in production!
For this reason, we use environment variables to store the confidential parts of our configuration. Since exporting the correct environment variables manually every time can be very tedious, we use .env files.

To quickly spin up a development instance, the current setup can handle the absence of a .env file by using fallback values provided in the docker-compose.yml file. These fallbacks will take care of giving the environment variables appropriate values. As mentioned above however, there are environment variables holding sensitive data (e.g. database password) and thus these fallbacks SHOULD NOT be used in a production setting.

Example Secrets File

An example .env file is available as .example.env. Its goal is to give a rough overview of what the environment variables and their values should look like. After copying the file (cp .example.env .env) and replacing the dummy values, it is ready for use. Yet again, DO NOT use these values in production; they are embrassingly simple!

Performing a Keycloak Realm(s) Export/Import

The primary reason to export/import realms is simple: keep a backup of the current setting. With this feature, we can back up the current keycloak data and restore them whenever required. Better safe than sorry!

Exporting Realms

Exporting one or multiple realms is important, in case backups or data transfer between servers is needed. The export-realms.sh script is responsible for dumping all the realms in a JSON file.

The Keycloak Admin Console offers also an easy way to export realms. So why not use that instead? Because the export file won't contain any user data. Besides that, the client secrets will be masked, which means that we won't be able to recreate the same exact instance using only this file.

Brief explanation of the arguments used for exporting realms

• -Djboss.socket.binding.port-offset
  Specifies port offset which this action will use. We want to run the export on a different port than Keycloak itself. By default, the jboss server in the current setup uses the 9990 port. Therefore, providing e.g. 100 as a value here will result in the command using the 10090 port.

• -Dkeycloak.migration.action
  Specifies what action should be taken, export or import.

• -Dkeycloak.migration.provider
  Defines how we want the data. We use singleFile, to export all the data into a single file.

• -Dkeycloak.migration.usersExportStrategy
  Specifies the strategy to export realm users. We use REALM_FILE to export the users to the same file as the realm configuration.

• -Dkeycloak.migration.file
  Defines the file where we want to save the data. Remember to prepend to the filename the exact same value that is used for the volume mapping in the docker-compose.yml.

Importing Realms

Having a dockerized Keycloak service that works out of the box and contains an imported realm with its default users is very useful. This not only simplifies the setup process, but also allows us to share a replicable Keycloak instance with others. The import-realms.sh script is responsible for reading and importing all the realms from a JSON file (that was naturally exported from Keycloak itself).

Brief explanation of the arguments used for importing realms

• -Djboss.socket.binding.port-offset
  Specifies port offset which this action will use. We want to run the import on a different port than Keycloak itself. By default, the jboss server in the current setup uses the 9990 port. Therefore, providing e.g. 10 as a value here will result in the command using the 10000 port.

• -Dkeycloak.migration.action
  Specifies what action should be taken, export or import.

• -Dkeycloak.migration.provider
  Defines how we are importing the data. We use singleFile to import all the data from a single file.

• -Dkeycloak.migration.strategy Specifies how to proceed when a realm with the same name already exists in the database. We use IGNORE_EXISTING to avoid overwriting a realm if it already exists.

• -Dkeycloak.profile.feature.upload_scripts
  The ability to enable custom scripts at startup. We use enabled since we have a logging script.
  Note: This feature is deprecated and has been removed from version 18.0 and later on.

• -Dkeycloak.migration.file
  Defines the file which we want to import the data from. Remember to prepend to the filename the exact same value that is used for the volume mapping in the docker-compose.yml.