Configuration of Back-End Credentials

Mindbreeze InSpire

Introduction

This instruction manual applies to G7 appliances.

Mindbreeze InSpire uses the Keycloak software component to manage sign-on credentials. This section describes the most important use cases (such as changing passwords or creating users). You can also find additional documentation here: Keycloak 11.0 Server Administration

Change password

The first time you log in to the Management Center, you will be asked to change your password. If you want to change a user’s password at a later time, proceed as follows: In the Management Center, navigate to the menu item “Setup”, “Credentials” and then “Users” under “Manage”. Search for the user in question using the search function or click on “View all users” to view a list of users. Click on “Edit” for the relevant user. In the “Credential” tab you can set a new password. You can use the “Temporary” setting to determine whether the user has to change the password the next time he or she logs on. Confirm your entries with “Reset Password”.

Create a user

You can create multiple users. In the Management Center, navigate to the menu item “Setup”, “Credentials” and then “Users” under “Manage”. Click on “Add user” on the right, then enter the user name “Username” and click on “Save”. Then switch to the “Credentials” tab to set a password. This is described in the previous section “Change password”. After you have set a password, you must assign roles to the user, otherwise the new user cannot be used properly. To do this, see the following section entitled “Managing roles”. To use the “Forgot/reset password” function, we recommend that you enter a valid e-mail address for each user.

Managing roles

Access to the various areas of the Management Center (e.g. “Reporting”, “Configuration”) is regulated by roles. For example, a user has to be assigned the role “InSpire Config Administrator” to be able to use the “Configuration” item in the Management Center. Several “InSpire” roles have already been defined by default. You can call up the list of all available roles as follows: In the Management Center, navigate to the menu item “Setup”, “Credentials” and then “Roles” under “Configure”. The user “admin” is assigned all roles by default. You can assign roles to or remove roles from users as follows: In the Management Center, navigate to the menu item “Setup”, “Credentials” and then “Users” under “Manage”. Search for the user in question using the search function or click on “View all users” to view a list of users. Click on “Edit” for the relevant user. Switch to the “Role Mappings” tab. You can assign roles here.

Standard roles

Several roles that are required for operation are preconfigured in the as-delivered settings. This section describes which roles that includes and their significance.

The roles can be divided into 3 categories:

• Mindbreeze InSpire roles (name starts with “InSpire”)
• app.telemetry roles (name starts with „Fabasoft app.telemetry“)
• Keycloak administration roles

In the following section, the Mindbreeze "InSpire Management Center" is abbreviated as MMC.

Description of the Mindbreeze InSpire roles

The following Mindbreeze InSpire roles are predefined by default:

Description of the Keycloak administration roles

The following Keycloak administration roles are predefined by default:

You can also find additional documentation here: Keycloak 11.0 Server Administration

Description of the app.telemetry roles

The following app.telemetry roles are predefined by default:

Further documentation can be found at: Fabasoft app.telemetry Installation Guide.

Cookies

For security reasons, all cookies issued by the Management Center or Keycloak Service have the SameSite option set to Strict. See RFC6265.

In some rare cases it may be necessary to reduce the security level. For this purpose, SameSiteValue=Lax or SameSiteValue=None can be set in the file /var/data/env/reverse-proxy.env. The setting will become active after a restart of the reverse-proxy container.

Reset configuration to Mindbreeze standards

If the credentials management is no longer working properly, the credentials management can be reset to Mindbreeze standards. A malfunction can have the following causes:

• The password for the administrator has been lost
• A configuration required for the operation of Mindbreeze InSpire has been changed, including the following parts of the configuration
  • Roles with names beginning with "InSpire"
  • The client "mindbreeze-inspire".
  • The realm theme "mindbreeze".

Resetting to Mindbreeze standards resets the password of the administrator and resets the configuration of the parts of the configuration necessary for operation. Other parts of the configuration will not be changed. We recommend making a backup before resetting.

Resetting to Mindbreeze standards is done as follows:

• Log on to the appliance terminal with the root user.
• Navigate to the directory /var/data/upload/image/keycloak/scripts
• Run the script reset_to_mindbreeze_defaults.sh and read the warnings carefully. Finally, run the script again with a parameter that you have taken from the warnings.
• The reset takes a few minutes; the Mindbreeze services are not available during this time.

Backup and recovery of credentials

Automatic backup

The database and associated configuration files are backed up locally on a daily basis. The backup target in the keycloak container is as follows:

/data/backup/curr

This directory is also available on the host at

/var/data/keycloak/data/backup/curr

This directory must be included in an external backup.

Manual backup

The local backup can also be triggered manually. The backup is always stored in the same directory as described above. The backup does not affect the running operation. Access to the command line is necessary. Execute the following commands:

# open a shell inside the keycloak container

