Installation und Konfiguration
Microsoft Graph Connector

Einleitung

Mithilfe des Microsoft Graph Connector können alle User einer Microsoft Graph Instanz indiziert und in Mindbreeze InSpire verwendet werden. Hierbei werden Microsoft Entra ID User inklusive folgender Punkte indiziert:

Profil-Metadaten
Manager Namen und die Referenzen zum Manager (z. B. Organigramm)
Microsoft Graph Profilbilder als Thumbnails in Mindbreeze InSpire
„Extension Attributes“ des Users

Hinweis: Microsoft Entra ID (ME-ID) ist der neue Name für Microsoft Azure Active Directory (Azure AD). Die Verwaltung ihrer Microsoft Graph Instanz können Sie hier vornehmen: Microsoft Entra - Microsoft Entra admin center.

Für mehr Informationen, was Microsoft Entra ID ist und welche Änderungen es beim Namenswechsel zu beachten gibt, siehe What is Microsoft Entra ID? - Microsoft Entra | Microsoft Learn und New name for Azure Active Directory - Microsoft Entra | Microsoft Learn.

Voraussetzungen

Um das Crawling von Microsoft Graph zu ermöglichen, wird eine neue oder bestehende Microsoft Graph Applikation benötigt, die Berechtigungen zum Auslesen von Microsoft Graph hat.

Die Microsoft Graph Applikation muss folgende Voraussetzungen erfüllen:

Verfügbares Client Secret
- Eine Gültigkeitsdauer von 6 bis 12 Monaten wird empfohlen, damit das Client Secret regelmäßig gewechselt wird.
- Achtung: Beachten Sie bei der Erzeugung des Client Secrets, dass das Secret in der Spalte „Value“ für die Erstellung des Credentials in Mindbreeze InSpire zwingend notwendig ist. Notieren Sie sich diesen Wert direkt nach der Erzeugung des Client Secrets, da der Wert beim Verlassen des Bereiches nicht mehr vollständig angezeigt wird.
Erteiltes Zugriffsrecht
- User.Read.All

Die Erstellung einer neuen Applikation wird in Microsoft Entra - Microsoft Entra admin center durchgeführt. Für mehr Informationen, siehe folgende Links:

Registrierung einer neuen Applikation: How to register an app in Microsoft Entra ID - Microsoft identity platform | Microsoft Learn
Erzeugung eines Client Secret: Add and manage app credentials in Microsoft Entra ID - Microsoft identity platform | Microsoft Learn
Vergabe der Zugriffsrechte: Web API app registration and API permissions - Microsoft identity platform | Microsoft Learn

Konfiguration

In diesem Kapitel wird die grundlegende Konfiguration des Microsoft Graph Connectors in einem Schnellstart-Guide erklärt. Sollten Sie aufgrund ihres Anwendungsfalles zusätzliche Informationen benötigen, finden Sie zum Beispiel eine Liste aller Einstellungen und nationalen Endpunkten in den darauffolgenden Kapiteln.

Schnellstart-Guide

Schritt 1: Erstellung des Index

Fügen Sie im Tab „Indices“ mit dem Button „+Add Index“ einen neuen Index hinzu. Wählen Sie den gewünschten „Index Node“ und „Client Service“ aus und wählen Sie bei „Data Source“ die Option „Microsoft Graph“ aus. Bestätigen Sie Ihre Eingaben anschließend mit „Apply“.

Geben Sie dem neu erstellten Index mit „Display Name“ einen Namen, wie zum Beispiel „Microsoft Graph Connector“.

Speichern Sie den erstellten Index mit „Save“.

Schritt 2: Erstellung des Credential

Als nächstes wird ein passendes Credential benötigt. Sollten Sie bereits ein Credential konfiguriert haben mit dem passenden „Type“ und „Password“, können Sie dieses Credential verwenden. Ist dies nicht der Fall, muss ein neues Credential im „Netzwerk“ Tab mit den folgenden Einstellungen erstellt werden:

Einstellung	Eingabe
Name	Beispiel: Microsoft Graph App Credential Client Secret
Type	Password
Password	Als Passwort wird das Client Secret ihrer Microsoft Graph Instanz benötigt. Beispiel: 1234abcd-5678-ef90-1a2b-3c4d5e6f7a8b

Speichern Sie das erstellte Credential mit „Save“.

Schritt 3: Konfiguration der Datenquelle

Gehen Sie zurück zum erstellten Index im Tab „Indices“ und konfigurieren mit den folgenden Einstellungen im Abschnitt „Data Sources“ die Datenquelle:

Einstellung	Beschreibung	Beispiel
Tenant ID	Die Tenant ID der Microsoft Graph Applikation. Hinweis: Die „Tenant ID“ finden Sie im „Overview“ Bildschirm ihrer Applikation im Bereich „Essentials“ als „Directory (tenant) ID“.	Beispiel: 5678efgh-9012-ij34-5a6b-5c6d7e8f9a0b
App ID	Die App ID der Microsoft Graph Applikation. Hinweis: Die „App ID“ finden Sie im „Overview“ Bildschirm ihrer Applikation im Bereich „Essentials“ als „Application (client) ID“.	Beispiel: 3434cdcd-7878-gh09-1a2b-3c4d3e4f3a4b
Client Secret	Das im „Network“-Tab angelegte Credential, welches das erstellte Client Secret enthält.	Beispiel: Microsoft Graph App Credential Client Secret

