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 21.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 search for “*” to view a list of all users. Click on the relevant user. In the “Credentials” tab you can set a new password with a click on “Reset 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 “Save”.

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”, then enter the user name “Username” and click on “Save”. Then switch to the “Credentials” tab and click on “Set password” 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 search for “*” to view a list of all users. Click on the relevant user. Switch to the “Role Mappings” tab. You can assign roles here.

Default Roles

Several roles that are required for operation are preconfigured in the default settings. This section describes these roles 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 21.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.

TLS

For security reasons, TLS versions before TLSv1.2 as well as SSL (all versions) are disabled.
Those versions are no longer supported by most browsers as well.

In some rare cases it may be necessary to enable TLSv1.1 again (not recommended).
For this purpose, TLSVersions='TLSv1.2 TLSv1.1' 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 Default

If the credentials management is no longer working properly, the credentials management can be reset to Mindbreeze default. 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.
• Run the following command:
• docker exec -it inspire-system-manager inspire-systemmanager reset keycloak --force
• 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 keycloak user

# you must not invoke a login shell (do not use ‘su – keycloak’)

su keycloak –

# as keycloak user, execute the backup script

./keycloak/scripts/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:

# open a shell inside the keycloak container

docker exec -it keycloak bash

# open a shell inside the keycloak container

docker exec -it keycloak bash

# call restore script (run the following commands)

./keycloak/scripts/export_import_db.sh /opt/keycloak /data/backup/curr import

# this can take a few minutes

# watch the console output for the message “import finished successfully”

# restart all containers 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/keycloak/log/server.log

# security logs within the inspire container:

/var/log/secure

Error When Updating to Version 20.4

If you receive the following error message when updating to version 20.4:

• verify.sh: ERROR: keycloak update script failed

Follow please this instruction.

Error: Limitations for Keycloak Data When Downgrading

When downgrading to some older versions it is not possible to retain all Keycloak data. This applies to data such as additionally created clients, synchronized users, and customized user role mappings.

However, to keep this data, please follow this instruction.

Error When Downgrading From Version 21.3 to 21.2 or Older

After a downgrade from version 21.3 to 21.2, credentials can no longer be loaded, corresponding error messages are displayed in the log, and affected services no longer start.

To fix this problem, please follow these instructions.

SSL Certificate Error During Update

If you receive the error listed below during an update (maybe you have to click on “Download Log” to see the complete logs), please follow these instructions (Section „Update with custom Keycloak system changes“).

...
Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

...

Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

...