Microsoft-Konfiguration
Eine App muss über das Azure-Portal > App-Registrierungen registriert werden. Die App muss über die API-Berechtigungen "Group.Read.All" und "User.Read.All" verfügen (Typ Anwendung). Diese Berechtigungen können nur von einem Administrator vergeben werden. Daher ist die Zustimmung des Administrators in dieser Konfiguration erforderlich. Wie Berechtigungen in Azure für Apps vergeben werden, haben wir bereits in diesem Artikel erklärt.
Folgende Berechtigungen müssen für MS Graph innerhalb der Azure AD - API permissions Einstellungen konfiguriert werden:
| API / Permissions Name | Type |
| Group.Read.All | Application |
| User.Read.All | Application |
| User.Read | Delegated |
Haiilo Konfiguration
Innerhalb von Haiilo ist die Konfiguration dem LDAP-Protokoll sehr ähnlich. Unter der Administration wählt ihr den Reiter "Benutzerverzeichnisse" und wählt bei Typ "Microsoft Graph" aus.
Die folgenden Felder müssen konfiguriert werden, um die Verbindung herzustellen. Der Tenant Identifier ist zu finden im Azure-Portal > Eigenschaften:
In der Registerkarte "Benutzer" wird festgelegt, ob "mail" oder "userPrincipalName" als Kennung für die Benutzer verwendet werden soll:
Zum Filtern von Benutzer und Gruppen könnt Ihr Microsoft Graph Filter verwenden.
Beispiel:
Filtere alle Gruppen, die mit 'COYO_' anfangen
startswith(displayName, 'COYO_')
Um eigene Filter zu schreiben und zu testen, empfiehlt sich der Microsoft Graph Explorer.
Hinweis:
Einige Filter Parameter funktionieren nicht mit der Graph API, wie man es erwarten würde. Beispielsweise funktioniert die Query Funktion endsWith(mail,'@coyo4.com') nicht mit dem /users Endpunkt. Das ist ein Problem auf Microsoft Seite, welches wir leider nicht beheben können.
Der Rest der Konfiguration funktioniert genauso, wie ihr es von der Konfiguration einer Benutzersynchronisation, z. B. über das LDAP-Protokoll, kennt.
Syntax für die Zuordnung von Benutzer Profilfeldern in MS Graph
Die Profilfeld Zuordnung eines Benutzers wird normalerweise durch Angabe eines einfachen Feldnamens konfiguriert.
Die MS Graph API antwortet jedoch mit JSON-Objekten, die verschachtelte Daten enthalten können (nested data). 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.
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.
Syntax
Die vorherige einfache Feld Syntax ist weiterhin gültig und kann 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:
- 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 eine Zeichenkette umgewandelt
- 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
Einfacher Ausdruck
$.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.
Verschachtelte Eigenschaften
$.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.
Prädikate
$.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.
Ausdrücke testen
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 MS Graph API manuell mit einem Tool wie Postman abzufragen, die JSON-Antwort in ein JSONPath-Auswertungstool wie JSONPath Online Evaluator zu kopieren und dort herauszufinden, was der Ausdruck zurückgibt.
Hinweis:
Bitte trefft Vorsichtsmaßnahmen, um nicht gegen Datenschutzgesetze zu verstoßen, indem ihr sensible Benutzerdaten in öffentliche Online-Tools kopiert!