Benutzerverzeichnis: Microsoft Graph

Du kannst Deine Nutzer und Gruppen über die Microsoft Graph API synchronisieren. Um die Synchronisierung zu aktivieren, musst Du Schritte sowohl in Microsoft Entra ID als auch in der Administration von Haiilo abschließen.

Bei der Synchronisierung eines Benutzerverzeichnisses werden Nutzer und Gruppen separat synchronisiert. Zuerst werden Gruppen synchronisiert, gefolgt von den Nutzern. Nutzer können nur zu den Gruppen hinzugefügt werden, die im ersten Schritt synchronisiert wurden. Alle Nutzer, die den Nutzerfiltern entsprechen, werden jedoch synchronisiert, unabhängig davon, ob sie zu den Gruppen gehören, die in der Gruppensynchronisierung synchronisiert wurden.

Bitte schließe die App-Registrierung in Microsoft Entra ID gemäß den Details im Artikel Microsoft-Authentifizierung einrichten ab, bevor Du mit diesem Tutorial fortfährst.

API-Berechtigungen in Microsoft hinzufügen

Du benötigst Administratorrechte in Deinem Microsoft Entra ID-Konto, um die Konfiguration abzuschließen.

  1. Melde Dich bei der Microsoft Azure-Plattform an.
  2. Gehe zu Microsoft Entra ID > App-Registrierungen > wähle die App aus, die Du erstellt hast, als Du die Microsoft-Authentifizierung für Haiilo eingerichtet hast
  3. Gehe zu API-Berechtigungen
  4. Wähle Berechtigung hinzufügen > Microsoft Graph > Anwendungsberechtigungen
  5. Füge die folgenden API-Berechtigungen hinzu:
    • Group.Read.All
    • User.Read.All
  6. Wähle Administratoreinwilligung erteilen für app_name für die hinzugefügten Berechtigungen und stelle sicher, dass der Status für alle Berechtigungen als Genehmigt für deinen_mandanten markiert ist.

Ein neues Benutzerverzeichnis in Haiilo einrichten

Du benötigst die Berechtigung "Verwaltung der Benutzerverzeichnisse", um ein Microsoft Graph-Benutzerverzeichnis in Haiilo einzurichten.

  1. Gehe in Haiilo zu Administration > Benutzerverzeichnisse
  2. Wähle Benutzerverzeichnis erstellen
  3. Gib einen Namen ein
  4. Wähle den Typ: Microsoft Graph
  5. Aktiviere Aktiv, wenn dieses neue Benutzerverzeichnis direkt aktiviert werden soll

Fülle die Felder auf jedem Tab wie unten detailliert aus.

Verbindung

  1. Gib die Anwendungs-(Client-)ID ein, die Du aus Microsoft Entra ID kopiert hast, in das Feld Client-ID ein
  2. Gib den Clientschlüssel ein, den Du aus Microsoft Entra ID kopiert hast, in das Feld Client-Secret ein
  3. Gib die Verzeichnis-(Mandanten-)ID ein, die Du aus Microsoft Entra ID kopiert hast, in das Feld Tenant ein
  4. Wähle Verbindung testen , um zu überprüfen, ob die Verbindung hergestellt wurde

