Sure, you can handle it. But should you?
Let our experts manage the tech maintenance while you focus on your business.
Let our experts manage the tech maintenance while you focus on your business.
Installation und Konfiguration
Caching Principal Resolution Service
Einführung
Diese Dokumentation beinhaltet grundlegende Informationen zur Konfiguration und Verwaltung von Caching Principal Resolution Services. Dabei erwartet Sie eine allgemeine Erklärung der Begriffe und Funktionen, eine Beispielkonfiguration, eine Liste an allgemeinen Einstellungen, eine Beschreibung zur Durchführung des Monitoring mit app.telemetry, als auch Troubleshooting- und Anwendungsbeispiele.
Die Informationen in dieser Dokumentation gelten für alle Caching Principal Resolution Services. Falls Informationen spezifisch für eine Datenquelle benötigt werden, können Sie diese in der zugehörigen Dokumentation finden. Eine Liste aller unterstützen Datenquellen inklusive Verweise auf die jeweilige Dokumentation, finden Sie im Kapitel Unterstützte Datenquellen.
Hinweis: Die Begriffe „Caching Principal Resolution Service“ und „Principal Resolution Service“ werden in diesem Dokument als Synonyme verwendet und sind somit gleichbedeutend.
Was sind Principals?
Ein "Principal" ist ein zentrales Konzept in Mindbreeze, das verschiedene Arten von Entitäten repräsentiert. Diese Entitäten können Nutzer, Gruppen, Rollen oder datenquellenspezifische Berechtigungskonzepte sein. Principals dienen zur einheitlichen Verwaltung und Identifizierung dieser Entitäten in unterschiedlichen Berechtigungssystemen.
Beispiel:
- Ein Nutzername wie "David Porter" oder eine E-Mail-Adresse wie "david.porter@mindbreeze.com" kann als Principal betrachtet werden. Dabei kann derselbe Nutzer mehrere Aliasnamen haben, also mehrere Repräsentationen.
- Ebenso werden Gruppen und Rollen, wie "Mindbreeze Mitarbeiter" oder "Mindbreeze Invoicing," als Principals bezeichnet.
- Auch datenquellenspezifische Berechtigungskonzepte sind Principals. Beispielsweise wird die Liste aller Nutzer mit Leseberechtigung für eine Microsoft Sharepoint Site auch als ein Principal gespeichert.
Warum wird ein Principal Resolution Service benötigt?
Wenn sich ein Nutzer in einem Mindbreeze Client Service anmeldet, sind nur die Anmeldeinformationen des Nutzers bekannt. Um die zugehörigen Aliase, Rollen und Gruppen des Nutzers zu bestimmen, ist es notwendig diese Informationen von der jeweiligen Datenquelle zu erhalten.
Mit einem Caching Principal Resolution Service werden alle Nutzer und deren Aliase, sowie Rollen und Gruppen aus einer Datenquelle heruntergeladen und gespeichert, um diese zur Suchzeit effizient aufzulösen.
Funktionalität des Caching Principal Resolution Service
Der Caching Principal Resolution Service hat die Aufgabe, alle Principals eines angemeldeten Nutzers bei einer Suchanfrage aufzulösen. Dies ist entscheidend, um festzustellen, auf welche Dokumente dieser Nutzer gemäß den Berechtigungen zugreifen kann.
Initialisierung des Services
Bevor der Caching Principal Resolution Service einsatzbereit ist, muss dieser alle Principals (Nutzer, Rollen, Gruppen etc.) aus einer Datenquelle abrufen und in einem Cache speichern. Diese werden im Caching Principal Resolution Service effizient gespeichert, wodurch die Auflösung in Echtzeit erfolgen kann, selbst wenn Millionen von Principals im Cache gespeichert sind.
Nach der Initialisierung wird der Cache regelmäßig aktualisiert. Für Informationen, wie man die Aktualisierung des Caches konfiguriert, siehe das Kapitel Cache Update Settings.
Ablauf zur Suchzeit
Der folgende Ablauf veranschaulicht in vereinfachter Form die wesentlichen Schritte die bei der Suchzeit durchlaufen werden:
- Eine Suche wird gestartet und die Principals (Anmeldeinformationen) des suchenden Nutzers „David Porter“ werden an den Mindbreeze Index gesendet.
- Die Principals von David Porter werden an den Principal Resolution Service weitergeleitet.
- Der Principal Resolution Service löst die zugehörigen Principals von „David Porter“ auf.
- Die ACLs (Access Control List) der Dokumente werden mit den aufgelösten Principals von David Porter verglichen.
- Schlussendlich sieht David Porter im Suchresultat nur die Dokumente, worauf er auch Zugriff haben darf.
Unterstützte Datenquellen
Jede Datenquelle hat mindestens einen unterstützten Principal Resolution Service.
Nachfolgend finden Sie eine Liste an unterstützten Datenquellen und die Verlinkung zur entsprechenden Dokumentation:
Service | |
Atlassian Confluence | |
Box Connector | |
COYO Connector | |
Documentum Connector | |
Dropbox Connector | |
Google Drive Connector | |
IBM Lotus Connector | |
Jira Connector | |
LDAP Connector | |
Microsoft Azure PRS | |
Microsoft Dynamics CRM Connector | |
Microsoft Exchange Connector | |
Microsoft File Connector | |
Microsoft SharePoint Connector | |
Microsoft SharePoint Online Connector | |
Microsoft Stream Connector | |
Microsoft Teams Connector | |
Novell Directory Service | |
Salesforce Connector | |
ServiceNow Connector | |
Yammer Connector |
Grundlegende Konfiguration
Vorbereitung
Auswahl des richtigen Caching Principal Resolution Service:
Im Kapitel Unterstützte Datenquellen finden Sie eine ausführliche Liste an Datenquellen mit den jeweiligen Caching Principal Resolution Services und dem Verweis auf die entsprechende Dokumentation.
In manchen Fällen können mehrere Principal Resolution Services für eine einzige Datenquelle ausgewählt werden. Ist dies der Fall, beachten Sie bitte folgende Punkte:
- Ermitteln Sie die Identitätsquellen oder Verzeichnisdienste, die in Ihrem Unternehmen für die jeweilige Datenquelle genutzt werden, um den passenden Principal Resolution Service auszuwählen.
- Beispielsweise wird LDAP häufig für die unternehmensweite Single-Sign-On Anmeldung (SSO) verwendet. Hierbei sollte ein CachingLdapPrincipalResolution Service eingesetzt werden, sofern verfügbar.
- Sollte es vorkommen, dass relevante Principals für Dokumente aus einer bestimmten Datenquelle auf verschiedene Quellen verteilt sind, ist eine Parent/Child Konfiguration der Services notwendig. Durch diese Konfiguration werden die Services miteinander verbunden. Für mehr Informationen über Parent/Child Konfigurationen, siehe das Kapitel Parent/Child Cache – Auflösung von Principals aus mehreren Datenquellen.
- Ein Beispiel dafür ist Microsoft Sharepoint Online, wo Principal-Informationen einerseits in den jeweiligen Sharepoint Online Sites und andererseits auf der Microsoft Azure Plattform zu finden sind.
Vorbereitung der Datenquelle:
Grundsätzlich ist es notwendig, die erforderlichen Anmeldeinformationen (Credentials) in der Datenquelle zu erstellen. Üblicherweise wird ein Nutzer mit Leseberechtigungen auf alle Nutzer, Rollen, Gruppen usw. benötigt. Dabei muss folgendes beachtet werden:
- Durchführung der spezifischen Vorbereitungsschritte entsprechend der Dokumentation des jeweiligen Principal Resolution Services.
- Falls ein Konnektor für die Datenquelle bereits konfiguriert wurde, können möglicherweise dieselben Credentials für den Principal Resolution Service genutzt werden.
Vorbereitung der Netzwerkkonfiguration:
Für einige Datenquellen ist das Bearbeiten der globalen Netzwerkkonfiguration in der Mindbreeze Appliance notwendig. Dabei muss folgendes beachtet werden:
- Durchführung der spezifischen Vorbereitungsschritte entsprechend der Dokumentation des jeweiligen Principal Resolution Services.
- Sammeln von Informationen über die spezifische Infrastruktur des Unternehmens, einschließlich Firewall- und Proxy-Einstellungen, um eine reibungslose Konfiguration sicherzustellen.
Überblick über die Konfigurationsschritte
Die grundsätzliche Konfiguration eines Principal Resolution Services beinhaltet die folgenden Schritte im Mindbreeze Management Center:
- Erstellung eines passenden Principal Resolution Service für die gewählte Datenquelle.
- Konfiguration der Anmeldedaten (Credentials) für die Datenquelle. Je nach Datenquelle kann die Konfiguration der Anmeldedaten auf zwei Arten erfolgen:
- Erstellung und Zuweisung eines Mindbreeze-Credential-Objekts mit den Anmeldedaten.
- Direkte Eingabe der Anmeldedaten in die Konfiguration des Principal Resolution Services.
- Zuweisung des erstellten Principal Resolution Service zum verwendeten Index.
Im folgenden Kapitel werden diese Schritte anhand einer Beispielkonfiguration demonstriert. Dabei wird ein Principal Resolution Service für Microsoft Dynamics 365 konfiguriert.
Beispielkonfiguration für Microsoft Dynamics 365
In diesem Kapitel wird die Konfiguration eines „Microsoft Dynamics CRM Principal Resolution“-Service für einen Index mit einer Microsoft Dynamics 365-Datenquelle beschrieben. Die folgenden Schritte müssen dafür ausgeführt werden:
- Führen Sie die Vorbereitungsschritte aus, die in der Dokumentation Microsoft Dynamics CRM Principal Resolution beschrieben werden. Erstellen Sie dabei eine Microsoft Azure Application mit den notwendigen Leseberechtigungen.
- Öffnen Sie das Management Center und dann den Menüpunkt „Configuration“ in der Seiten-Navigation. Erstellen Sie im „Indices“-Tab einen Service. Geben Sie dem Service einen Namen in der Einstellung „Display Name“. Im Kontext dieses Beispiels ist der Display Name „Microsoft Dynamics 365 Principal Resolution Service“.
- Wählen Sie unter „Service“ die Option „Microsoft Dynamics 365 Principal Resolution Service“ aus.
- Wechseln Sie zum „Network“-Tab und erstellen Sie ein neues Mindbreeze-Credential für die OAuth2-Authentifizierung. Verwenden Sie dabei die Microsoft Azure Application, die Sie in Schritt 1 erstellt haben. In diesem Fall wird ein Credential vom Typ „OAuth2“ benötigt.
- Füllen Sie die Felder „Access Token URL“, „Client ID“ und „Client Secret“ entsprechend aus. Geben Sie dem Credential einen passenden Namen wie z. B. „Microsoft Dynamics 365 Oauth2 Credential“.
- Wechseln Sie zurück zum „Index“-Tab, um die Anmeldeinformationen des Principal Resolution Services im Bereich „Connection Settings“ zu konfigurieren.
- Geben Sie als erstes die URL in "CRM URL" und "Organizational Service URL" der Dynamics 365 Instanz ein. Wählen Sie als „Credential“ das von Ihnen in Schritt 4 erstellte Credential „Microsoft Dynamics 365 OAuth2 Credential“ aus. Aktivieren Sie zusätzlich auch die Einstellung „Is Microsoft Dynamics CRM Online“.
- Konfigurieren Sie den SharePoint Online Konnektor im "Indices"-Tab des gewünschten Index im Abschnitt "Data Sources". Wählen Sie bei der Einstellung "Caching Principal Resolution Service" den erstellten Service aus. In diesem Beispiel muss "Microsoft Dynamics 365 Principal Resolution Service" ausgewählt werden.
- Speichern Sie anschließend die Änderungen durch das Klicken auf „Save“.
Nachdem der Principal Resolution Service konfiguriert und mit dem Index verbunden wurde, können Sie überprüfen, ob der Cache erfolgreich aufgebaut wurde und die Principals wie erwartet aufgelöst werden. Mehr Informationen dazu finden Sie im folgenden Kapitel Monitoring.
Hinweis: Sobald die grundlegende Konfiguration abgeschlossen ist, wird empfohlen, im Bereich „Cache Update Settings“ ebenfalls die Einstellung „Cache Update Interval“ anzupassen. Diese Einstellung bestimmt, wie häufig die Principals des Principal Resolution Services aktualisiert werden. Mehr Informationen dazu finden Sie in den Kapiteln Cache Settings und Cache Update Settings.
Monitoring
Nach der Konfiguration eines Caching Principal Resolution Services ist es wichtig sicherzustellen, dass der Cache erfolgreich aufgebaut wurde und der Service wie erwartet funktioniert. Der Cache-Aufbau wird standardmäßig gestartet, sobald die Konfiguration gespeichert wurde.
Der Status und das Verhalten des Caching Principal Resolution Services können über das app.telemetry Reporting Dashboard überwacht werden. Dadurch erhalten Sie Echtzeitinformationen über den Status des Cache-Aufbaus und über die Auflösung der Principals.
Zusätzlich steht eine REST-API zur Verfügung, die von jedem Caching Principal Resolution Service gehostet wird. Diese API ermöglicht die Überwachung und Verwaltung des Dienstes, einschließlich der Aktualisierung des Caches, der Überprüfung des Cache-Inhalts und der Analyse der aufgelösten Principals.
Monitoring und Verwaltung mithilfe der REST API
In diesem Kapitel wird erklärt, wie Sie die REST-API für die Verwaltung und Überwachung der Caching Principal Resolution Services nutzen können. Die API-Calls ermöglichen:
- Auslösen eines Cache-Updates
- Abfrage des aktuellen Zustandes des Cache-Aufbaus
- Analyse der aufgelösten Principals
- Einsicht in den Inhalt des Caches
- Export des Cache-Inhalts
Hinweis: Beachten Sie dabei, dass für die Verwendung der REST-API eine direkte Verbindung zur Mindbreeze-Appliance erforderlich ist.
API-Calls für Statusinformationen
URL | Beschreibung |
https://search.myorganization.com:8443/cache/<Webservice Port>/info?key=cachedir | Gibt das momentan verwendete Cache-Verzeichnis zurück. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=printstacktraces | Gibt den aktuellen Zustand von allen Threads aus. |
API-Calls zur Auflösung der Principals
URL | Beschreibung |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=checkprincipals&individualid=<userid>&timeoutms=<milliseconds> | Gibt Principals mit <userid> vom Cache zurück. <userid> sollte keine „unified ID“ sein. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=checkconsistency&individualid=<userid>&isunifiedid=false | Überprüft, ob die Principals im Cache mit den von der Quelle bereitgestellten Principals übereinstimmen. Wird „all“ anstelle von <userid> verwendet, werden alle Nutzer überprüft. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=checkprincipals&individualid=“somestring“&aliasnameattribute=<attribute>&aliasname=<aliasname>&timeoutms=<milliseconds> | Gibt Principals mit Aliasname zurück. <aliasnameattribute> sollte das konfigurierte “Identity Alias Name Property” sein. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=checkprincipals&individualid=“somestring“&isanonymous=true&timeoutms=<milliseconds> | Gibt Principals von anonymen Nutzern zurück. |
API-Calls für Cache-Inhalte
URL | Beschreibung |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=export&path=/data/tmp/export | Exportiert alle Datenbanktabellen im CSV-Format. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updateprincipalmembership&container=<container>&individuals=<individuals> | Eine <individuals> Liste von Individuen getrennt mit Strichpunkten (;). Zum Beispiel: user1;user2. |
API-Calls für die Verwaltung des Caches
URL | Beschreibung |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache | Aktualisiert alle Container. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache&container=<containerid>&isunifiedid=false | Aktualisiert nur <containerid>. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache&partition=<partition> | Aktualisiert nur eine Partition. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache&scope=full | Führt eine vollständige Aktualisierung durch. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=updatecache&scope=clean | Führt ein Cleanup und eine vollständige Aktualisierung durch. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=cancelupdate | Bricht eine laufende Aktualisierung ab. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=reopencache&path=/data/newcache | Öffnet den Cache wieder in einem leeren Verzeichnis. Der Cache sollte nach dem Wiederöffnen aktualisiert werden. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=reset&aliasnames=true&partition=<partition> | Setzt die Aliasnamen von einer Partition zurück. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=syncconsumers | Alle konfigurierten Consumer Caches werden synchronisiert. |
https://search.myorganization.com:8443/cache/<Webservice Port>/control?action=setLogCacheUpdateCalls&value=true | Aktiviert das Debug-Logging für alle Aufrufe, die das Caching-Framework tätigt, um in den aktuellen Zustand zu gelangen. Kann mit "value=false" deaktiviert werden. |
Monitoring mit app.telemetry
Sie finden app.telemetry im Management Center in der Seitennavigation unter dem Menüpunkt „Reporting“. Klicken Sie auf „Reporting“, wodurch weitere Menüpunkte erscheinen. Öffnen Sie den Untermenüpunkt „Telemetry Details“.
Sie werden zum Bereich „Applications“ weitergeleitet. Klicken Sie im Abschnitt „Mindbreeze“ auf den Punkt „Principal Resolution Service“.
Öffnen Sie danach „View Telemetry Data“.
Schlussendlich befinden Sie sich nun im Bereich „Software-Telemetry“. Hier können Sie verschiedene Aspekte des erstellten Cache betrachten und analysieren. Zum Beispiel können Sie den Status des Cache abfragen, nachsehen ob Fehler aufgetreten sind, die Dauer des Aufbaus des Caches betrachten, den Zeitpunkt des letzten Cache-Updates überprüfen und weitere Aspekte.
Hinweis: Falls gewisse Informationen nicht angezeigt werden, könnte die Konfiguration der Spalten aushelfen. Dafür muss „Columns“ links unten geöffnet werden. Dort können Sie auswählen, welche Spalten angezeigt werden sollen. Es wird empfohlen die Spalten „Start Time“, „Duration“, „Running“, „Service“, „Agent“ und „Errors“ auszuwählen.
Liste der allgemeinen Einstellungen
In diesem Kapitel werden alle Einstellungen beschrieben, die für jeden Caching Principal Resolution Service konfiguriert werden können. Bei möglichen Unterschieden, werde diese in den einzelnen Dokumentationen für den jeweiligen Caching Principal Resolution Service erläutert.
Cache Settings
Im Bereich „Cache Settings“ können die Eigenschaften des Caches angepasst werden, einschließlich der Festlegung des Datenbankpfades. Beachten Sie dabei, dass diese Konfiguration optional ist.
Einstellung | Beschreibung | Beispiel/Standardeinstellung |
Identity Encryption Credential | Mit dieser Einstellung kann man die Nutzeridentität verschlüsselt in der app.telemetry anzeigen lassen. | Beispiel: Credential123 |
Cache In Memory Items Size | Anzahl der im Cache aufbewahrten Items. Abhängig vom verfügbaren Speicherplatz der JVM. | Standardeinstellung: 60000 |
Database Directory Path | Definiert den Verzeichnispfad für den Cache. Falls man ein Mindbreeze Enterprise Produkt verwendet, muss ein Pfad gesetzt werden. Sollte ein Mindbreeze InSpire Produkt verwendet werden, muss der Pfad nicht gesetzt werden. Ist der Verzeichnispfad nicht definiert, wird unter Linux folgender Pfad definiert: /data/currentservices/<server name>/data. | Beispiel: /data/principal_resolution_cache |
Group Members Resolution And Inversion Threads | Diese Einstellung bestimmt die Anzahl der Threads, die parallel Gruppenmitglieder auflösen und diese Gruppen invertieren. Werte kleiner als 1 werden als 1 angenommen. | Standardeinstellung: 1 |
In-Memory Containers Inversion Threshold (Advanced Setting) | Diese Einstellung bestimmt die maximale Anzahl der Gruppen. Wird diese Anzahl überschritten, wird weiterer RAM Speicherverbrauch beim Invertieren durch die Verwendung von Festplatten vermieden. | Standardeinstellung: 1000000 |
Cache Update Settings
Im Bereich “Cache Update Settings” kann der Aufbau des Caches und die Häufigkeit des Cache-Updates konfiguriert werden.
Einstellung | Beschreibung | Beispiel/Standardeinstellung |
Cache Update Interval (Minutes) | Diese Einstellung bestimmt (in Minuten), wann der Cache aktualisiert werden soll. Ist der Wert unter oder gleich 0, wird das Cache Update deaktiviert. Beim Starten des Service wird die letzte (persistierte) Cache-Aktualisierungszeit berücksichtigt. Das bedeutet, dass der Cache z. B. nicht unbedingt aktualisiert wird, wenn der Service gestoppt oder gestartet wird, sondern erst beim nächsten Zeitintervall. | Standardeinstellung: 60 |
Readonly (Advanced Setting) | Eine fortgeschrittene Einstellung, die nur für Producer-Consumer-Konfigurationen verwendet werden soll. Diese Einstellung sollte bei Consumer-Caches aktiviert werden, wenn im Producer-Cache die Einstellung „Readonly on Consumer“ aktiviert ist. Siehe dazu Installation und Konfiguration - Caching Principal Resolution Service - Producer-Consumer Services. | Standardeinstellung: Deaktiviert |
Delete old cache after update | Diese Einstellung entscheidet, ob die alten Cache-Daten nach jedem Update gelöscht werden sollen. Ist diese Einstellung deaktiviert, werden alte Cache-Daten nicht mehr gelöscht und sammeln sich dadurch auf dem Speichergerät an. Daher wird die Aktivierung dieser Einstellung empfohlen. Die Deaktivierung dieser Einstellung kann für das Debugging verwendet werden oder wenn dies vom Mindbreeze Support gefordert wird. | Standardeinstellung: Aktiviert |
Backup cache before cleaning | Wenn diese Einstellung ausgewählt ist, wird vor dem Cleanup eine Kopie des Cache im Verzeichnis /data/currentservice/<Service Name>/temp/<Zeitstempel>_backup angelegt. Hierbei hängt diese Einstellung mit den zwei Einstellungen „Clean Cache Update Schedule“ und „Clean Cache after each N updates“ zusammen. Sind diese Einstellungen konfiguriert, so wird mit jedem Update auch ein Backup erstellt. Falls diese Einstellungen nicht konfiguriert sind, wird kein Backup mit dem Update erstellt. | Standardeinstellung: Deaktiviert |
Clean Cache Update Schedule | In diesem Feld kann man das Cleanup und Update vom Cache mithilfe von Extended CRON-Ausdrücken zu bestimmten Zeiten konfigurieren (für eine Dokumentation und Beispiele zu CRON-Ausdrücken, siehe Konfiguration - Mindbreeze InSpire - Extended Cron Ausrücke). Diese Einstellung muss konfiguriert werden, damit bei jedem Update auch ein Backup erstellt wird. Siehe Einstellung „Backup cache before cleaning“. | Beispiel: # Examples (daily at 23:00 and weekend at 08:00): # 0 0 23 * * ? # 0 0 8 ? * SAT,SUN |
Clean Cache after each N updates | In diesem Feld wird eine Anzahl an Aktualisierungen (N) angegeben. Wird diese Zahl überschritten, wird der Cache gelöscht und neu aufgebaut. Diese Einstellung muss konfiguriert werden, damit bei jedem Update auch ein Backup erstellt wird. Siehe Einstellung „Backup cache before cleaning“. | Standardeinstellung: 1 |
Retry Update Cache Run If Was Incomplete In (Minutes) | Diese Einstellung bestimmt (in Minuten), wann der Cache einen neuen Aktualisierungsprozess durchführen soll, falls eine Aktualisierung unvollständig war. Ist der Wert unter oder gleich 0, wird das Cache-Retry-Update deaktiviert und unvollständige Caches können erzeugt werden. | Standardeinstellung: 30 |
Health Check Settings
Im Bereich „Health Check Settings“ werden Health Checks konfiguriert. Durch einen Health Check wird automatisch die Verfügbarkeit des Caching Principal Resolution Service überprüft. Sollten Verbindungsprobleme festgestellt werden, wird der Dienst neugestartet. Dazu wird eine Health-Check-Netzwerkanfrage an den Service gesendet. Wenn innerhalb des angegebenen Timeouts keine Antwort vom Service kommt, wird dies als Fehler gewertet. Dieser Vorgang wird so lange wiederholt, bis die maximale Anzahl von Fehlern überschritten wurde oder eine Antwort innerhalb der Zeitüberschreitung eintrifft. Wird die maximale Anzahl von Fehlern überschritten, dann wird der Caching Principal Resolution Service automatisch neu gestartet.
Service Settings
Im Bereich „Service Settings“ wird das Verhalten des Principal Resolution Services als eigenständiger Service und die Kommunikation mit anderen Services konfiguriert.
Einstellung | Beschreibung | Beispiel/Standardeinstellung |
Webservice Port | Diese Einstellung gibt den Port an, wo das Service verfügbar ist. Wenn mehrere Principal Resolution Services konfiguriert sind, muss sichergestellt werden, dass unterschiedliche Ports benutzt werden und verfügbar sind. | Beispiel: 23900 |
Identity Alias Name Property | Diese Einstellung erlaubt es in der Identity befindliche Eigenschaften zu verwenden, um mit deren Wert im Cache nach Principals zu suchen. Es sollte der Eigenschaftsname eingetragen werden, der von der Authentisierung geliefert wird. Diese Einstellung wird z. B. bei der Authentisierung durch SAML verwendet, um damit eine Eigenschaft aus der Identity als Usernamen festzulegen. | Beispiel: |
Lowercase Principals | Mit dieser Einstellung werden die vom Cache gelieferten Principals kleingeschrieben. Dies sollte aktiviert werden, wenn der Konnektor Principals in Kleinbuchstaben ausliefert. Achtung: Diese Einstellung ist standardmäßig aktiviert, da dies für die meisten Datenquellen notwendig ist und potentielle Probleme bei der Verarbeitung der Principals vorbeugt. Das Deaktivieren dieser Einstellung sollte nur durchgeführt werden, wenn man weiß, wie die Principals aus der Datenquelle ausgegeben werden und welchen Effekt dies auf die Verarbeitung der Principals haben wird. | Standardeinstellung: Aktiviert |
Preserve Case for Principals Matching Pattern | Diese Einstellung ermöglicht das Beibehalten bestimmter (durch Regex Pattern definierte) Principals im originalen Format (nicht kleingeschrieben). | Beispiel: ^[a-z]+[A-Z][a-z]*$ Dieses Pattern matcht alle Principals, die in Camelcase geschrieben sind und zwei Wörter beinhalten wie z. B. „johnSmith“, „aliceJohnson“. |
Case Insensitive Member Resolution | Diese Einstellung bestimmt, ob Nutzer unabhängig von deren Groß- und Kleinschreibung geprüft werden. Die Notwendigkeit dieser Einstellung hängt von der Datenquelle ab. | Standardeinstellung: Aktiviert |
Exclude Principals Pattern | Diese Einstellung ermöglicht es bestimmte Principals für alle Nutzer aus deren Principals-Liste zu entfernen | Beispiel: .*_admin.* |
Suppress Anonymous Users Principals | Diese Einstellung ermöglicht es z. B. den Principal „Everyone“ für anonyme Nutzer zu unterdrücken. Damit können anonyme Nutzer auch öffentliche Dokumente nicht finden. | Standardeinstellung: Deaktiviert |
Suppress External Service Calls | Diese Einstellung verhindert, dass während der Suche externe Services wie z. B. LDAP abfragen können, welche Gruppen eines Nutzers sich nicht im Cache befinden. | Standardeinstellung: Aktiviert |
Resolve non-anonymous principal to all registered users. | Diese Einstellung bestimmt, ob „normale“ bzw. nicht anonyme Nutzer zu der Gruppe gehören, die alle Nutzer enthält. Wird zum Beispiel für die Active-Directory-Gruppe „everyone“ verwendet, worin sich alle Nutzer befinden. Ein weiterer Anwendungsfall ist, wenn Nutzer ohne ein Konto Zugang zu Dokumenten haben, die für alle registrierten Nutzer zugänglich sind. Hierbei wird entschieden, ob der Nutzer in die Gruppe „all registered users“ hinzugefügt wird. | Standardeinstellung: Aktiviert |
Parent Cache Settings
Im Bereich “Parent Cache Settings” können Parent/Child Konfigurationen erstellt werden. Mit einem Parent Cache werden zwei oder mehrere Principal Resolution Services miteinander verbunden. Dies ist notwendig, wenn die relevanten Principals für Dokumente aus einer bestimmten Datenquelle in verschiedenen Quellen verteilt sind. Ein praktisches Beispiel dazu kann im Kapitel Anwendungsfälle gefunden werden.
Einstellung | Beschreibung | Beispiel/Standardeinstellung |
Use Parent Principals Cache Service | Ist diese Einstellung aktiviert, werden die Gruppenmitgliedschaften aus dem Parent Cache zuerst berechnet und dessen Ergebnisse an den Child-Cache geliefert. Damit kann der aktuelle Cache die Ergebnisse des Parent Cache zum Nachschlagen nutzen. | Standardeinstellung: Deaktiviert |
Parent Principals Cache Service Port | Der Port der für die Einstellung „Use Parent Principals Cache Service“ verwendet wird, falls diese aktiviert ist. | Beispiel: 23902 |
Parent Cache Principals Include Patterns | In dieser Einstellung können Principals anhand von Regex-Mustern vom Parent Cache inkludiert werden. Stimmt der Principal mit mindestens einer Pattern-Zeile überein, wird dieser einbezogen. Ist dieses Feld leer, werden alle Principals vom Parent Cache einbezogen. Die Groß- und Kleinschreibung wird dabei nicht berücksichtigt. Die Principles in „Parent Cache Principals Exclude Patterns“ haben Vorrang vor den Principles in „Parent Cache Principals Include Patterns“. | Beispiel: ^[a-zA-Z]+\\.[a-zA-Z]+@mindbreeze\\.com$ Dieses Pattern matcht alle Email-Adressen, die in „@mindbreeze.com“ enden und sonst nur aus Kleinbuchstaben und einem Punkt bestehen. Zum Beispiel max.mustermann@mindbreeze.com . |
Parent Cache Principals Exclude Patterns | In dieser Einstellung können Principals anhand von Regex-Mustern vom Parent Cache exkludiert werden. Stimmt der Principal mit mindestens einer Pattern-Zeile überein, wird dieser ausgeschlossen. Die Groß- und Kleinschreibung wird dabei nicht berücksichtigt. Die Principles in „Exclude Patterns“ haben Vorrang vor den Principles in „Include Patterns“. | Beispiel: .*_admin.* |
Producer-Consumer Services
Mindbreeze InSpire kann mit dedizierten Producer- und Consumer-Nodes betrieben werden. Das Producer-Node ist für die Vorbereitung zuständig, indem dort der Index aufgebaut, das Crawling ausgeführt und die Gruppen gesammelt werden. Ist das Producer-Node mit der Vorbereitung fertig, werden die Principal Resolution Service Daten kopiert und damit das Consumer-Node aktualisiert.
Das Consumer-Node wird im Query Service abgefragt und vom Producer-Node aktualisiert. Sollte das Producer-Node aktualisiert werden, bewirkt dies automatisch eine Aktualisierung des Consumer-Node.
Für mehr Informationen zu Producer- und Consumer-Node, siehe die Dokumentation Handbook - Distributed Operation (G7) - Introduction.
Nachfolgend wird erklärt, wie der Cache des Producer-Node und des Consumer-Node konfiguriert werden.
Producer Cache
Klicken Sie im Producer-Node (= erstellter Service) im „Indices“-Tab im Abschnitt “Consumer Services” auf “Add Property”. Konfigurieren Sie dann die folgenden Einstellungen:
Einstellung | Beschreibung | Beispiel/Standardeinstellung |
Diese Einstellung sollte nur auf Producer-Nodes von Mindbreeze InSpire Umgebungen mit Producer- und Consumer-Nodes aktiviert werden. Lokale Updates auf allen Consumer-Nodes werden deaktiviert. Wenn Consumer Base URLs konfiguriert sind, werden per Remote-Zugriff nur diese konfigurierten Consumer aktualisiert. Eine explizite Konfiguration ist in manchen Situationen nicht empfohlen, wo die Producer- oder Consumer-Nodes deaktiviert werden oder eine andere Rolle bekommen. In solchen Fällen ist es ausreichend nur diese Einstellung am Producer-Node zu aktivieren, da die Consumer-Nodes automatisch berechnet werden. | Standardeinstellung: Deaktiviert | |
Disable | Deaktiviert das Aktualisieren des Remote-Cache. | Standardeinstellung: Deaktiviert |
Base URL | Die URL zum Mindbreeze Management Center der Mindbreeze InSpire Consumer-Appliance. | Beispiel: https://myhost.myorganization.com:8443 |
Realm | Das Ziel-Realm der Consumer-Appliance. Der Standard ist “master”. Achtung: Bei der Verwendung von Windows ist die Angabe eines Realm nicht notwendig, da dies von der Base URL angegeben wird. | Standardeinstellung: master |
Service Port | Der Port des Caching Principal Resolution Service auf der Mindbreeze InSpire Appliance. Achtung: Bei der Verwendung von Windows muss der Service Port leer bleiben, da der Port die Base URL beinhalten soll. | Beispiel: 23900 |
Consumer Cache
Ist bei einer Mindbreeze InSpire Umgebung mit Producer- und Consumer-Nodes, die Einstellung „Readonly on Consumer“ auf dem Producer-Node konfiguriert, so sind lokale Cache-Aktualisierungen auf Consumer-Nodes deaktiviert. Im Falle von anderen Umgebungen muss die Einstellung "Readonly" manuell in den "Cache Update Settings" im Consumer-Cache gewählt werden, wie im folgenden Screenshot dargestellt. Es ist keine weitere Konfiguration erforderlich. Der Consumer Cache wird nach jeder Aktualisierung im Producer Cache automatisch synchronisiert.
Anwendungsfälle
Parent/Child Cache – Auflösung von Principals aus mehreren Datenquellen
Parent und Child Principal Resolution Services sind erforderlich, wenn die relevanten Principals für Dokumente aus einer bestimmten Datenquelle in verschiedenen Quellen verteilt sind. Ein Beispiel dafür ist Microsoft Sharepoint Online, wo Principal-Informationen einerseits in den jeweiligen Sharepoint Online Sites und andererseits auf der Microsoft Azure Plattform zu finden sind.
Durch die Parent/Child-Konfiguration ist es möglich, Daten aus verschiedenen Principal Resolution Services zu verbinden, ohne die Daten zu duplizieren oder die Autonomie des Parent Cache aufzugeben.
Ablauf der Auflösung des Principals mit Parent/Child Service:
Die Auflösung von Principals durch den Parent/Child-Service folgt einem festgelegten Prozess:
- Weiterleitung an den Parent Cache durch den Child Service:
- Der Child Service leitet vor der Auflösung des Principals alle erhaltenen Principals an den Parent Cache weiter.
- Auflösung durch den Parent Service:
- Der Parent Service löst alle ihm bekannten Principals auf und sendet sie an den Child Service zurück.
- Abschließende Auflösung durch den Child Service:
- Letztendlich löst der Child Service alle erhaltenen Principals auf, sodass die vollständige Auflösung erfolgt.
Auswahl des Parent- und Child-Services:
Die Entscheidung, welcher Service der Parent-Service oder der Child-Service sein sollte, kann anhand der folgenden Kriterien getroffen werden:
- Parent-Service:
- Der Parent-Service sollte allgemeine Principal-Informationen besitzen, die für mehrere Datenquellen relevant sind. Dieser Service kann zusätzlich für weitere Child-Services verwendet werden und eigenständig als Caching Principal Resolution Service fungieren.
- Beispiel: Microsoft Azure, LDAP.
- Child-Service:
- Der Child-Service sollte spezifische Principal-Informationen besitzen, die für eine bestimmte Datenquelle relevant sind.
- Beispiel: Sharepoint Online, OpenText Documentum.
Allgemeine Konfiguration
Konfiguration der eigenständigen Services:
- Konfigurieren Sie zunächst alle Services eigenständig, wobei die Services jeweils ihre eigenen Datenquellen und Einstellungen haben. Mehr Informationen über die Konfiguration eines Principal Resolution Service finden Sie im Kapitel Grundlegende Konfiguration.
- Stellen Sie nach der Konfiguration sicher, dass die einzelnen Caches der Principal Resolution Services fertig aufgebaut sind und die Principals richtig aufgelöst werden. Mehr Informationen zur Überprüfung des Caches und der Auflösung der Principals, finden Sie im Kapitel Monitoring.
Festlegung eines Principal Resolution Services als Parent Cache:
Um die Parent/Child-Konfiguration einzustellen, müssen folgende Schritte durchgeführt werden:
- Gehen Sie zum Abschnitt "Parent Cache Settings" im Child-Service.
- Aktivieren Sie die Einstellung "Use Parent Principals Cache Service".
- Geben Sie den "Webservice Port" des Parent-Service in der Einstellung "Parent Principals Cache Service Port" ein.
- Speichern Sie die Änderungen.
Konfiguration in den Index-Einstellungen:
Nun muss das Child Principal Resolution Service der entsprechenden Datenquelle in Ihrem Index zugewiesen werden.
Konfigurationsbeispiel mit Microsoft Sharepoint Online
Microsoft SharePoint Online ist ein Beispiel für eine Datenquelle, die eine Parent/Child-Konfiguration erfordert. Die Principal-Informationen, die für diese Datenquelle relevant sind, befinden sich auf den jeweiligen SharePoint Online Sites und auch auf der Microsoft Azure Plattform.
Um die korrekte Auflösung der Principals, die für SharePoint Online relevant sind, zu gewährleisten, ist die Verknüpfung aller Principals aus beiden Quellen über eine Parent/Child-Konfiguration notwendig.
Hinweis: Falls die Erstellung von Credentials zusätzlich benötigt wird, finden Sie die notwendigen Informationen in den Dokumentationen Konfiguration - Microsoft SharePoint Online Connector - Konfiguration der Zugangsdaten und Endpunkte und Konfiguration - Microsoft Azure Principal Resolution Service - Konfiguration des Microsoft Azure Principal Resolution Service.
Die Erstellung der Parent/Child-Konfiguration wird folgendermaßen durchgeführt:
- Erstellung eines Index und Crawlers
Erstellen Sie einen neuen Index, wenn noch kein Index vorhanden ist. Wählen Sie als Datenquelle "Microsoft SharePoint Online" aus. In diesem Beispiel lautet der Indexname "Microsoft SharePoint Online Index".
- Erstellung des Parent Service für Microsoft SharePoint Online
Erstellen Sie einen neuen Caching Principal Resolution Service, indem Sie "Add Service" anklicken und unter "Service" die Option "SharepointOnlinePrincipalCache" auswählen. Geben Sie dem Cache einen Namen wie z. B. "Microsoft SharePoint Online Cache".
- Konfiguration des Webservice Ports für den Microsoft SharePoint Online Principal Resolution Service
Geben Sie im Abschnitt "Service Settings" des Principal Resolution Services einen Webservice Port an. Die Verfügbarkeit dieses Ports ist wichtig, da der Service sonst nicht funktionsfähig ist. In diesem Beispiel wird der Port "23901" verwendet.
- Erstellung des Principal Resolution Service für Microsoft Azure
Erstellen Sie nun einen zweiten Caching Principal Resolution Service für Microsoft Azure. Wählen Sie unter "Service" die Option "Microsoft Azure Principal Resolution Service" aus. Geben Sie dem Service einen Namen wie z. B. "Microsoft Azure Cache".
- Konfiguration des Webservice Ports für den Microsoft Azure Principal Resolution Service
Geben Sie für den Microsoft Azure Caching Principal Resolution Service einen "Webservice Port" an. In diesem Beispiel wird der Port "23902" verwendet.
- Festlegung des Parent Cache und des Child Cache für die Auflösung der Principals
Der Microsoft Azure Principal Resolution Service wird als Parent-Service und der Microsoft SharePoint Online Principal Resolution Service wird als Child-Service festgelegt. Die Gründe dafür sind:
- Der Microsoft Azure Principal Resolution Service stellt allgemeine Principal-Informationen für mehrere Datenquellen bereit. Also muss dies der Parent-Service sein.
- Der Microsoft SharePoint Online Principal Resolution Service stellt spezifische Principal-Informationen nur für Sharepoint Online bereit. Also muss dies der Child-Service sein.
- Konfiguration des Services als Child-Service
Öffnen Sie den „Microsoft SharePoint Online Cache“ und geben Sie im Abschnitt "Parent Cache Settings" in der Einstellung "Parent Principals Cache Service Port" den Port des „Microsoft Azure Cache“ an. In diesem Beispiel wird der Port "23902" benötigt.
- Verknüpfung des Microsoft SharePoint Online Principal Resolution Service mit dem Index
Öffnen Sie den Index und gehen Sie im Abschnitt "Data Sources" auf die Einstellung "Caching Principal Resolution Service". Wählen Sie dann den entsprechenden Service aus. In diesem Beispiel muss "Microsoft SharePoint Online Cache" gewählt werden.
- Fertigstellung der Konfiguration
Speichern Sie schlussendlich die Konfiguration, um die Erstellung der Parent/Child-Konfiguration zu beenden.
Verwendung von (LDAP/SAML) Identity-Attributen zur Auflösung von Principals
Was ist ein Mindbreeze-Identity-Objekt?
Meldet sich ein Nutzer in einer Suchanwendung an, werden die Nutzerinformationen in Form eines Mindbreeze-Identity-Objekts gespeichert. Wenn dieser Nutzer eine Suche startet, wird dieses Identity-Objekt zur Auflösung der Principals an den Principal Resolution Service weitergeleitet.
Was sind Identity-Attribute?
Je nach verwendetem Authentifizierungssystem, können Identity-Objekte optionale Attribute enthalten. Wenn beispielsweise LDAP für die Single-Sign-On-Authentifizierung in Ihrer Suchanwendung genutzt wird, werden automatisch alle mitgelieferten LDAP-Attribute als Identity-Attribute übernommen. Gleiches gilt für die Verwendung von SAML-Authentifizierung mit den entsprechenden SAML-Attributen.
Standardverhalten bei der Auflösung von Principals
Standardmäßig wird für die Auflösung der Principals in einem Principal Resolution Service nur der Nutzername (und alle bekannten Aliase) des angemeldeten Nutzers verwendet. Die Identity-Attribute werden dabei ignoriert. Wenn Ihre Datenquelle beispielsweise E-Mail-Adressen zur Identifikation von Nutzern verwendet, wird eine Auflösung der Principals allein auf Basis des Nutzernamens keine Ergebnisse liefern.
Konfiguration für Identity-Attribute zur Auflösung von Principals
Um dieses Problem zu lösen, muss das Identity-Attribut, in diesem Fall die E-Mail-Adresse, als Alias für den Principal Resolution Service markiert werden. Dadurch wird gewährleistet, dass der Wert dieses Attributes für die Auflösung des Principals berücksichtigt wird. Dies kann mithilfe der Einstellung "Identity Alias Name Property" im Abschnitt "Service Settings" vorgenommen werden.
Konfigurationsbeispiel für Microsoft Azure/SAML-Authentifizierung mit Box als Datenquelle
In diesem Beispiel betrachten wir die Datenquelle Box. Diese Datenquelle verwendet E-Mail-Adressen zur Identifikation der Nutzer.
Der Mindbreeze Search Client ist so konfiguriert, dass eine SAML-basierte Anmeldung über Microsoft Azure (Entra) verwendet wird, mithilfe des Microsoft Azure Principal Resolution Service.
Beispiel für eine SAML-Claims-Konfiguration in Microsoft Azure (Entra):
Da Box die Identifikation der Nutzer mit E-Mail-Adressen durchführt, ist die alleinige Verwendung des Nutzernamens in der Auflösung der Principals unzureichend. Ohne weitere Konfigurationen können unsere Such-Nutzer daher keine Resultate finden.
Konfiguration
Für die notwendige Konfiguration muss der passende Microsoft Azure Claim Name „http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" als Alias markiert werden.
Dies kann in den „Service Settings“ in der Einstellung „Identity Alias Name Property“ des Principal Resolution Services getan werden (siehe Screenshot). Dieses Attribut wird von Microsoft Azure bereitgestellt und wird bei der SSO-Anmeldung als SAML-Attribut an den Mindbreeze Search Client weitergeleitet.
Ergebnis
Durch diese Konfiguration sollte der "Microsoft Azure Resolution Service" nun alle Nutzer anhand ihrer E-Mail-Adressen erfolgreich identifizieren und die Principals ordnungsgemäß auflösen können. Die Nutzer sollten daher nun problemlos nach Box-Dokumenten suchen können.
Nun kann getestet werden, ob die Auflösung der Principals wie erwartet funktioniert. Für mehr Informationen, wie man die Auflösung der Principals überprüfen kann, siehe das Kapitel Monitoring.
Ausschluss von Principals mit weitreichenden Rechten
In manchen Fällen haben bestimmte Principals in einem System sehr weitreichende Rechte. Dadurch wird ihnen Zugriff auf viele Daten und Ressourcen gewährt. Dies kann ein potentielles Sicherheitsrisiko darstellen. Um dieses Risiko zu minimieren und die Datensicherheit zu gewährleisten, können solche Principals präventiv aus dem Principal Resolution Service ausgeschlossen werden.
Konfigurationsbeispiel für den Ausschluss von Principals nach einem bestimmten Muster
Angenommen es sollen alle Principals ausgeschlossen werden, deren Namen mit "_admin" enden. Solche Namen kennzeichnen oft Nutzer mit sehr umfangreichen Rechten, die potenziell uneingeschränkten Zugriff auf Daten und Ressourcen haben.
Konfiguration
Um dies zu erreichen muss die Einstellung "Exclude Principals Pattern" mit einem Regex-Muster konfiguriert werden. Durch das Regex-Muster werden alle Principals mit der Endung "_admin" aus dem Principal Resolution Service entfernt.
Das benötigte Regex-Muster lautet in diesem Fall:
.*_admin.*
Nach der Konfiguration müssen die Änderungen im Principal Resolution Service gespeichert werden.
Ergebnis
Durch diese Konfiguration werden alle Principals, die mit "_admin" enden und möglicherweise sehr weitreichende Rechte haben, aus dem Principal Resolution Service ausgeschlossen. Dies minimiert das Sicherheitsrisiko und stellt sicher, dass Nutzer mit solchen Rechten keinen uneingeschränkten Zugriff auf alle Dateien und Daten haben.
Troubleshooting
Problemlösung bei Unterschieden in der Groß- und Kleinschreibung von Principals
Unterschiede in der Groß- und Kleinschreibung von Principals können dazu führen, dass die Auflösung von Nutzern nicht wie erwartet funktioniert oder dass die aufgelösten Principals nicht der Groß- und Kleinschreibung der Dokument-ACLs entsprechen.
Fall 1: Die aufgelösten Principals entsprechen nicht den Dokument-ACLs
Ein solcher Fall könnte wie folgt aussehen:
- ACLs der Dokumente: sales, marketing.
- Gespeicherte Principals im Principal Resolution Service: SALES, MARKETING.
Lösung:
Dafür muss im Abschnitt „Service Settings“ die Einstellung "Lowercase Principals" für den Principal Resolution Service aktiviert werden. Diese Einstellung ermöglicht die Umwandlung aller Principals in Kleinbuchstaben, unabhängig von ihrer ursprünglichen Schreibweise.
Fall 2: Principals der angemeldeten Nutzer werden nicht aufgelöst
Ein solcher Fall könnte wie folgt aussehen:
- Anmeldeinformationen des Nutzers: “david porter”.
- Gespeicherte Principals im Principal Resolution Service: “David Porter”, “David.Porter”, „david.porter@mindbreeze.com“.
Lösung 1:
Dafür muss im Abschnitt „Service Settings“ die Einstellung "Lowercase Principals" für den Principal Resolution Service aktiviert werden. Diese Einstellung ermöglicht die Umwandlung aller Principals in Kleinbuchstaben, unabhängig von ihrer ursprünglichen Schreibweise.
Achtung: Das Aktivieren dieser Einstellung löst das Problem nur, wenn die Anmeldeinformationen in Kleinbuchstaben vorliegen.
Lösung 2:
Alternativ kann im Abschnitt "Service Settings" die Einstellung "Case Insensitive Member Resolution" für den Principal Resolution Service aktiviert werden. Diese Einstellung ermöglicht die korrekte Auflösung von Principals, unabhängig von der Groß- und Kleinschreibung.