Home
Home
German Version
Support
Impressum
22.1 Release ►

    Main Navigation

    • Preparation
      • Connectors
      • Initial Startup for G7 appliances
      • Setup InSpire G7 primary and Standby Appliances
    • Datasources
      • Configuration - Atlassian Confluence Connector
      • Configuration - Best Bets Connector
      • Configuration - COYO Connector
      • Configuration - Data Integration Connector
      • Configuration - Documentum Connector
      • Configuration - Dropbox Connector
      • Configuration - Egnyte Connector
      • Configuration - GitHub Connector
      • Configuration - Google Drive Connector
      • Configuration - GSA Adapter Service
      • Configuration - HL7 Connector
      • Configuration - IBM Connections Connector
      • Configuration - IBM Lotus Connector
      • Configuration - Jira Connector
      • Configuration - JiveSoftware Jive Connector
      • Configuration - JVM Launcher Service
      • Configuration - LDAP Connector
      • Configuration - Microsoft Azure Principal Resolution Service
      • Configuration - Microsoft Dynamics CRM Connector
      • Configuration - Microsoft Exchange Connector
      • Configuration - Microsoft File Connector (Legacy)
      • Configuration - Microsoft File Connector
      • Configuration - Microsoft Graph Connector
      • Configuration - Microsoft Project Connector
      • Configuration - Microsoft SharePoint Connector
      • Configuration - Microsoft Stream Connector
      • Configuration - Microsoft Teams Connector
      • Configuration - Salesforce Connector
      • Configuration - SAP KMC Connector
      • Configuration - SemanticWeb Connector
      • Configuration - ServiceNow Connector
      • Configuration - SharePoint Online Connector
      • Configuration - Sitecore Connector
      • Configuration - Web Connector
      • Configuration - Yammer Connector
      • Data Integration Guide with SQL Database by Example
      • Indexing user-specific properties (Documentum)
      • Installation & Configuration - Atlassian Confluence Sitemap Generator Add-On
      • Installation & Configuration - Caching Principal Resolution Service
      • Installation & Configuration - Jive Sitemap Generator
      • Installation & Configuration - Mindbreeze InSpire Insight Apps in Microsoft SharePoint On-Prem
      • Mindbreeze InSpire Insight Apps in Microsoft SharePoint Online
      • Mindbreeze Web Parts for Microsoft SharePoint
      • User Defined Properties (SharePoint 2013 Connector)
      • Whitepaper - Mindbreeze InSpire Insight Apps in Salesforce
    • Configuration
      • CAS_Authentication
      • Cognito JWT Authentication
      • Configuration - Alternative Search Suggestions and Automatic Search Expansion
      • Configuration - Back-End Credentials
      • Configuration - Chinese Tokenization Plugin (Jieba)
      • Configuration - CJK Tokenizer Plugin
      • Configuration - Collected Results
      • Configuration - CSV Metadata Mapping Item Transformation Service
      • Configuration - Entity Recognition
      • Configuration - Exporting Results
      • Configuration - Filter Plugins
      • Configuration - GSA Late Binding Authentication
      • Configuration - Identity Conversion Service - Replacement Conversion
      • Configuration - Index-Servlets
      • Configuration - Item Property Generator
      • Configuration - Japanese Language Tokenizer
      • Configuration - Kerberos Authentication
      • Configuration - Management Center Menu
      • Configuration - Metadata Enrichment
      • Configuration - Metadata Reference Builder Plugin
      • Configuration - Mindbreeze Proxy Environment (Remote Connector)
      • Configuration - Notifications
      • Configuration - Personalized Relevance
      • Configuration - Plugin Installation
      • Configuration - Principal Validation Plugin
      • Configuration - Profile
      • Configuration - QueryExpr Label Transformer Service
      • Configuration - Reporting Query Logs
      • Configuration - Reporting Query Performance Tests
      • Configuration - Request Header Session Authentication
      • Configuration - Shared Configuration (Windows)
      • Configuration - Vocabularies for Synonyms and Suggest
      • Configuration of Thumbnail Images
      • Cookie-Authentication
      • Documentation - Mindbreeze InSpire
      • I18n Item Transformation
      • Installation & Configuration - Outlook Add-In
      • Installation - GSA Base Configuration Package
      • Language detection - LanguageDetector Plugin
      • Mindbreeze Personalization
      • Mindbreeze Property Expression Language
      • Mindbreeze Query Expression Transformation
      • Non-Inverted Metadata Item Transformer
      • SAML-based Authentication
      • Trusted Peer Authentication for Mindbreeze InSpire
      • Using the InSpire Snapshot for Development in a CI_CD Scenario
      • Whitepaper - SSO with Microsoft AAD or AD FS
      • Whitepaper - Text Classification Insight Services
    • Operations
      • app.telemetry Statistics Regarding Search Queries
      • Configuration - app.telemetry dashboards for usage analysis
      • Configuration Usage Analysis
      • Deletion of Hard Disks
      • Handbook - Backup & Restore
      • Handbook - Command Line Tools
      • Handbook - Distributed Operation (G7)
      • Handbook - Filemanager
      • Handbook - Indexing and Search Logs
      • Handbook - Updates and Downgrades
      • Index Operating Concepts
      • Inspire Diagnostics and Resource Monitoring
      • InSpire Support Documentation
      • Mindbreeze InSpire SFX Update
      • Provision of app.telemetry Information on G7 Appliances via SNMPv3
      • Restoring to As-Delivered Condition
    • User Manual
      • Cheat Sheet
      • iOS App
      • Keyboard Operation
    • SDK
      • api.v2.alertstrigger Interface Description
      • api.v2.export Interface Description
      • api.v2.personalization Interface Description
      • api.v2.search Interface Description
      • api.v2.suggest Interface Description
      • api.v3.admin.SnapshotService Interface Description
      • Debugging (Eclipse)
      • Developing an API V2 search request response transformer
      • Developing Item Transformation and Post Filter Plugins with the Mindbreeze SDK
      • Development of Insight Apps
      • Embedding the Insight App Designer
      • Java API Interface Description
    • Release Notes
      • Release Notes 20.1 Release - Mindbreeze InSpire
      • Release Notes 20.2 Release - Mindbreeze InSpire
      • Release Notes 20.3 Release - Mindbreeze InSpire
      • Release Notes 20.4 Release - Mindbreeze InSpire
      • Release Notes 20.5 Release - Mindbreeze InSpire
      • Release Notes 21.1 Release - Mindbreeze InSpire
      • Release Notes 21.2 Release - Mindbreeze InSpire
      • Release Notes 21.3 Release - Mindbreeze InSpire
      • Release Notes 22.1 Release - Mindbreeze InSpire
    • Security
      • Known Vulnerablities
    • Product Information
      • Product Information - Mindbreeze InSpire - Standby
      • Product Information - Mindbreeze InSpire
    Home

    Path

    Sure, you can handle it. But should you?
    Let our experts manage the tech maintenance while you focus on your business.
    See Consulting Packages

    Configuration of Back-End Credentials

    Mindbreeze InSpire

    Copyright ©

    Mindbreeze GmbH, A-4020 Linz, 2022.

    All rights reserved. All hardware and software names used are brand names and/or trademarks of their respective manufacturers.

    These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes, or any other protected rights. The dissemination, publication, or reproduction hereof is prohibited.

    For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.

    IntroductionPermanent link for this heading

    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 passwordPermanent link for this heading

    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 userPermanent link for this heading

    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 rolesPermanent link for this heading

    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 rolesPermanent link for this heading

    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 rolesPermanent link for this heading

    The following Mindbreeze InSpire roles are predefined by default:

    Role name

    Description

    Examples (selection)

    “InSpire Administrator”

    Access to MMC “Update” and “InSpire Global Settings“

    Installation of updates, container management

    “InSpire app.telemetry Administrator”

    Access to MMC “Reporting” (app.telemetry)

    Diagnostics, reading log files, reading feedback. Read and change diagostic configuration.

    “InSpire Application Impersonation“

    Authorizes the use of “Trusted Peer Authentication” in the client; see documentation: “Configuring Trusted Peer Authentication for Mindbreeze InSpire”

    Use “Trusted Peer Authentication” in the client, search on behalf of other users.

    “InSpire Config Administrator”

    Access to MMC “Configuration”

    Read and change Mindbreeze InSpire configuration

    “InSpire Index User”

    Access to the "filter" and "index" diagnostic servlets

    Index/filter status queries, detailed diagnostic options

    “InSpire Index Writer”

    Access for indexing documents

    Index or delete documents, filter documents, access for external connectors

    “InSpire Overview User”

    Basic access to the MMC "Search Experience".

    “InSpire Services Administrator”

    Access to MMC “Services”  

    Start/stop nodes, re-index

    “InSpire Webmin Administrator”

    Access to MMC “System”

    Download, upload and edit files, manage time zones

    “InSpire Vocabulary Administrator”

    Access to MMC „Synonyms, Replacements, Vocabulary“

    Edit Synonyme, Replacements and Vocabulary

    “InSpire Relevance Administrator”

    Access to Insight Apps, Query Boosting, Relevance

    Edit Relvance and Boosting

    “InSpire Resource Administrator”

    Combines the permissions of  InSpire Vocabulary Administrator and InSpire Relevance Administrator

    Description of the Keycloak administration rolesPermanent link for this heading

    The following Keycloak administration roles are predefined by default:

    Role name

    Description

    Examples (selection)

    “admin”

    Access to “Credentials”

    Create/delete users, change role assignments

    “create-realm”

    Not used

    “offline-access”

    Not used

    “uma_authorization”

    Not used

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

    Description of the app.telemetry rolesPermanent link for this heading

    The following app.telemetry roles are predefined by default:

    Role name

    Description

    Examples (selection)

    „Fabasoft app.telemetry Administrators”

    Full administrative access

    Configuration changes

    „Fabasoft app.telemetry Dashboard Users”

    Access only to public dashboards and thoses assigned to this group.

    „Fabasoft app.telemetry Logpool Users“

    Access only to reports and log pools assigned to this group.

    „Fabasoft app.telemetry Users”

    Read only acces to all app.telemetry data.

    „Fabasoft app.telemetry Web Form Users”

    Access to the feedback inbox, forms and website configuration

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

    CookiesPermanent link for this heading

    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.

    TLSPermanent link for this heading

    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 standardsPermanent link for this heading

    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 credentialsPermanent link for this heading

    Automatic backupPermanent link for this heading

    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 backupPermanent link for this heading

    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 backupPermanent link for this heading

    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/troubleshootingPermanent link for this heading

    Log FilesPermanent link for this heading

    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 when updating to version 20.4Permanent link for this heading

    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 when downgrading to version 19.0 - 20.3 / 20.4 / 20.5 / 21.2Permanent link for this heading

    When downgrading to versions 19.0 to 20.3, 20.4, 20.5 and 21.2, it is not possible to retain all Keycloak data. This applies to data such as additionally created clients (synchronized users, customized user role mappings).

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

    Error when downgrading from version 21.3 to 21.2 or olderPermanent link for this heading

    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.

    Download PDF

    • Configuration - Back-End Credentials

    Content

    • Introduction
    • Change password
    • Create a user
    • Managing roles
    • Standard roles
    • Cookies
    • TLS
    • Reset configuration to Mindbreeze standards
    • Backup and recovery of credentials

    Download PDF

    • Configuration - Back-End Credentials