docker exec -it keycloak bash

# within the keycloak container, impersonate the jboss user

su jboss –

# as jboss user, execute the backup script

./backup.sh

# this can take a few minutes

Restoring a backup

A backup can be restored manually using the command line. Since the containers have to be restarted several times, the services are not available during this time. A prerequisite for recovery is an intact backup directory that has been stored or copied in /var/data/keycloak/data/. In this example, the copied backup directory is located in /var/data/keycloak/data/restore. Execute the following commands:

# stop the keycloak container

docker stop keycloak

# remove the keycloak container

docker rm keycloak

# locate the restore script (docker_export_import_db.sh),

# it is /var/data/upload/image/keycloak/scripts/docker_export_import_db.sh, if the appliance has never been updated, it is /var/data/upload/image/keycloak/scripts/ docker_export_import_db.sh

# run the restore script with the current version number of Mindbreeze, the restore directory path relative to the keycloak container and in import mode

/var/data/upload/image/keycloak/scripts/docker_export_import_db.sh 19.1.2.345 /data/restore import

# this can take a few minutes

# watch the console output for the message “import finished successfully”, then actively exit the script

# the restore process creates a temporary container that must be removed

# stop the temporary keycloak container

docker stop keycloak

# remove the temporary keycloak container

docker rm keycloak

# now create the real keycloak container

# locate the create script

# it is  /var/data/upload/image/keycloak/create.sh, if the appliance has never been updated, it is /var/data/upload/image/keycloak/create.sh

# run the create.sh script

/var/data/upload/image/keycloak/create.sh

# restart all container to apply the restored data

systemctl restart docker

# this can take a few minutes

Error diagnosis/troubleshooting

Log Files

The following log files can be helpful for troubleshooting:

# in-progress backups

/var/data/keycloak/data/temp/backup.log

# finished backups

/var/data/keycloak/data/curr/backup.log

# keycloak server logs within the keycloak container:

/opt/jboss/keycloak/standalone/log/server.log

# security logs within the inspire container:

/var/log/secure

Error on Upgrade “verify.sh: ERROR: keycloak update script failed”

A possible cause of this error is missing or incorrect configuration files.

Check the file /var/data/keycloak/config/keycloak_h2_db_name. With InSpire version 20.3 or older the file should have the content keycloak_4_6_0. With InSpire version 20.4 or later, the file should have the content keycloak_10_0_2.

If the file is missing or the contents do not match, correct this and try the upgrade again.

Important notes for InSpire downgrades

General notes

In general, a full backup (not only of Keycloak) must be performed before a downgrade.

With certain InSpire versions a downgrade is not possible without keeping all keycloak data. This applies to data such as additionally created clients (synchronized users, customized user role mappings). The following InSpire versions are affected:

• 19.0
• 20.3

This means, for example, that when downgrading from 20.4 to 20.3 not all Keycloak data is preserverd, when downgrading from 20.3 to 20.2 the Keycloak data is preserved.

If a downgrade to those certain versions has to be performed, the keycloak data must be re-entered manually after the downgrade.

In the case of downgrades, a distinction is made between 2 basic cases:

1. In the past, an update was performed. When downgrading, it is intended to go back to the old version. "Downgrade after update". This is usually the case.
2. Downgrade to an old version, that was never been run on the appliance before. "Downgrade without previous version"

The Keycloak data is stored in database files in the /var/data/keycloak/data/data/ directory. The database files contain the Keycloak version in the file name.

• InSpire 19.0 up to including InSpire 20.3 uses Keycloak 4.6
• InSpire 20.4 uses Keycloak 10.0
• InSpire 20.5 uses Keycloak 11.0

The following sections describe the steps needed for each case:

Downgrade after upgrade

1. Before downgrading, make sure that there are old database files in the /var/data/keycloak/data/data/ directory.

e.g. on an InSpire 20.4:

# ll  /var/data/keycloak/data/data/

total 2076

drwxr-xr-x 2 1000 1000       6 Sep  8 13:43 content

drwxr-xr-x 2 1000 1000      26 Sep  8 13:43 kernel

-rw-r--r-- 1 1000 1000     146 Sep 16 16:57 keycloak_10_0_2.lock.db

-rw-r--r-- 1 1000 1000 1302528 Sep 17 10:16 keycloak_10_0_2.mv.db

-rw-r--r-- 1 1000 1000    7924 Sep 16 16:57 keycloak_10_0_2.trace.db

-rw-r--r-- 1 1000 1000     146 Sep 14 10:50 keycloak_4_6_0.lock.db

-rw-r--r-- 1 1000 1000  798720 Sep 14 11:19 keycloak_4_6_0.mv.db

-rw-r--r-- 1 1000 1000    4507 Sep 14 10:46 keycloak_4_6_0.trace.db