Speichern Sie die Konfiguration mit „Save“. Der Microsoft Graph Connector ist jetzt vollständig konfiguriert.

Verfügbare Einstellungen

Bereich „Connection Settings“

Im Bereich „Connection Settings“ können Sie Ihre Microsoft Graph Instanz, die indiziert werden soll, definieren.

Einstellung

Beschreibung

Standardeinstellung/Beispiel

Graph Service Root

(Advanced Settings)

Der Endpunkt bzw. die URL der Microsoft Graph API.

Ändern Sie diese Einstellung nur, wenn Sie eine nationale Microsoft Cloud, wie zum Beispiel die Cloud für die US-Regierung, verwenden möchten.

Eine Liste aller verfügbaren nationalen Microsoft Graph Endpunkte finden Sie im Kapitel Microsoft Graph.

Standardeinstellung:

https://graph.microsoft.com

AD Url

(Advanced Settings)

Der Endpunkt bzw. die URL zur Microsoft Entra ID Cloud.

Ändern Sie diese Einstellung nur, wenn Sie eine nationale Microsoft Cloud, wie zum Beispiel die Cloud für die US-Regierung, verwenden möchten.

Eine Liste aller verfügbaren nationalen Microsoft Entra ID Endpunkte finden Sie im Kapitel Microsoft Entra ID.

Standardeinstellung:

https://login.microsoftonline.com

Trust all SSL certificates

(Advanced Settings)

Erlaubt die Verwendung von nicht gesicherten Verbindungen, beispielsweise für Testsysteme.

Achtung: Aktivieren Sie diese Einstellung nicht in der Produktionsumgebung.

Standardeinstellung:

Deaktiviert

Tenant ID*

Die Tenant ID der Microsoft Graph Applikation.

Hinweis: Die „Tenant ID“ finden Sie im „Overview“ Bildschirm ihrer Applikation im Bereich „Essentials“ als „Directory (tenant) ID“.

Beispiel:

5678efgh-9012-ij34-5a6b-5c6d7e8f9a0b

App ID*

Die App ID der Microsoft Graph Applikation.

Hinweis: Die „App ID“ finden Sie im „Overview“ Bildschirm ihrer Applikation im Bereich „Essentials“ als „Application (client) ID“.

Beispiel:

3434cdcd-7878-gh09-1a2b-3c4d3e4f3a4b

Client Secret*

Das im „Network“-Tab angelegte Credential, welches das erstellte Client Secret enthält.

Beispiel:

Microsoft Graph App Credential Client Secret

Crawler Thread Count

Anzahl an Threads, die für die Indizierung verwendet werden.

Standardeinstellung:

Max Retries

Die maximale Anzahl an Retries die versucht werden, wenn der Server gewisse Throttling Responses schickt (z.B. HTTP 429).

Standardeinstellung:

Network Timeout (Seconds)

Zeit in Sekunden, die der Connector auf eine Antwort von Microsoft Graph wartet.

Standardeinstellung:

Log All Requests

(Advanced Settings)

Ist diese Einstellung aktiviert, werden alle Anfragen gegen die Graph API in einer Log-Datei geschrieben.

Sollte nur für Troubleshooting aktiviert werden.

Standardeinstellung:

Deaktiviert

Get Metadata From Profile

(Advanced Settings)

Ist diese Einstellung aktiviert, werden zusätzliche Metadaten vom Profil-Endpunkt heruntergeladen. Diese Informationen umfassen Fähigkeiten, Sprachen, Projekte usw.

Standardeinstellung:

Aktiviert

Include Additional User Info

(Advanced Settings)

Ist diese Einstellung aktiviert, werden folgende zusätzliche Metadaten über jeden Benutzer abgerufen:

Metadaten	Beschreibung
mgru_manager	Name des Managers des Users.
mgru_managerId	Referenz zum Manager.
mgru_onPremises ExtensionAttributes	Item, das alle Erweiterungsattribute (1-15) enthält (wenn gesetzt).
mgru_onPremises ExtensionAttributes _extensionAttribute<x>	Der Wert des Erweiterungsattributes x (wenn gesetzt).

Standardeinstellung:

Aktiviert

Enable Delta Crawl

(Advanced Settings)

Ist diese Einstellung aktiviert, holt sich der Crawler nur beim ersten Update alle User von Microsoft Graph ab. Danach werden nur noch die Änderungen am User abgeholt. Mit dieser Einstellung kann eine bessere Performance erzielt werden.

Deaktivieren Sie diese Einstellung nur, falls eine Inkonsistenz zwischen dem Index und den tatsächlichen Usern in Microsoft Graph entstanden ist.

Standardeinstellung:

Aktiviert

Use Profile Picture as Thumbnail

(Advanced Settings)

