Skip to content

Updating Keycloak

Hint - version changes

The new Keycloak version comes with some important changes, see Changes

Updating from Version 15.0.0 and Later

... with Automatic Export and Import of the Configuration

Hint - internal data structure changes

Due to Keycloak-internal data structure changes the installation script proceeds as follows:

  1. Export of the old Keycloak configuration (with timestamp and keycloak version).

  2. Move the old configuration (*.install-bak).

  3. Update Keycloak.

  4. Reimport the exported configuration.

  1. In a browser, log on to the SEAL Systems delivery platform with your logon data:

    https://delivery.sealsystems.de

    Hint - logon data

    You receive the logon data from your Technical Project Manager at SEAL Systems.

  2. Download the Keycloak - 26.8.1.162 - msi folder. It is saved as Keycloak - 26.8.1.162 - msi.zip.

  3. Extract the .zip archive.

  4. In a PowerShell (Administrator), change to the Keycloak - 26.8.1.162 - msi directory and start installing the package:

    cd "Keycloak - 26.8.1.162 - msi"

    Set-ExecutionPolicy Bypass -Scope Process -Force; .\install.ps1

    Hint - insufficient java version

    If the Java Version is insufficient, the install.sh script stops the installation with an error. Keycloak 22.0 and later versions require at least version 17, see requirements.

    Set the JAVA_HOME environment variable when installing Java.

  5. Open the required firewall ports:

    Set-ExecutionPolicy Bypass -Scope Process -Force; .\firewall.ps1

  6. Change to the common configuration directory:

    cd "C:\ProgramData\SEAL Systems\config"

  7. In an editor, compare the new keycloak.conf configuration file to the old keycloak.conf.install-bak configuration file.

    Add your customer-specific changes, e. g. certificates.

    For details on the general configuration, see Configuring the TLS Encryption.

  8. Start the service:

    start-service seal-keycloak

  9. After the successful update, delete no longer required directories and files from the SEAL data directory:

    • Windows

      "$env:ProgramData\SEAL Systems\data\"

    • Linux

      /opt/seal/data/

Steps of the install.ps1 Script

The script executes the following steps:

  1. Export the existing Keycloak configuration (using the command described in configuration export) with the previous version (15 or 21) to the following directory:

    • Windows

      "$env:ProgramData\SEAL Systems\data\seal-keycloak-export_from-version_<old_version>_<timestamp>.install-bak"

    • Linux

      /opt/seal/data/seal-keycloak-export_from-version_<old_version>_<timestamp>.install-bak

    Example - log message

    • Windows

      Exporting settings from old version 21.0.1.40 to directory "C:\ProgramData\SEAL Systems\data\seal-keycloak-export_from-version_21_20230925T133600977026309.install-bak"...
...finished successfully.

    • Linux

      Exporting settings from old version 21.0.1 to directory /opt/seal/data/seal-keycloak-export_from-version_21_20230925_133600977026309.install-bak...
...finished successfully.

  2. Stop the service.

  3. Back up the content of the data directory:

    • Windows

      "$env:ProgramData\SEAL Systems\data\seal-keycloak\"` directory into `"$env:ProgramData\SEAL Systems\data\seal-keycloak_<timestamp>.install-bak\"

    • Linux

      /opt/seal/data/seal-keycloak/` directory to `/opt/seal/data/seal-keycloak_<timestamp>.install-bak/

    Example - log message

    • Windows

      Moving old data directory "C:\ProgramData\SEAL Systems\data\seal-keycloak" to "C:\ProgramData\SEAL Systems\data\seal-keycloak_20230925T133600977026309.install-bak"...
...finished successfully.

    • Linux

      Moving old data directory /opt/seal/data/seal-keycloak to /opt/seal/data/seal-keycloak_20230925_133600977026309.install-bak...
...finished successfully.

  4. Import the old Keycloak configuration (using the command described in configuration import).

    Example - log message

    • Windows

      Importing settings from old version 21.0.1.40 into new version 22.0.0.61 from directory "C:\ProgramData\SEAL Systems\data\seal-keycloak-export_from-version_21_20230925T133600977026309.install-bak"...
...finished successfully.

    • Linux

      Importing settings from old version 21.0.1 into new version 22.0.0 from directory /opt/seal/data/seal-keycloak-export_from-version_21_20230925_133600977026309.install-bak...
...finished successfully.

... with Manual Export and Import of the Configuration

As of version 22.0 the installation script automatically performs the export and import of the configuration. If you prefer a manual update, you can proceed as described in the following instructions.

Hint - internal data structure changes

Due to Keycloak-internal data structure changes you have to proceed as follows:

  1. Export the old Keycloak configuration.
  2. Remove the old configuration.
  3. Update Keycloak.
  4. Reimport the exported configuration.

  1. Export the existing Keycloak configuration with version 15 or 21.

  2. In a browser, log on to the SEAL Systems delivery platform with your logon data:

    https://delivery.sealsystems.de

    Hint - logon data

    You receive the logon data from your Technical Project Manager at SEAL Systems.

  3. Download the Keycloak - 26.8.1.162 - msi folder. It is saved as Keycloak - 26.8.1.162 - msi.zip.

  4. Extract the .zip archive.

  5. Stop the service:

    stop-service seal-keycloak

  6. Remove the content of the "$env:ProgramData\SEAL Systems\data\seal-keycloak\" directory:

    Remove-Item "$env:ProgramData\SEAL Systems\data\seal-keycloak\*" -Force -Recurse

  7. In a PowerShell (Administrator), change to the Keycloak - 26.8.1.162 - msi directory and start installing the package:

    cd "Keycloak - 26.8.1.162 - msi"

    Set-ExecutionPolicy Bypass -Scope Process -Force; .\install.ps1

    Hint - insufficient java version

    If the Java Version is insufficient, the install.sh script stops the installation with an error. Keycloak 22.0 and later versions require at least version 17, see requirements.

    Set the JAVA_HOME environment variable when installing Java.

  8. Open the required firewall ports:

    Set-ExecutionPolicy Bypass -Scope Process -Force; .\firewall.ps1

  9. Start the service:

    start-service seal-keycloak

  10. Import the old Keycloak configuration into the new version.

Back to top