Nutzer

  1. Benutzerfilter: Definiere Filter, um nur bestimmte Nutzer zu synchronisieren. Du kannst die Standard-Microsoft-Graph-Filter verwenden, z.B. startsWith(displayName,'Jane').
  2. Lokaler Benutzerfilter: Der lokale Nutzerfilter funktioniert genauso wie der normale Nutzerfilter, ist jedoch kein Teil der Abfrage an die MS Graph API, sondern wird im Haiilo-Backend auf der empfangenen Antwort ausgeführt. Dadurch ist es möglich, zunächst nach dem 'Nutzerfilter' in der 1. Phase zu filtern und dann weiter nach dem 'lokalen Nutzerfilter' mit Ausdrücken zu filtern, die von MS Graph nicht unterstützt werden.
  3. Lokale Gruppen entfernen: Überprüfe, ob du die synchronisierten Nutzer aus allen lokalen Gruppen entfernen möchtest, zu denen sie manuell hinzugefügt wurden.
  4. Andere Verzeichnisgruppen entfernen: Überprüfe, ob du die synchronisierten Nutzer aus allen anderen Benutzerverzeichnisgruppen entfernen möchtest, zu denen sie manuell hinzugefügt wurden.
  5. Sync-Manager: Überprüfe, ob du möchtest, dass die Manager und Teams der Nutzer in ihren Profilen sichtbar sind.
  6. Benutzername: Gib das Attribut für den Benutzernamen ein. Wir empfehlen die Verwendung von mail oder userPrincipalName.
  7. Du kannst auch zusätzliche Profilfelder synchronisieren. Das Mapping der Profilfelder kann für die MS Graph API komplex sein, da die API mit JSON-Objekten antwortet, die verschachtelte Daten enthalten können.

Gruppen

  1. Um Gruppen aus dem Microsoft Graph zu synchronisieren, aktiviere Gruppen synchronisieren.
  2. Gruppenfilter: Definiere Filter, um nur bestimmte Gruppen zu synchronisieren. Du kannst die Standard-Microsoft-Graph-Filter verwenden, z.B. startsWith(displayName, 'Haiilo')
  3. Nur Benutzer aus Gruppen: Überprüfe, ob du nur Nutzer synchronisieren möchtest, die Teil einer synchronisierten Gruppe sind. Wenn dies aktiviert ist, werden nur die Nutzer synchronisiert, die dem Benutzerfilter entsprechen und auch einer in der Gruppensynchronisation synchronisierten Gruppe angehören.
  4. Gruppen bewahren: Wenn Gruppen synchronisieren deaktiviert ist, kannst du dieses Feld aktivieren, um alle zuvor synchronisierten Gruppen für dieses spezifische Benutzerverzeichnis beizubehalten. Auf diese Weise kannst du die zuvor synchronisierten Gruppen einfrieren. Wenn es nicht aktiviert ist, werden bei der nächsten Synchronisierung alle zuvor synchronisierten Gruppen und deren Mitgliedschaften entfernt.

Synchronisation

  1. Page Size: Definiert, wie viele Elemente pro Abfrage synchronisiert werden. Wir empfehlen, die Seitengröße nicht auf einen Wert höher als 120 festzulegen, da Microsoft dies als Limit in ihrer Dokumentation angibt in ihrer Dokumentation. Sie sagen jedoch auch, dass der Wert je nach Abfrage sogar niedriger sein könnte.
  2. Aktivierung: Wenn aktiviert, werden neue und wiederhergestellte Nutzer während der Synchronisierung aktiviert. Andernfalls musst Du den Status der Nutzer manuell auf Aktiv im Benutzerverwaltung setzen.
  3. Verwaiste Benutzer: Wähle aus, was mit Nutzern geschehen soll, die derzeit als aktive Nutzer auf Haiilo existieren, aber nicht mehr im Benutzerverzeichnis vorhanden sind. Wenn Du Ignorieren wählst, bleiben sie unverändert.
  4. Benutzer wiederherstellen: Wenn aktiviert, wird ein Nutzer, der von Haiilo deaktiviert oder gelöscht wurde, aber während der Synchronisierung erneut im Benutzerverzeichnis vorhanden ist, wieder aktiviert. Es ist nicht möglich, anonymisierte Nutzer wiederherzustellen. Ein zuvor anonymisierter Nutzer kann nur als neuer Nutzer erstellt werden.

Ausführung

  1. Wähle die Synchronisierungsfrequenz. Wenn Du Deaktiviert wählst, führst Du die Synchronisierung manuell durch.

Zusätzliche Informationen zur Zuordnung von Profilfeldern