Ist diese Einstellung aktiviert, wird das Profilbild des Benutzers in Microsoft Graph als Thumbnail in Mindbreeze InSpire verwendet.

Standardeinstellung:

Aktiviert

* = Diese Einstellungen müssen zwingend konfiguriert werden, damit der Connector funktioniert und aufgebaut wird. Alle weiteren Einstellungen müssen je nach Anwendungsfall konfiguriert werden.

Bereich „Crawling Constraints“ (Advanced Settings)

Einstellung

Beschreibung

Constraints

Mit „Constraints“ können Nachrichten abhängig von ihren Metadaten exkludiert werden.

Einstellung	Beschreibung
Metadata Key	Der Name des Metadatums, mit dem die Regex-Patterns verglichen werden. Das bezieht sich auf den Namen des Metadatums im Index.
Include Pattern (regex)	Regex-Pattern, mit dem der Wert der Metadaten verglichen wird. Wenn das Regex-Pattern übereinstimmt, wird das Dokument inkludiert.
Exclude Pattern (regex)	Regex-Pattern, mit dem der Wert der Metadaten verglichen wird. Wenn das Regex-Pattern übereinstimmt, wird das Dokument exkludiert.

Folgendes ist zu beachten:

Ein Constraint wird nur überprüft, wenn das Objekt das entsprechende Metadatum gesetzt hat. Ansonsten wird das Constraint ignoriert.
Das Exkludieren wird stärker als das Inkludieren behandelt. Wenn ein Objekt von mindestens einem „Exclude Pattern“ exkludiert wird, wird es nicht indiziert, egal ob es mit einem anderen „Include Pattern“ übereinstimmt.
Wenn ein „Include Pattern“ für ein Metadatum konfiguriert ist, muss jedes Objekt, welches das Metadatum besitzt, mit dem Pattern übereinstimmen, damit es indiziert wird.
Wenn für das Metadatum nur „Exclude Pattern“ gesetzt wurden, wird das Objekt indiziert, solange es mit keinem „Exclude Pattern“ übereinstimmt.

Bereich „Authorization Settings“ (Advanced Settings)

Einstellung

Beschreibung

Static Access Rules

Microsoft Graph Dokumente sind standardmäßig nicht nutzbar in Mindbreeze InSpire, da Microsoft Graph keine ACL-Informationen zur Verfügung stellt. Um Microsoft Graph Dokumente in Mindbreeze InSpire dennoch zu nutzen, können statische ACLs in dieser Einstellung gesetzt werden.

Zusätzlich kann der Zugriff auf gewisse Benutzer und Gruppen auch mit statischen ACLs festgelegt werden.

Folgende Einstellungen stehen zur Verfügung:

Einstellung	Beschreibung
Access Check Principal	Der Principal Name, für den die Access Rule gelten soll (z.B. everyone, user@myorganization.com, Management).
Access Check Action	Hier können Sie auswählen, ob dem definierten Principal der Zugang gewährt („Grant“) oder verweigert („Deny“) werden soll.

Verfügbare nationale Endpunkte

Microsoft Graph

Nationale Cloud	Microsoft Graph
Microsoft Graph weltweiter Service	https://graph.microsoft.com
Microsoft Graph für US Government L4 (GCC High)	https://graph.microsoft.us
Microsoft Graph für US Government L5 (DOD)	https://dod-graph.microsoft.us
Microsoft Graph China betrieben von 21Vianet	https://microsoftgraph.chinacloudapi.cn

Für mehr Informationen, siehe https://learn.microsoft.com/de-de/graph/deployments#microsoft-graph-and-graph-explorer-service-root-endpoints.

Microsoft Entra ID

Nationale Cloud	Microsoft Entra-Authentifizierungsendpunkte
Microsoft Entra ID (globaler Dienst)	https://login.microsoftonline.com
Microsoft Entra ID für die US-Regierung	https://login.microsoftonline.us
Microsoft Entra ID China, betrieben von 21Vianet	https://login.partner.microsoftonline.cn

Für mehr Informationen, siehe https://learn.microsoft.com/de-de/entra/identity-platform/authentication-national-cloud#microsoft-entra-authentication-endpoints.

Liste der Requests

Die folgenden Requests werden vom Microsoft Graph Connector im Laufe des Crawl-Durchgangs ausgeführt.

Request	HTTP-Methode	Beschreibung
https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token	POST	Abholen des Access Tokens.
https://graph.microsoft.com/beta/users/delta	GET	Abholen aller User beim ersten Crawl-Durchgang und danach, falls die Einstellung „Enable Delta Crawl“ aktiviert ist, werden ebenfalls die User abgeholt, die seit dem letzten Crawl-Durchgang geändert wurden.
https://graph.microsoft.com/beta/users/<userId>	GET	Abrufen zusätzlicher User-Informationen (z. B. Informationen zum Manager).
https://graph.microsoft.com/beta/users/<userId>/photo/$value	GET	Herunterladen des Profilbildes eines Users.

Installation und Konfiguration
Microsoft Graph Connector

Einleitung

Voraussetzungen

Konfiguration