Office 365 Kontakt Synchronisation auf Exchange Online Mailboxen mit PowerShell und Office 365 Graph API

Von einem Kunden haben wir die folgende Anforderung erhalten:

• Beim Eingang eines Telefon-Anrufs auf dem Smartphone eines Benutzers sollen die Kontakt-Details des Anrufers angezeigt werden (ohne dass der Mitarbeiter diesen Kontakt selbst pflegen muss in Outlook 😊)
• Die Mitarbeiter haben stets eine komplette Kontakt-Liste aller «internen Mitarbeiter» aus der Exchange Online GAL auf Ihrem Mobile, respektive im Outlook Mobile Client zur Verfügung, d.h. ruft ein Mitarbeiter an, so wird der Name des Anrufers angezeigt
• Als weitere Anforderung wurde gestellt, dass die Lösung, mit sämtlichen Schnittstellen, vom Kunden selbst betrieben werden soll. Somit fielen auch sämtliche «pfannenfertigen» Lösungen von Drittanbietern ins Wasser.

Für den Endbenutzer steht in Office 365, respektive Exchange Online zwar eine Globale Adressliste (GAL) sowie andere zentrale Adresslisten zur Verfügung, deren Nutzung hat aber v.a. mit dem Smartphone zwei gewichtige Nachteile:

• Die Anruferkennung auf dem Smartphone funktioniert nur auf lokal synchronisierte Kontakte jedoch nicht auf Kontakte aus der GAL
• Der Zugriff aufs GAL funktioniert nur mit einer Internetverbindung

Aufgrund dieser Lücken entstand die Anforderung, einen definierten Benutzerkreis aus Office 365 Benutzern regelmässig in die persönlichen Kontakte der Benutzer-Mailboxen synchronisieren zu können. Wie das Bild am Anfang des Blogeintrages zeigt, geht das natürlich auch mit «normalen» Outlook Kontakten und nicht bloss mit GAL Benutzereinträgen.

Somit kann das Script natürlich auch sonstige Outlook Kontakte, zum Beispiel aus einer zentralen Mailbox, auf die einzelnen Office 365 Mailboxen/Benutzer synchronisieren. Im erwähnten Kundenbeispiel war dies aber keine Anforderung. Andere Kunden nutzen den Synchronisationsmechanismus aber für Ihre Kunden-/Lieferantenadressen, welche zentral gepflegt werden und so über die Synchronisation an die Mitarbeiter verteilt werden.

Die Outlook Mobile App bietet die Funktionalität, Kontakte aus der persönlichen Mailbox in das Adressbuch des Smartphones zu synchronisieren, und somit die Anforderung für die Anruferkennung zu erfüllen. Diese Option kann beim Outlook App unter Einstellungen -> Office 365 Account -> Synchronisation eingeschalten werden. Somit hat der Benutzer selbst die Wahl ob er dieses Feature auf seinem Smartphone nutzen will oder nicht 😉.

Als Daten-Quelle für die Kontakte der Globalen Adressliste haben wir alle aktiven und lizenzierten Office 365 Benutzer genommen. Als Methode zur Erstellung der Kontakte innerhalb der Mailboxen wurde die Microsofts Graph API ausgewählt. Eine Übersicht, was MS Graph ist und was es kann gibt es hier: MS Graph Concept Overview

Die MS Graph API erlaubt es, persönliche Kontakte von einzelnen Benutzern anzeigen zu lassen, zu verändern oder zu löschen, sofern man zuvor einen entsprechenden Schlüssel für den Zugriff erhalten hat. Die MS Graph API baut auf dem Oauth 2.0 Authentifizierungs-Protokoll auf. Details dazu gibt es hier: Auth-Flow

Hinweis: Wenn du die Möglichkeiten des MS Graph APIs gerne ausprobieren möchtest, kannst du dich auf dem Graph Explorer mit deinem Office 365 Account einloggen und dich über die vielfältigen Funktionalitäten informieren und auch gleich ausprobieren. Es ist beispielsweise möglich, über den Graph Explorer einen neuen Kontakt zu erstellen, welcher nach erfolgreicher Erstellung auch sofort in der persönlichen Mailbox erscheint. Hier ein Beispiel der Anzeige des eigenen Profils:

Um eine Synchronisierung von Kontaktinformationen braucht es zunächst eine publizierte Enterprise Application auf Azure im Kontext von Azure AD, mit einer eindeutigen AppID und einem Secret. Danach werden die nötigen Berechtigungen gesetzt und vererbt, damit die MS Graph API die notwendigen Aktionen, also das Erstellen und Löschen eines Kontakts, ohne manuelle Userinteraktion unternehmen kann. Hilfreich war dabei die von Microsoft zur Verfügung gestellte Dokumentation.

Als Voraussetzung für Interaktionen mit der MS Graph API gilt es als erstes eine Authentifizierungs-Anfrage abzusetzen, um einen Authentifizierungs-Token zu erhalten. Dieser hat eine zeitlich beschränkte Gültigkeit von genau einer Stunde. Die MS Graph API nimmt Anfragen in Form von sogenannten Web-Requests entgegen. Diese müssen einer spezifischen Formatierung im JSON-Format entsprechen und sind nur mit dem erwähnten gültigen Authentifizierungs-Token möglich.

In einem nächsten Schritt wurde die nötige Skript-Intelligenz entwickelt, welche die aktiven Benutzer mit den relevanten Informationen (Vorname, Nachname, Telefonnummern, E-Mailadresse usw.) mit den aktuell vorhandenen Kontakten innerhalb der Benutzer-Mailboxen vergleicht und nach Bedarf entsprechend Kontakte via MS Graph API löscht oder erstellt.

Um zu verhindern, dass das Skript ungewollt persönliche Kontakte löscht, welche nicht angefasst werden sollen, wurde definiert, dass nur Kontakte mit einer vom Kunden bestimmten Outlook Kategorie von der Skript-Logik erfasst werden. Dies stellt zum einen sicher, dass ausgetretene Mitarbeiter aus der Kontaktliste gelöscht werden, neue erfasst werden, jedoch persönlich geführte Kontakte nicht verändert werden.

Damit die Performance bei einer grösseren Menge Benutzer/Kontakte stimmt, wurde durch Parallelisierung beim Abgleich der persönlichen Kontakte die Synchronisierungs-Performance entsprechend erhöht, so dass auch bei der initialen Synchronisation sichergestellt ist, dass die Laufzeit unter einer Stunde bleibt (der Token ist ja initial nur 60 Minuten gültig 😉)

Damit das Debugging nicht zu kurz kommt, wurde ein Logging-Modul eingebaut, welches die Vorgänge auf sämtlichen Mailboxen in einem Logfile mit Zeitstempel nachvollziehbar sammelt und speichert.

Bei regelmässigen Synchronisations-Läufen ist durch die Abgleichs-Funktion sichergestellt, dass nur an der Quelle veränderte Objekte in den persönlichen Kontakten verändert werden und der Abgleich aufgrund des reduzierten Synchronisierungs-Aufwands innert Minuten oder bei weniger Mitarbeitern sogar nur in Sekunden abgeschlossen ist.

Fazit

Microsoft stellt mit der MS Graph API eine vielfältige und sichere Schnittstelle zur Verfügung, mit enormem Potential für viele weitere Abenteuer 😉