Ihr könnt eure Nutzer auch über Microsoft Graph als Benutzerverzeichnis synchronisieren.

Konfiguration in Microsoft Azure

Eine App muss über das Microsoft Azure-Portal registriert werden.

Die App muss dann über die API-Berechtigungen "Group.Read.All" und "User.Read.All" verfügen (Typ Anwendung). Wie Berechtigungen in Azure für Apps vergeben werden, könnt ihr in diesem Artikel nachschauen.

Hinweis:

Diese Berechtigungen können nur von einem Administrator vergeben werden. Daher ist die Zustimmung des Administrators in dieser Konfiguration erforderlich.

Folgende Berechtigungen müssen für Microsoft Graph innerhalb der API Berechtigungen Einstellungen konfiguriert werden:

Konfiguration in Haiilo

1. Verbindung
2. Benutzer
3. Gruppen
4. Synchronisation
5. Ausführung

Verbindung

Für die Verbindung zu Azure müsst ihr Client-ID, Client-Secret und Tenant aus der Azure App eintragen.

Benutzer

Dann müsst ihr in der Registerkarte “Benutzer” das Attribut für Benutzername eintragen. Wir empfehlen hier die “mail” oder "userPrincipalName" zu verwenden.

Für Benutzerfilter könnt ihr die Standard Microsoft Graph Filter verwenden. Ein Filter auf alle Nutzer, deren Name mit "Dennis" in MS Graph anfängt, sieht z.B. wie folgt aus:

startswith(displayName,'Dennis')

Hinweis:

Es empfiehlt sich den Benutzerfilter leer zu lassen und den Gruppenfilter im Tab "Gruppen" zu nutzen, weil so eine genauere Filterung möglich ist. Wie das geht, erfahrt ihr weiter unten.

Wenn ihr auch die Vorgesetzten mit synchronisieren wollt, müsst ihr zusätzlich die Option "Sync managers" anhaken. Mehr Informationen dazu findet ihr hier.

Die Profilfelder Zuordnung eines Nutzers kann etwas komplex sein, weil die MS Graph API mit JSON-Objekten antwortet, die verschachtelte Daten (nested data) enthalten können. Dies erfordert die Verwendung einer komplexeren Feldadressen Syntax. Wir haben uns für JSONPath entschieden, das den Zugriff auf verschachtelte oder indizierte Eigenschaften und auch die Verwendung von Prädikaten ermöglicht, die für die Auswahl von Erweiterungen nützlich sind.

Hinweis:

MS Graph verlangt auch, dass in der Abfrage angegeben wird, welche Eigenschaften der Aufruf zurückgeben soll. Dies geschieht durch Übergabe einer Feldliste in den Parametern $select oder $expand. Ein einfacher Feldname wird automatisch wortwö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 Feld Syntax ist weiterhin gültig und kann auch verwendet werden.

Für die zusätzliche Feldzuordnung (field mapping) sieht die Syntax wie folgt aus:

<jsonpath>[:select/expand- clause]

Bitte beachtet beim Syntax die folgenden Hinweise:

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

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

Beispiele für Syntax für Profilfelder Zuordnung

$.aboutMe:aboutMe

Dieser Ausdruck fügt der Abfrage den Parameter $select=aboutMe hinzu. Der JSONPath-Teil wird die Eigenschaft aboutMe aus dem Abfrageergebnis auswählen. 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 Stammeigenschaft employeeOrgData aus. Dieser Ausdruck hat keine Entsprechung 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 den Parameter $expand=extensions zur Abfrage hinzu. Der JSONPath-Teil wählt die erste extension innerhalb des Stammobjekts aus, das eine Eigenschaft id mit dem Wert com.haiilo hat. Von dieser Erweiterung wird die verschachtelte Eigenschaft nested.prop1 ausgewählt.

Die API-Antwort ist nicht bekannt, bis der Synchronisierungs Job (sync job) ausgeführt wird, daher ist nicht bekannt, was ein gültiger JSONPath-Ausdruck tatsächlich auswählt.

Wir empfehlen Administratoren derzeit, die Microsoft Graph API manuell mit einem Tool wie Postman abzufragen, die JSON-Antwort in ein JSONPath-Auswertungstool zu kopieren und dort herauszufinden, was der Ausdruck zurück gibt.

Der Rest der Konfiguration funktioniert genauso, wie ihr es von der Konfiguration eines Benutzerverzeichnisses kennt.

Gruppen

Um die Synchronisierung von Gruppen generell zu aktivieren, müsst ihr zunächst die Option "Gruppen synchronisieren" anhaken.

Anschließend werden die Optionen für Gruppenfilter und "Nur Benutzer aus Gruppen" freigeschaltet.

Bei Gruppenfilter könnt ihr die Standard Microsoft Graph Filter verwenden. Ein Filter auf alle Gruppen, die mit "Haiilo" in MS Graph anfangen, sieht z.B. wie folgt aus:

startswith(displayName, 'Haiilo')

Mit der Option "Nur Benutzer aus Gruppen" wird zudem sichergestellt, dass Nutzer nur synchronisiert werden, wenn sie Teil einer synchronisierten Gruppe sind.

Synchronisation

In diesem Reiter könnt ihr Einstellungen zur Synchronisation vornehmen. 

Der Wert in Page Size definiert, wie viele Elemente pro Abfrage synchronisiert werden sollen. Das Limit des LDAP-Protokolls liegt bei 1000. Ihr solltet also keinen höheren Wert wählen.

Die Option Aktivierung ermöglicht, dass neue und wiederhergestellte Nutzer bei der Synchronisierung aktiviert werden. Anderenfalls müsstet ihr den Status der Nutzer in der Benutzerverwaltung manuell auf "Aktiv" setzen.

Hinweis:

Wenn ihr Nutzungsbedingungen in der Administration aktiviert habt, bleiben die neuen und wiederhergestellten Nutzer auf "Versteckt" bis sie diese akzeptiert haben.

Verwaiste Benutzer sind Nutzer, welche derzeit als aktiver Nutzer existieren, aber im LDAP Verzeichnis nicht mehr vorhanden sind. Es besteht die Möglichkeit, die Nutzer in Haiilo Home beim Sync zu ignorieren, deaktivieren oder zu löschen.

Der Punkt Benutzer wiederherstellen ermöglicht es deaktivierte oder gelöschte Nutzer von Haiilo Home wieder zu reaktivieren, wenn diese beim Sync im Benutzerverzeichnis wieder vorhanden sind.

Hinweis:

Es ist nicht möglich anonymisierte Nutzer wiederherzustellen. Der vorher anonymisierte Nutzer kann dann lediglich als neuer Nutzer erstellt werden. Die Anonymisierung ist standardmäßig deaktiviert und kann in den "Allgemeinen Einstellungen" der Administration aktiviert werden.

Ausführung

Hier könnt ihr die Regelmäßigkeit der Synchronisierung konfigurieren. Ihr habt die Optionen einmal täglich (nachts), mehrmals täglich (alle vier Stunden) und einmal stündlich.