Home
Home
German Version
Support
Impressum
25.2 Release ►

Start Chat with Collection

    Main Navigation

    • Preparation
      • Connectors
      • Create an InSpire VM on Hyper-V
      • Initial Startup for G7 appliances
      • Setup InSpire G7 primary and Standby Appliances
    • Datasources
      • Configuration - Atlassian Confluence Connector
      • Configuration - Best Bets Connector
      • Configuration - Box 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 - 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 Loop Connector
      • Configuration - Microsoft Project Connector
      • Configuration - Microsoft SharePoint Connector
      • Configuration - Microsoft SharePoint Online Connector
      • Configuration - Microsoft Stream Connector
      • Configuration - Microsoft Teams Connector
      • Configuration - Salesforce Connector
      • Configuration - SCIM Principal Resolution Service
      • Configuration - SemanticWeb Connector
      • Configuration - ServiceNow 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 - 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
      • Whitepaper - Web Connector - Setting Up Advanced Javascript Usecases
    • Configuration
      • CAS_Authentication
      • Configuration - Alerts
      • 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 - External Query Service
      • Configuration - Filter Plugins
      • Configuration - GSA Late Binding Authentication
      • Configuration - Identity Conversion Service - Replacement Conversion
      • Configuration - InceptionImageFilter
      • Configuration - Index-Servlets
      • Configuration - InSpire AI Chat and Insight Services for Retrieval Augmented Generation
      • 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 - Personalized Relevance
      • Configuration - Plugin Installation
      • Configuration - Principal Validation Plugin
      • Configuration - Profile
      • 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
      • JWT Authentication
      • Language detection - LanguageDetector Plugin
      • Mindbreeze Personalization
      • Mindbreeze Property Expression Language
      • Mindbreeze Query Expression Transformation
      • SAML-based Authentication
      • Trusted Peer Authentication for Mindbreeze InSpire
      • Using the InSpire Snapshot for Development in a CI_CD Scenario
      • Whitepaper - AI Chat
      • Whitepaper - Create a Google Compute Cloud Virtual Machine InSpire Appliance
      • Whitepaper - Create a Microsoft Azure Virtual Machine InSpire Appliance
      • Whitepaper - Create AWS 10M InSpire Appliance
      • Whitepaper - Create AWS 1M InSpire Appliance
      • Whitepaper - Create AWS 2M InSpire Appliance
      • Whitepaper - Create Oracle Cloud 10M InSpire Application
      • Whitepaper - Create Oracle Cloud 1M InSpire Application
      • Whitepaper - MMC_ Services
      • Whitepaper - Natural Language Question Answering (NLQA)
      • Whitepaper - SSO with Microsoft AAD or AD FS
      • Whitepaper - Text Classification Insight Services
    • Operations
      • Adjusting the InSpire Host OpenSSH Settings - Set LoginGraceTime to 0 (Mitigation for CVE-2024-6387)
      • app.telemetry Statistics Regarding Search Queries
      • CIS Level 2 Hardening - Setting SELinux to Enforcing mode
      • 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
      • Provision of app.telemetry Information on G7 Appliances via SNMPv3
      • Restoring to As-Delivered Condition
      • Whitepaper - Administration of Insight Services for Retrieval Augmented Generation
    • User Manual
      • Browser Extension
      • Cheat Sheet
      • iOS App
      • Keyboard Operation
    • SDK
      • api.chat.v1beta.generate Interface Description
      • 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 a Query Expression Transformer
      • Development of Insight Apps
      • Embedding the Insight App Designer
      • Java API Interface Description
      • OpenAPI 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
      • Release Notes 22.2 Release - Mindbreeze InSpire
      • Release Notes 22.3 Release - Mindbreeze InSpire
      • Release Notes 23.1 Release - Mindbreeze InSpire
      • Release Notes 23.2 Release - Mindbreeze InSpire
      • Release Notes 23.3 Release - Mindbreeze InSpire
      • Release Notes 23.4 Release - Mindbreeze InSpire
      • Release Notes 23.5 Release - Mindbreeze InSpire
      • Release Notes 23.6 Release - Mindbreeze InSpire
      • Release Notes 23.7 Release - Mindbreeze InSpire
      • Release Notes 24.1 Release - Mindbreeze InSpire
      • Release Notes 24.2 Release - Mindbreeze InSpire
      • Release Notes 24.3 Release - Mindbreeze InSpire
      • Release Notes 24.4 Release - Mindbreeze InSpire
      • Release Notes 24.5 Release - Mindbreeze InSpire
      • Release Notes 24.6 Release - Mindbreeze InSpire
      • Release Notes 24.7 Release - Mindbreeze InSpire
      • Release Notes 24.8 Release - Mindbreeze InSpire
      • Release Notes 25.1 Release - Mindbreeze InSpire
      • Release Notes 25.2 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

    Installation and Configuration
    Caching Principal Resolution Service

    IntroductionPermanent link for this heading

    This documentation contains basic information about the configuration and management of Caching Principal Resolution Services. You will find a general explanation of the terms and functions, an example configuration, a list of general settings, a description of how to carry out monitoring with app.telemetry, as well as troubleshooting and use case examples.

    The information in this documentation applies to all Caching Principal Resolution Services. If specific information is required for a data source, you can find this in the corresponding documentation. A list of all supported data sources, including references to the respective documentation, can be found in the chapter Supported data sources.

    Hint: The terms "Caching Principal Resolution Service" and "Principal Resolution Service" are used synonymously in this document and have therefore the same meaning.

    What are principals?Permanent link for this heading

    A "principal" is a central concept in Mindbreeze that represents different types of entities. These entities can be users, groups, roles or data source-specific authorisation concepts. Principals are used for the uniform administration and identification of these entities in different authorisation systems.

    Example:

    • A user name like "David Porter" or an e-mail address like "david.porter@mindbreeze.com" can be regarded as a principal. The same user can have several aliases thus several representations.
    • Groups and roles such as "Mindbreeze employee" or "Mindbreeze Invoicing" are also referred to as principals.
    • Data source-specific authorisation concepts are also principals. For example, the list of all users with read authorisation for a Microsoft Sharepoint site is also saved as a principal.

    Why is a Principal Resolution Service needed?Permanent link for this heading

    When a user logs in to a Mindbreeze Client Service, only the user's login information is known. To determine the associated aliases, roles and groups of the user, it is necessary to obtain this information from the respective data source.

    With a Caching Principal Resolution Service, all users and their aliases, roles and groups are downloaded from a data source and stored to resolve them efficiently at the time of the search.

    Functionality of the Caching Principal Resolution ServicePermanent link for this heading

    The Caching Principal Resolution Service has the task of resolving all principals of a logged in user in a search query. This is crucial to determine which documents this user can access according to their authorisations.

    Initialisation of the servicePermanent link for this heading

    Before the Caching Principal Resolution Service is ready for use, it must retrieve all principals (users, roles, groups, etc.) from a data source and store them in a cache. These are stored efficiently in the Caching Principal Resolution Service, which means that the resolution can take place in real time, even if millions of principals are stored in the cache.

    After initialisation, the cache is updated regularly. For information on how to configure the updating of the cache, see the chapter Cache Update Settings.

    Procedure at the time of the searchPermanent link for this heading

    The following process illustrates in a simplified form the essential steps that are performed at the time of the search:

    1. A search is started and the principals (login information) of the searching user "David Porter" are sent to the Mindbreeze Index.
    2. The principals of David Porter are forwarded to the Principal Resolution Service.
    3. The Principal Resolution Service resolves the associated principals of "David Porter".
    4. The ACLs (Access Control List) of the documents are compared with the resolved principals of David Porter.
    5. Finally, David Porter only sees the documents in the search result to which he is authorised to have access.

    Supported data sourcesPermanent link for this heading

    Each data source has at least one supported Principal Resolution Service. Below you will find a list of supported data sources and the link to the corresponding documentation:

    Data source

    Service

    Atlassian Confluence

    CachingConfluencePrincipalResolutionService

    Box Connector

    Box Principal Resolution Service

    COYO Connector

    COYO Principal Resolution Service

    Documentum Connector

    Documentum Principal Resolution

    Dropbox Connector

    Dropbox Principal Resolution Service

    Google Drive Connector

    Google Drive Principal Resolution Service

    IBM Lotus Connector

    CachingIBMLotusNotesPrincipalResolutionService

    Jira Connector

    Atlassian Jira Caching Principal Resolution Service

    LDAP Connector

    • CachingLdapPrincipalResolution
    • CachingNovellLdapPrincipalResolution

    Microsoft Azure PRS

    Microsoft Azure Principal Resolution Service

    Microsoft Dynamics CRM Connector

    Microsoft Dynamics CRM Principal Resolution

    Microsoft Exchange Connector

    CachingLdapPrincipalResolution

    Microsoft File Connector

    CachingLdapPrincipalResolution

    Microsoft SharePoint Connector

    • CachingLdapPrincipalResolution
    • SharepointPrincipalCache
    • SharepointACLReferenceCache

    Microsoft SharePoint Online Connector

    • SharepointOnlinePrincipalCache
    • Microsoft Azure Principal Resolution Service

    Microsoft Stream Connector

    Microsoft Azure Principal Resolution Service

    Microsoft Teams Connector

    Microsoft Azure Principal Resolution Service

    Novell Directory Service

    CachingNovellLdapPrincipalResolution

    Salesforce Connector

    Salesforce Principal Resolution Service

    ServiceNow Connector

    CachingServiceNowPrincipalResolutionService

    Yammer Connector

    YammerPrincipalResolutionService

    Basic configurationPermanent link for this heading

    PreparationPermanent link for this heading

    Selecting the correct Caching Principal Resolution Service:

    In the chapter Supported data sources you will find a detailed list of data sources with the respective Caching Principal Resolution Services and the reference to the corresponding documentation.

    In some cases, several Principal Resolution Services can be selected for a single data source. If this is the case, please note the following points:

    • Identify the identity sources or directory services used in your organisation for each data source in order to select the appropriate Principal Resolution Service.
      • For example, LDAP is often used for the company-wide single sign-on (SSO) registration. A CachingLdapPrincipalResolution Service should be used here, if available.
    • If relevant principals for documents from a specific data source are distributed across different sources, a parent/child configuration of the services is necessary. This configuration links the services together. For more information on parent/child configurations, see the chapter Parent/child cache - resolution of principals from multiple data sources.
      • An example of this is Microsoft Sharepoint Online, where information of the principal can be found in the respective Sharepoint Online sites and on the Microsoft Azure platform.

    Preparation of the data source:

    Basically, it is necessary to create the required login information (credentials) in the data source. A user with read authorisation for all users, roles, groups etc. is usually required. The following must be noted:

    • Carry out the specific preparation steps according to the documentation of the respective Principal Resolution Service.
    • If a connector has already been configured for the data source, it may be possible to use the same credentials for the Principal Resolution Service.

    Preparation of the network configuration:

    For some data sources, it is necessary to edit the global network configuration in the Mindbreeze Appliance. The following must be noted:

    • Carry out the specific preparation steps according to the documentation of the respective Principal Resolution Service.
    • Gather information about the specific infrastructure of the organisation, including firewall and proxy settings, to ensure a configuration without problems.

    Overview of the configuration stepsPermanent link for this heading

    The basic configuration of a Principal Resolution Service involves the following steps in the Mindbreeze Management Center:

    1. Creation of a suitable Principal Resolution Service for the selected data source.
    2. Configuration of the login data (credentials) for the data source. Depending on the data source, the credentials can be configured in two ways:
      • Creating and assigning a Mindbreeze credential object with the login data.
      • Direct entry of the credentials in the configuration of the Principal Resolution Service.
    3. Assignment of the created Principal Resolution Service to the used index.

    In the following chapter, these steps are demonstrated using an example configuration. There, a Principal Resolution Service for Microsoft Dynamics 365 is configured.

    Example configuration for Microsoft Dynamics 365 Permanent link for this heading

    This section describes the configuration of a Microsoft Dynamics CRM Principal Resolution Service for an index with a Microsoft Dynamics 365 data source. The following steps must be carried out:

    1. Carry out the preparation steps described in the Microsoft Dynamics CRM Principal Resolution documentation. Create a Microsoft Azure application with the necessary read authorizations.
    1. Open the Management Centre and then the menu item "Configuration" in the page navigation. Create a service in the "Indices" tab. Give the service a name in the setting "Display Name". In the context of this example, the display name is "Microsoft Dynamics 365 Principal Resolution Service".

    1. Select in the "Service" setting the option "Microsoft Dynamics 365 Principal Resolution Service"
    1. Switch to the "Network" tab and create a new Mindbreeze credential for OAuth2 authentication. Use the Microsoft Azure application that you created in step 1. In this case, a credential of the type "OAuth2" is required.

    1. Fill in the fields "Access Token URL", "Client ID" and "Client Secret" accordingly. Give the credential a suitable name like for example "Microsoft Dynamics 365 Oauth2 Credential".
    1. Switch back to the "Index" tab to configure the Principal Resolution Services credentials in the section "Connection Settings".
    1. First, enter the URL for "CRM URL" and "Organisational Service URL" of the Dynamics 365 instance. Select the credential "Microsoft Dynamics 365 OAuth2 Credential" created by you in step 4 as the "Credential". Also activate the setting "Is Microsoft Dynamics CRM Online".

    1. Configure the SharePoint Online connector in the "Indices" tab of the desired index in the section "Data Sources". Select the created service in the setting "Caching Principal Resolution Service". In this example, "Microsoft Dynamics 365 Principal Resolution Service" must be selected.

    1. Then save the changes by clicking on "Save".

    Once the Principal Resolution Service has been configured and connected to the index, you can check whether the cache has been set up successfully and the principals are resolved as expected. You can find more information on this in the following chapter Monitoring.

    Hint: As soon as the basic configuration has been completed, it is recommended that you also adjust the setting "Cache Update Interval" in the section "Cache Update Settings". This setting determines how often the principals of the Principal Resolution Services are updated. You can find more information on this in the chapters Cache Settings and Cache Update Settings.

    MonitoringPermanent link for this heading

    After configuring a caching principal resolution service, it is important to ensure that the cache has been successfully established and that the service works as expected. The build-up of the cache is started by default as soon as the configuration has been saved.

    The status and behaviour of the Caching Principal Resolution Service can be monitored via the app.telemetry Reporting Dashboard. It provides you with real-time information about the status of the build-up of the cache and the resolution of the principals.

    In addition, a REST API is available that is hosted by each Caching Principal Resolution Service. This API enables the monitoring and management of the service, including updating the cache, checking the cache content and analyzing the resolved principals.

    Monitoring and management with the REST API Permanent link for this heading

    This chapter explains how you can use the REST API to manage and monitor the caching principal resolution services. The API calls enable to:

    • Trigger a cache update
    • Query the current status of the build-up of the cache
    • Analyzing the resolved principals
    • Viewing the content of the cache
    • Export of the cache content

    Hint: Please note that a direct connection to the Mindbreeze appliance is required to use the REST API.

    API calls for status informationPermanent link for this heading

    URL

    Description

    https://search.myorganization.com:8443/cache/<Webservice Port>/info?key=cachedir

    Returns the currently used cache directory.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=printstacktraces

    Returns the current status of all threads.

    API calls for resolving the principalsPermanent link for this heading

    URL

    Description

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=checkprincipals&individualid=<userid>&timeoutms=<milliseconds>

    Returns principals with <userid> from the cache. <userid> should not be a "unified ID".

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=checkconsistency&individualid=<userid>&isunifiedid=false

    Checks whether the principals in the cache match the principals provided by the source. If "all" is used instead of <userid>, all users are checked.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=checkprincipals&individualid=“somestring“&aliasnameattribute=<attribute>&aliasname=<aliasname>&timeoutms=<milliseconds>  

    Returns principals with alias name. <aliasnameattribute> should be the configured "Identity Alias Name Property".

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=checkprincipals&individualid=“somestring“&isanonymous=true&timeoutms=<milliseconds>

    Returns principals of anonymous users.

    API calls for cache contentPermanent link for this heading

    URL

    Description

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=export&path=/data/tmp/export

    Exports all database tables in CSV format.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updateprincipalmembership&container=<container>&individuals=<individuals>

    A <individuals> list of individuals separated by semicolons (;).

    For example: user1;user2.

    API calls for managing the cachePermanent link for this heading

    URL

    Description

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache

    Updates all containers.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache&container=<containerid>&isunifiedid=false

    Updates only <containerid>.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache&partition=<partition>

    Updates only one partition.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache&scope=full

    Performs a complete update.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache&scope=clean

    Performs a cleanup and a complete update.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=cancelupdate

    Cancels a running update.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=reopencache&path=/data/newcache

    Reopens the cache in an empty directory. The cache should be updated after reopening.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=reset&aliasnames=true&partition=<partition>

    Resets the alias names of a partition.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=syncconsumers

    All configured consumer caches are synchronised.

    https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=setLogCacheUpdateCalls&value=true

    Activates debug logging for all calls made by the caching framework to get to the current state. Can be deactivated with "value=false".

    Monitoring with app.telemetryPermanent link for this heading

    You will find app.telemetry in the Management Centre in the page navigation under the menu item "Reporting". Click on "Reporting" and additional menu items will appear. Open the submenu item "Telemetry Details".

    You will be directed to the area "Applications". In the section "Mindbreeze" click on "Principal Resolution Service".

    Then, open "View Telemetry Data".

    Finally, you are now in the section "Software telemetry". Here you can view and analyze various aspects of the created cache. For example, you can query the status of the cache, check if errors have occurred, view the duration of the build-up of the cache, check when the last cache update was performed and other aspects.

    Hint: If certain information is not displayed, the configuration of the columns could be helpful. To do this, open "Columns" at the bottom left. There you can select which columns should be displayed. It is recommended to select the columns "Start Time", "Duration", "Running", "Service", "Agent" and "Errors".

    List of general settingsPermanent link for this heading

    This chapter describes all the settings that can be configured for each Caching Principal Resolution Service. If there are any differences, these are explained in the individual documentation for the respective Caching Principal Resolution Service.

    Cache settingsPermanent link for this heading

    In the section "Cache Settings", the properties of the cache can be customized, including the definition of the database path. Please note that this configuration is optional.

    Setting

    Description

    Example/Default setting

    Identity Encryption Credential

    This setting can be used to display the user identity in encrypted form in the app.telemetry.

    Example:

    Credential123

    Cache In Memory Items Size

    Number of items stored in the cache. Depends on the available memory of the JVM.

    Default setting:

    60000

    Database Directory Path

    Defines the directory path for the cache.

    If a Mindbreeze Enterprise product is used, a path must be set. If a Mindbreeze InSpire product is used, the path does not need to be set.

    If the directory path is not defined, under Linux the following path is defined: /data/currentservices/<server name>/data.

    Example:

    /data/principal_resolution_cache

    Group Members Resolution And Inversion Threads

    This setting determines the number of threads that resolve group members in parallel and invert these groups. Values less than 1 are assumed to be 1.

    Default setting:

    1

    In-Memory Containers Inversion Threshold (Advanced Setting)

    This setting determines the maximum number of groups. If this number is exceeded, further RAM memory consumption by using hard disks during inversion is avoided.

    Default setting:

    1000000

    Cache Update SettingsPermanent link for this heading

    In the section "Cache Update Settings", the structure of the cache and the frequency of the cache update can be configured.

    Setting

    Description

    Example/Default setting

    Cache Update Interval (Minutes)

    This setting determines (in minutes) when the cache should be updated.

    Is the value less than or equal to 0, the cache update is deactivated.

    When the service is started, the last (persisted) cache update time is considered. This means that for example the cache is not necessarily updated when the service is stopped or started, but only at the next time interval.

    Default setting:

    60

    Readonly

    (Advanced Setting)

    An advanced setting that should only be used for producer consumer configurations. This setting should be activated for consumer caches if the setting "Readonly on Consumer" is activated in the producer cache.

    See Installation and Configuration - Caching Principal Resolution Service - Producer-Consumer Services.

    Default setting:

    Deactivated

    Delete old cache after update

    This setting decides whether the old cache data should be deleted after each update.

    If this setting is deactivated, old cache data is no longer deleted and therefore accumulates on the storage device. Enabling this setting is therefore recommended. Deactivating this setting can be used for debugging or if this is required by Mindbreeze Support.

    Default setting:

    Activated

    Backup cache before cleaning

    If this setting is selected, a copy of the cache is created in the directory /data/currentservice/<Service Name>/temp/<timestamp>_backup before the cleanup.

    This setting is related to the two settings "Clean Cache Update Schedule" and "Clean Cache after each N updates". If these settings are configured, a backup is also created with every update. If these settings are not configured, no backup is created with the update.

    Default setting:

    Deactivated

    Clean Cache Update Schedule

    In this field, you can configure the cleanup and update of the cache using extended CRON expressions at specific times (for documentation and examples of CRON expressions, see Documentation - Mindbreeze InSpire - Extended cron expressions).

    This setting must be configured so that a backup is also created with every update. See setting "Backup cache before cleaning".

    Example:

    # Examples (daily at 23:00 and weekend at 08:00):

          # 0 0 23 * * ?

          # 0 0 8 ? * SAT,SUN

    Clean Cache after each N updates

    A number of updates (N) is specified in this field.  If this number is exceeded, the cache is deleted and rebuilt.

    This setting must be configured so that a backup is also created for each update. See setting "Backup cache before cleaning".

    Default setting:

    1

    Retry Update Cache Run If Was Incomplete In (Minutes)

    This setting determines (in minutes) when the cache should perform a new update process if an update was incomplete.

    If the value is less than or equal to 0, the cache retry update is deactivated and incomplete caches could be generated.

    Default setting:

    30

    Health Check SettingsPermanent link for this heading

    Health checks are configured in the section "Health Check Settings". With a health check the availability of the Caching Principal Resolution Service is checked automatically. If connection issues are detected, the service will be restarted. A health check network request is sent to the service for this purpose. If no response is received from the service within the specified timeout, it will be recognised as an error. This process is repeated until the maximum number of errors has been exceeded or a response is received within the timeout. If the maximum number of errors is exceeded, the Caching Principal Resolution Service is automatically restarted.

    Setting

    Description

    Example/Default setting

    Health Check Interval (Minutes)

    This setting specifies the time interval in minutes in which a health check is to be carried out.

    Default setting:

    1

    Health Check max. Retries On Failure

    This setting specifies how often the health check is repeated if it was not successful.

    Default setting:

    30

    Health Check Request Timeout (ms)

    If the number of repetitions specified here is exceeded, the Caching Principal Resolution Service is restarted.

    Default setting:

    2000

    Service SettingsPermanent link for this heading

    The behaviour of the Principal Resolution Service as an independent service and the communication with other services is configured in the section "Service Settings".

    Setting

    Description

    Example/Default setting

    Webservice Port

    This setting specifies the port where the service is available. If several Principal Resolution Services are configured, it must be ensured that different ports are used and available.

    Example:

    23900

    Identity Alias Name Property

    This setting enables to use properties of the identity to search for principals in the cache. The property name supplied by the authentication should be entered.

    This setting is used, for example, in SAML authentication to specify a property of the identity as username.

    Example:

    mail

    Lowercase Principals

    With this setting, the principals supplied by the cache are written in lower case. This should be activated if the connector delivers principals in lower case.

    Attention: This setting is activated by default, as this is necessary for most data sources and prevents potential problems when processing the principals. This setting should only be deactivated if you know how the principals are output from the data source and what effect this will have on the processing of the principals.

    Default setting:

    Activated

    Preserve Case for Principals Matching Pattern

    This setting allows certain principals (defined by regex patterns) to be retained in their original format (not lower-case).

    Example:

    ^[a-z]+[A-Z][a-z]*$

    This pattern matches all principals written in Camelcase that contain two words, such as "johnSmith", "aliceJohnson".

    Case Insensitive Member Resolution

    This setting determines whether users are checked regardless of upper or lower case. The necessity of this setting depends on the data source.

    Default setting:

    Activated

    Exclude Principals Pattern

    This setting enables to remove certain principals for all users from their principals list

    Example:

    .*_admin.*

    Suppress Anonymous Users Principals

    This setting enables, for example, to suppress the principal "Everyone" for anonymous users. This also prevents anonymous users from finding public documents.

    Default setting:

    Deactivated

    Suppress External Service Calls

    This setting prevents external services such as LDAP from being able to query which user groups are not in the cache during the search.

    Default setting:

    Activated

    Resolve non-anonymous principal to all registered users.

    This setting determines whether "normal" or non-anonymous users belong to the group that contains all users.

    For example, it is used for the Active Directory group "everyone", which contains all users. Another use case is when users without an account have access to documents that are accessible to all registered users. In this case, a decision is made as to whether the user is added to the "all registered users" group.

    Default setting:

    Activated

    Parent Cache SettingsPermanent link for this heading

    Parent/child configurations can be created in the section "Parent Cache Settings". A parent cache is used to link two or more Principal Resolution Services with each other. This is necessary if the relevant principals for documents from a specific data source are distributed in different sources. A practical example of this can be found in the chapter Use cases.

    Setting

    Description

    Example/Default setting

    Use Parent Principals Cache Service

    If this setting is activated, the group memberships from the parent cache are calculated first and its results are delivered to the child cache. This allows the current cache to use the results of the parent cache for lookup.

    Default setting:

    Deactivated

    Parent Principals Cache Service Port

    The port used for the setting "Use Parent Principals Cache Service", if it is activated.

    Example:

    23902

    Parent Cache Principals Include Patterns

    In this setting, principals can be included from the parent cache based on regex patterns. If the principal matches with at least one pattern line, it is included. If this field is empty, all principals from the parent cache are included. Upper and lower case is not taken into account.

    The principles in " Parent Cache Principals Exclude Patterns " take precedence over the principles in " Parent Cache Principals Include Patterns ".

    Example:

    ^[a-zA-Z]+\\.[a-zA-Z]+@mindbreeze\\.com$

    This pattern matches all email addresses that end in "@mindbreeze.com" and otherwise consist of lowercase letters and a dot. For example max.mustermann@mindbreeze.com .

    Parent Cache Principals Exclude Patterns

    In this setting, principals can be excluded from the parent cache based on regex patterns. If the principal matches with at least one pattern line, it is excluded. Upper and lower case is not taken into account.

    The principles in " Parent Cache Principals Exclude Patterns" take precedence over the principles in " Parent Cache Principals Include Patterns".

    Example:

    .*_admin.*

    Producer Consumer ServicesPermanent link for this heading

    Mindbreeze InSpire can be operated with dedicated producer and consumer nodes. The producer node is responsible for the preparation by building the index, crawling and collecting the groups. Once the producer node is finished with the preparation, the Principal Resolution Service data is copied and the consumer node is updated with it.

    The consumer node is queried in the query service and updated by the producer node. If the producer node is updated, it automatically causes the consumer node to be updated.

    For more information on producer and consumer nodes, see the documentation Handbook - Distributed Operation (G7) - Introduction.

    The following explains how to configure the cache of the producer node and the consumer node.

    Producer cachePermanent link for this heading

    Click in the Producer Node (= created service) in the "Indices" tab in the section "Consumer Services" on "Add Property". Then configure the following settings:

    Setting

    Description

    Example/Default setting

    Readonly on Consumer

    This setting should only be activated on producer nodes of Mindbreeze InSpire environments with producer and consumer nodes. Local updates on all consumer nodes are deactivated. If consumer base URLs are configured, only these configured consumers are updated via remote access.

    Explicit configuration is not recommended in some situations where the producer or consumer nodes are deactivated or given a different role. In such cases, it is sufficient to only activate this setting on the producer node, as the consumer nodes are calculated automatically.

    Default setting:

    Deactivated

    Disable

    Deactivates the updating of the remote cache.

    Default setting:

    Deactivated

    Base URL

    The URL to the Mindbreeze Management Center of the Mindbreeze InSpire consumer appliance.

    Example:

    https://myhost.myorganization.com:8443

    Realm

    The target realm of the consumer appliance. The default is "master".

    Attention: When using Windows, it is not necessary to specify a realm as this is specified by the base URL.

    Default setting:

    master

    Service Port

    The port of the Caching Principal Resolution Service on the Mindbreeze InSpire appliance.

    Attention: When using Windows, the service port must remain empty, as the port should contain the base URL.

    Example:

    23900

    Consumer cachePermanent link for this heading

    If the setting "Readonly on Consumer" is configured on the producer node in a Mindbreeze InSpire environment with producer and consumer nodes, local cache updates on consumer nodes are deactivated. In the case of other environments, the setting "Readonly" must be selected manually in the “Cache Update Settings” in the consumer cache as displayed in the screenshot below. No further configuration is required. The consumer cache is automatically synchronised after each update in the producer cache.

    Use casesPermanent link for this heading

    Parent/Child Cache - resolution of principals from multiple data sourcesPermanent link for this heading

    Parent and Child Principal Resolution Services are required if the relevant principals for documents from a specific data source are distributed in different sources. An example of this is Microsoft Sharepoint Online, where principal information can be found in the respective Sharepoint Online sites and on the Microsoft Azure platform.

    The Parent/Child Configuration makes it possible to combine data from different Principal Resolution Services without duplicating the data or giving up the autonomy of the parent cache.

    Procedure for the resolution of principals with Parent/Child Service:

    The resolution of principals by the Parent/Child Service follows a defined process:

    1. Forwarding to the Parent Cache by the Child Service:
      • The Child Service forwards all received principals to the Parent Cache before resolving the principal.
    2. Resolution by the Parent Service:
      • The Parent Service resolves all principals known to it and sends them back to the Child Service.
    3. Final resolution by the Child Service:
      • Finally, the Child Service resolves all the principals it has received, so that the complete resolution is done.

    Selection of the Parent and Child Service:

    The decision which service should be the Parent Service or the Child Service can be made based on the following criteria:

    • Parent Service:
      • The Parent Service should have general principal information that is relevant for multiple data sources. This service can also be used for other Child Services and act independently as a Caching Principal Resolution Service.
      • Example: Microsoft Azure, LDAP.
    • Child Service:
      • The Child Service should have specific principal information that is relevant for a specific data source.
      • Example: Sharepoint Online, OpenText Documentum.

    General configurationPermanent link for this heading

    Configuration of the standalone Services:

    1. Configure all services independently, whereby the services each have their own data sources and settings. You can find more information about the configuration of a Principal Resolution Service in the chapter Basic configuration.
    2. After the configuration, ensure that the individual caches of the Principal Resolution Services have been set up and that the principals are resolved correctly. You can find more information on checking the cache and the resolution of the principals in the chapter Monitoring.

    Defining a Principal Resolution Service as a Parent Cache:

    To set the Parent/Child Configuration, the following steps must be carried out:

    1. Go to the section "Parent Cache Settings" in the child service.

    1. Activate the setting "Use Parent Principals Cache Service".
    2. Enter the "Webservice Port" of the Parent Service in the setting "Parent Principals Cache Service Port".
    3. Save the changes.

    Configuration in the index settings:

    Now the Child Principal Resolution Service must be assigned to the corresponding data source in your index.

    Configuration example with Microsoft SharePoint OnlinePermanent link for this heading

    Microsoft SharePoint Online is an example of a data source that requires a Parent/Child Configuration. The principal information that is relevant for this data source is located on the respective SharePoint Online sites and also on the Microsoft Azure platform.

    To ensure the correct resolution of the principals that are relevant for SharePoint Online, it is necessary to link all principals from both sources with a Parent/Child Configuration.

    Hint: If the creation of credentials is also required, you will find the necessary information in the documentation Configuration - Microsoft SharePoint Online Connector - Configuration credentials and endpoints and Configuration - Microsoft Azure Principal Resolution Service - Configuring the Microsoft Azure Principal Resolution Service.

    The creation of the Parent/Child Configuration is carried out as follows:

    1. Creation of an index and crawler

    Create a new index if no index exists yet. Select "Microsoft SharePoint Online" as the data source. In this example, the index name is "Microsoft SharePoint Online Index".

    1. Creation of the Parent Service for Microsoft SharePoint Online

    Create a new Caching Principal Resolution Service and in the setting "Service” click "Add Service" and select the option "SharepointOnlinePrincipalCache". Give the cache a name such as "Microsoft SharePoint Online Cache".

    1. Configuration of the Webservice Port for the Microsoft SharePoint Online Principal Resolution Service

    Enter a web service port in the "Service Settings" section of the Principal Resolution Services. The availability of this port is important, otherwise the service will not work. In this example, port "23901" is used.

    1. Creation of the Principal Resolution Service for Microsoft Azure

    Now create a second Caching Principal Resolution Service for Microsoft Azure. Select in "Service", the option "Microsoft Azure Principal Resolution Service". Give the service a name such as "Microsoft Azure Cache".

    1. Configuration of the Webservice Port for the Microsoft Azure Principal Resolution Service

    Specify a "Webservice Port" for the Microsoft Azure Caching Principal Resolution Service. In this example, the port "23902" is used.

    1. Definition of the Parent Cache and the Child Cache for the resolution of the principals

    The Microsoft Azure Principal Resolution Service is defined as the Parent Service and the Microsoft SharePoint Online Principal Resolution Service is defined as the Child Service. The reasons for this are:

    • The Microsoft Azure Principal Resolution Service provides common principal information for multiple data sources. So this must be the Parent Service.
    • The Microsoft SharePoint Online Principal Resolution Service provides specific principal information for SharePoint Online only. This must therefore be the Child Service.
    1. Configuring the service as the Child Service

    Open the "Microsoft SharePoint Online Cache" and enter the port of the "Microsoft Azure Cache" in the section "Parent Cache Settings in the setting "Parent Principals Cache Service Port". In this example, the port "23902" is required.

    1. Linking the Microsoft SharePoint Online Principal Resolution Service with the index

    Open the index and in the "Data Sources" section go to the setting "Caching Principal Resolution Service". Then select the corresponding service. In this example, "Microsoft SharePoint Online Cache" must be selected.

    1. Finalising the configuration

    Finally, save the configuration to finalise the creation of the Parent/Child configuration.

    Using (LDAP/SAML) identity attributes to resolve principals Permanent link for this heading

    What is a Mindbreeze Identity Object?

    When a user logs into a search application, the user information is saved in the form of a Mindbreeze Identity Object. When this user starts a search, this Identity Object is forwarded to the Principal Resolution Service to resolve the principals.

    What are Identity Attributes?

    Depending on the authentication system used, identity objects can contain optional attributes. For example, if LDAP is used for single sign-on authentication in your search application, all LDAP attributes supplied are automatically adopted as identity attributes. The same applies to the use of SAML authentication with the corresponding SAML attributes.

    Default Behaviour when Resolving Principals

    By default, only the user name (and all known aliases) of the logged-in user is used to resolve the principals in a Principal Resolution Service. The identity attributes are ignored. For example, if your data source uses email addresses to identify users, resolving the principals based on the user name alone will not provide any results.

    Configuration for Identity Attributes for Resolving Principals

    To solve this problem, the identity attribute, in this case the email address, must be marked as an alias for the Principal Resolution Service. This ensures that the value of this attribute is considered for the resolution of the principal. This can be done with the setting "Identity Alias Name Property" in the section "Service Settings".

    Configuration example for Microsoft Azure/SAML authentication with Box as data sourcePermanent link for this heading

    In this example, we look at the data source Box. It uses email addresses to identify users.

    The Mindbreeze Search Client is configured to use SAML-based Sign-On via Microsoft Azure (Entra) using the Microsoft Azure Principal Resolution Service.

    Example SAML Claims Configuration in Microsoft Azure (Entra):

    Since Box identifies users with e-mail addresses, using only the username in the resolution of the principals is insufficient. Without further configuration, our searching users can therefore not find any results.

    Configuration

    For the necessary configuration, the identity attribute matching the Microsoft Azure Claim Name "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" must be marked as an alias.

    This can be done in the "Service Settings" in the setting "Identity Alias Name Property" of the Principal Resolution Services (see screenshot). This attribute is provided by Microsoft Azure and is forwarded to the Mindbreeze Search Client as a SAML attribute during the SSO login.

    Result

    With this configuration, the "Microsoft Azure Principal Resolution Service" should now be able to successfully identify all users by their email addresses and resolve the principals properly. The users should therefore now be able to search for Box documents without any problems.

    It is now possible to test whether the resolution of the principals works as expected. For more information on how to check the resolution of the principals, see the chapter Monitoring.

    Exclusion of principals with extensive rightsPermanent link for this heading

    In some cases, certain principals have very extensive rights in a system. This grants them access to a lot of data and resources. Whic can represent a potential security risk. To minimise this risk and ensure data security, such principals can be excluded from the Principal Resolution Service as a preventative measure.

    Configuration example for the exclusion of principals according to a specific patternPermanent link for this heading

    Assume that all principals whose names end with "_admin" are to be excluded. Such names often characterise users with very extensive rights who potentially have unrestricted access to data and resources.

    Configuration

    To achieve this, the setting "Exclude Principals Pattern" must be configured with a regex pattern. The regex pattern removes all principals with the ending "_admin" from the Principal Resolution Service.

    The required regex pattern in this case is

    .*_admin.*

    After configuration, the changes must be saved in the Principal Resolution Service.

    Result

    This configuration excludes all principals that end with "_admin" and may have very far-reaching rights from the Principal Resolution Service. This minimises the security risk and ensures that users with such rights do not have unrestricted access to all files and data.

    TroubleshootingPermanent link for this heading

    Troubleshooting differences between upper and lower case spelling of principalsPermanent link for this heading

    Differences in the upper and lower case spelling of principals can mean that the resolution of users does not work as expected or that the resolved principals do not correspond to the upper and lower case spelling of the document ACLs.

    Case 1: The resolved principals do not correspond to the document ACLsPermanent link for this heading

    Such a case could look as follows:

    • Document ACLs: sales, marketing.
    • Stored principals in the Principal Resolution Service: SALES, MARKETING.

    Solution:

    In the section "Service Settings", the setting "Lowercase Principals" must be activated for the Principal Resolution Service. This setting enables the conversion of all principals to lowercase, regardless of their original spelling.

    Case 2: Principals of logged-in users are not resolvedPermanent link for this heading

    Such a case could look like this:

    • User credentials: "david porter".
    • Stored principals in the Principal Resolution Service: "David Porter", "David.Porter", “david.porter@mindbreeze.com”.

    Solution 1:

    In the section "Service Settings", the setting "Lowercase Principals" must be activated for the Principal Resolution Service. This setting enables the conversion of all principals to lowercase, regardless of their original spelling.

    Attention: Activating this setting only solves the problem if the login information is in lowercase.

    Solution 2:

    Alternatively, the setting "Case Insensitive Member Resolution" for the Principal Resolution Service can be activated in the section "Service Settings". This setting enables the correct resolution of principals, regardless of upper and lower case.

    Download PDF

    • Installation & Configuration - Caching Principal Resolution Service

    Content

    • Introduction
    • Supported data sources
    • Basic configuration
    • Monitoring
    • List of general settings
    • Use cases
    • Troubleshooting

    Download PDF

    • Installation & Configuration - Caching Principal Resolution Service