Die Profilfeldzuordnung eines Nutzers kann etwas komplex sein, da die MS Graph API mit JSON-Objekten antwortet, die verschachtelte Daten enthalten können. Dies erfordert die Verwendung einer komplexeren Feldadresssyntax. Wir haben uns für JSONPath entschieden, das den Zugriff auf verschachtelte oder indizierte Eigenschaften sowie die Verwendung von Prädikaten ermöglicht, die für die Erweiterungsauswahl nützlich sind.

MS Graph erfordert auch, dass Du in der Abfrage angibst, welche Eigenschaften der Aufruf zurückgeben soll. Dies erfolgt durch Übermittlung einer Liste von Feldern in den $select oder $expand Parametern. Ein einfacher Feldname wird automatisch wörtlich in die $select Klausel der MS Graph API-Abfrage eingefügt. Die neue Syntax akzeptiert die select/expand-Klausel als optionalen zweiten Teil des Ausdrucks. Die vorherige einfache Feldsyntax ist weiterhin gültig und kann ebenfalls verwendet werden.

Für die zusätzliche Feldzuordnung lautet die Syntax wie folgt:

<jsonpath>[:select/expand-Klausel]

Bitte achte auf die folgende Syntax:

  • Der JSONPath muss mit $. beginnen, um als neue JSONPath-Syntax erkannt zu werden
  • Wenn der JSONPath einen Doppelpunkt enthält, muss der Doppelpunkt mit einem Backslash maskiert werden
  • Wenn der JSONPath mehr als einen Eintrag auswählt, wird nur der erste zurückgegeben
  • Der ausgewählte Wert wird in einen String konvertiert
  • Ein fehlender Wert führt zu einem leeren Profilfeld

Der Pfad kann optional durch einen Doppelpunkt gefolgt werden (der Doppelpunkt darf hier nicht mit einem Backslash maskiert werden) und der ausgewählten/erweiterten Klausel entsprechen, die einem Eintrag des $select oder $expand Parameters oben entspricht. Nur wenn der Wert extensions ist, wird der Abfrageparameter $expand=extensions hinzugefügt. Jeder andere Wert wird als Eintrag für die $select Feldliste interpretiert. Es wird empfohlen, die ausgewählte/erweiterte Klausel zu konfigurieren, um sicherzustellen, dass die API-Antwort das erforderliche Feld enthält.

Beispiele für die Syntax zur Zuweisung von Profilfeldern

  • $.aboutMe:aboutMe
    • Dieser Ausdruck fügt der Abfrage den Parameter $select=aboutMe hinzu. Der JSONPath-Teil wählt das aboutMe -Eigenschaft aus dem Abfrageergebnis aus. Dieser Ausdruck entspricht dem einfachen Feldausdruck aboutMe.
  • $.employeeOrgData.division:employeeOrgData
    • Dieser Ausdruck fügt der Abfrage den Parameter $select=employeeOrgData hinzu. Der JSONPath-Teil wählt die verschachtelte Eigenschaft division der Wurzel employeeOrgData -Eigenschaft aus. Dieser Ausdruck hat kein Äquivalent in einem einfachen Feldausdruck, da es nicht möglich ist, verschachtelte Eigenschaften auf diese Weise auszuwählen.
  • $.extensions[?(@.id=='com.haiilo')].nested.prop1:extensions
    • Dieser Ausdruck fügt der Abfrage den Parameter $expand=extensions hinzu. Der JSONPath-Teil wählt die erste Erweiterung im Wurzelobjekt aus, das eine Eigenschaft id mit dem Wert com.haiilo hat. Aus dieser Erweiterung wird die verschachtelte Eigenschaft nested.prop1 ausgewählt.

Die API-Antwort ist erst nach Ausführung des Synchronisationsjobs bekannt, daher ist nicht bekannt, was ein gültiger JSONPath-Ausdruck tatsächlich auswählt. Derzeit empfehlen wir Administratoren, die Microsoft Graph API manuell mit einem Tool wie Postman abzufragen, dann die JSON-Antwort in ein JSONPath-Auswertungstool zu kopieren und herauszufinden, was der Ausdruck zurückgibt.

War dieser Beitrag hilfreich?