drwxr-xr-x 2 1000 1000       6 Sep 14 10:44 timer-service-data

drwxr-xr-x 3 1000 1000      35 Sep 14 11:19 tx-object-store

In this list you can see that a keycloak_4_6_0.mv.db database file exists, which is from the previous, old InSpire version. If you cannot find an older database file here, please follow the section "Downgrade without previous version" instead.

1. Install the old InSpire version in the MMC under "Update". The old Keycloak database file will be used again. All Keycloak data is then back to the state before the last InSpire update.
2. Note: if you have changed your password since the last InSpire update, you must use the old password again after the downgrade. You will also need to manually redo any changes you have made in Keycloak since the last InSpire update, if necessary.
3. You are now using the old version of InSpire again with the old version of Keycloak. In order to be able to update in the future without problems, you have to do the following steps:

Since the old database files will now be used, you will have to delete the database files with the new version to prevent the data from diverging.

# ll /var/data/keycloak/data/data/

total 2080

drwxr-xr-x 2 1000 1000       6 Sep  8 13:43 content

drwxr-xr-x 2 1000 1000      26 Sep  8 13:43 kernel

-rw-r--r-- 1 1000 1000     146 Sep 16 16:57 keycloak_10_0_2.lock.db

-rw-r--r-- 1 1000 1000 1302528 Sep 17 10:16 keycloak_10_0_2.mv.db

-rw-r--r-- 1 1000 1000    7924 Sep 16 16:57 keycloak_10_0_2.trace.db

-rw-r--r-- 1 1000 1000     146 Sep 17 11:15 keycloak_4_6_0.lock.db

-rw-r--r-- 1 1000 1000  798720 Sep 17 11:15 keycloak_4_6_0.mv.db

-rw-r--r-- 1 1000 1000    8469 Sep 17 11:15 keycloak_4_6_0.trace.db

drwxr-xr-x 2 1000 1000       6 Sep 14 10:44 timer-service-data

drwxr-xr-x 3 1000 1000      35 Sep 14 11:19 tx-object-store

In this case you must delete the files keycloak_10_0_2.lock.db, keycloak_10_0_2.mv.db and keycloak_10_0_2.trace.db.

Then check the contents of the following files:

# cat /var/data/keycloak/config/keycloak_version

4_6_0

# cat /var/data/keycloak/config/keycloak_h2_db_name

keycloak_10_0_2

The contents of the file /var/data/keycloak/config/keycloak_h2_db_name needs to be changed. Change the version number according to the file /var/data/keycloak/config/keycloak_version.

then check the contents of the following files, the versions should now match (with the old version):

# cat /var/data/keycloak/config/keycloak_version

4_6_0

# cat /var/data/keycloak/config/keycloak_h2_db_name

keycloak_4_6_0

This completes the downgrade from Keycloak's perspective.

Downgrade without previous version

1. In this case there is no database file that can be used after the downgrade. Check the directory /var/data/keycloak/data/data/ and make sure that no older database files exist.

# ll  -a /var/data/keycloak/data/data/

total 796

drwxr-xr-x 6 1000 root    173 Sep 17 11:32 .

drwxr-xr-x 4 1000 root     32 Sep 14 11:00 ..

drwxr-xr-x 2 1000 1000      6 Sep  8 13:43 content

drwxr-xr-x 2 1000 1000     26 Sep  8 13:43 kernel

-rw-r--r-- 1 1000 1000    146 Sep 17 11:15 keycloak_10_0_2.lock.db

-rw-r--r-- 1 1000 1000 798720 Sep 17 11:15 keycloak_10_0_2.mv.db

-rw-r--r-- 1 1000 1000   8469 Sep 17 11:15 keycloak_10_0_2.trace.db

drwxr-xr-x 2 1000 1000      6 Sep 14 10:44 timer-service-data

drwxr-xr-x 3 1000 1000     35 Sep 14 11:19 tx-object-store

If database files of older versions are listed here, continue with the section "Downgrade after update" instead.

1. Install the old InSpire version in the MMC under "Update". As there is no old Keycloak database file, Keycloak is initialized "empty". After the downgrade no login to the MMC is possible, because no user exists in the database. Execute the following commands to reset Keycloak to InSpire default settings:

docker rm -f keycloak

bash /var/data/upload/image/keycloak/scripts/recreate_volumes.sh -f

bash /var/data/upload/image/keycloak/create.sh

docker start keycloak

You can monitor the progress with the command journalctl -f. With the log entry "Initial Config Sucessful" the operation is completed. Restart all containers with the following command: systemctl restart docker

1. After that, you have to manually redo all the changes you made in Keycloak in the new InSpire version, if necessary.
2. You are now using the old version of InSpire again with the old version of Keycloak. This completes the downgrade from Keycloak's perspective.