Systeme

Microsoft 365 Konnektor

Die Microsoft Graph API ist eine REST-basierte Schnittstelle für den Zugriff auf Microsoft 365-Daten. Dieser Konnektor ermöglicht die Authentifizierung, den Zugriff und die Synchronisation mit der Graph API. Er stellt ein Datenschema mit speziellen Funktionen und Parametern bereit, insbesondere für die Verarbeitung von Terminen, Aufgaben, Kontakten, E-Mails und SharePoint-Inhalten. Ziel ist die bidirektionale Integration mit Microsoft 365, um Unternehmensdaten wie Kalender, Aufgaben und Kommunikation zentral mit anderen Systemen zu synchronisieren.

Einrichtung

Für die Einrichtung der Verbindung ist eine registrierte Anwendung in Microsoft Entra ID (Azure Active Directory) erforderlich. Diese Anwendung stellt die Authentifizierungsdaten bereit, die im Konnektor verwendet werden.

Registrierung der Anwendung

Melden Sie sich im Microsoft Entra ID Portal an:
https://go.microsoft.com/fwlink/?linkid=2083908
Wählen Sie „Neue Registrierung“.
Geben Sie einen Namen für die Anwendung an, z. B. „Syncler Graph API Integration“.
Legen Sie fest, welche Kontotypen Zugriff haben (meist „Konten in diesem Organisationsverzeichnis“).
Optional: Tragen Sie eine Umleitungs-URI (Redirect URI) ein. Diese wird bei bestimmten Authentifizierungsverfahren benötigt.
Nach der Registrierung werden angezeigt:
- Anwendungs-ID (Client-ID)
- Verzeichnis-ID (Mandanten-ID)

Diese Werte tragen Sie in die entsprechenden Felder der Systemeinstellungen des Konnektors ein.

Authentifizierungsverfahren

Die Graph API unterstützt mehrere Authentifizierungsverfahren, die unterschiedliche Sicherheits- und Berechtigungsmodelle abbilden. Der Konnektor implementiert folgende Verfahren:

Client-Secret

Das Client-Secret-Verfahren ist eine serverseitige Anmeldevariante.
Sie basiert auf einem geheimen Schlüssel (Secret), der im Azure-Portal erzeugt wird.

Öffnen Sie in der registrierten Anwendung den Bereich „Zertifikate & Geheimnisse“.
Klicken Sie auf „Neuer geheimer Clientschlüssel“.
Definieren Sie eine Gültigkeit (z. B. 6 oder 12 Monate).
Klicken Sie auf „Hinzufügen“ und kopieren Sie den angezeigten Schlüssel direkt in den Konnektor.

Hinweis: Der Wert kann später nicht mehr eingesehen werden.
Tragen Sie den Wert im Feld Client-Geheimschlüssel in den Systemeinstellungen ein.
Setzen Sie den Scope-Wert auf:
https://graph.microsoft.com/.default

Dieses Verfahren unterstützt ausschließlich Anwendungsberechtigungen (Application Permissions).

Administrator Refresh-Token

Bei diesem Verfahren erfolgt die Authentifizierung über einen delegierten Benutzerkontext, also im Namen eines Benutzers. Hierbei werden die Berechtigungen der registrierten Anwendung durch einen Administrator bestätigt und gespeichert.

Vorgehen:

Öffnen Sie in Syncler die Registerkarte Microsoft 365 OAuth 2.0.
Starten Sie den Freigabeprozess.
Melden Sie sich mit einem administrativen Microsoft 365-Konto an.
Erteilen Sie der Anwendung die erforderlichen Berechtigungen.

Die Verbindung speichert das erhaltene Refresh-Token verschlüsselt und verwendet es für die automatische Token-Erneuerung.

Unterstützte Berechtigungstypen: Delegierte Berechtigungen (Delegated Permissions).

Beispielhafte Scope-Werte:

offline_access Calendars.ReadWrite Contacts.ReadWrite Tasks.ReadWrite

Ein Refresh-Token muss bei Änderungen des Benutzerpassworts neu generiert werden.

Benutzer Refresh-Token (Portalunterstützung)

Dieses Verfahren ermöglicht es, Benutzerzustimmungen über ein externes Portal (z. B. Sage CRM) einzuholen. Damit können mehrere Benutzer gleichzeitig autorisiert werden, ohne dass individuelle Anmeldungen über die Syncler-Oberfläche notwendig sind.

Das externe Portal greift über die API-Endpunkte GraphRefreshToken und DeleteGraphRefreshToken zu.
Der Autorisierungscode wird übergeben und intern in einen Refresh-Token umgewandelt.
Der Refresh-Token wird verschlüsselt gespeichert und kann weder exportiert noch extern eingesehen werden.

Der Scope für die Autorisierung muss mit dem im System hinterlegten Scope identisch sein, damit ein gültiger Access-Token erstellt werden kann.

API-Berechtigungen

Die folgenden Berechtigungen sind erforderlich, abhängig von den genutzten Funktionen:

Bereich	Berechtigung	Typ
Kalender	Calendars.ReadWrite	Anwendung / Delegiert
Kontakte	Contacts.ReadWrite	Anwendung / Delegiert
Benutzer	User.Read.All	Anwendung
Gruppen	GroupMember.Read.All	Anwendung
Aufgaben	Tasks.ReadWrite	Delegiert
E-Mail	Mail.ReadWrite, Mail.Send	Anwendung / Delegiert
SharePoint	Files.ReadWrite.All	Anwendung / Delegiert

Administratorrechte sind erforderlich, um Anwendungsberechtigungen freizugeben.

Funktionen

Schema ermitteln

Das Datenschema wird dynamisch aus den Metadaten der Graph API (https://graph.microsoft.com/v1.0/$metadata) erzeugt. Es werden nur geprüfte Objekte und Felder bereitgestellt. ID-Felder und Änderungsinformationen (z. B. lastModifiedDateTime) werden automatisch erkannt und gekennzeichnet.

Das Schema wird teilweise erweitert, um zusätzliche Felder wie isDeleted oder user bereitzustellen, die für Synchronisationen benötigt werden.

Lesen von Daten

Das Lesen erfolgt über Universal Syncs oder spezialisierte Syncs. Unterstützt werden Abfragen per Änderungsdatum sowie vollständige Datensynchronisationen.
Delta-Abfragen ermöglichen eine Synchronisation nach Änderungstoken, wodurch auch Löschungen erkannt werden. Dafür müssen spezialisierte Syncs eingesetzt werden. Die Graph API ruft Ereignisse, Aufgaben und Kontakte pro Benutzer ab. Die Benutzer werden über Systemeinstellungen (z. B. Benutzerfilter oder Benutzerliste) definiert.

Für Aufgaben wird ausschließlich die Standardliste des jeweiligen Benutzers synchronisiert.

Schreiben von Daten

Das Schreiben erfolgt über den Benutzer, der für das Lesen verwendet wurde. Beim Anlegen von Ereignissen wird der Benutzer aus dem Feld Organisator oder user übernommen. Ungültige Werte führen zu einem Fehler. Das Feld "user" für Aufgaben, Kontakte oder Nachrichten legt das Zielpostfach fest.

Einstellungen

Kalender

Einstellung	Beschreibung
Anzahl vergangener Monate	Definiert den Beginn des Zeitfensters für Delta-Synchronisationen.
Anzahl zukünftiger Monate	Definiert das Ende des Zeitfensters.
Bevorzugte Outlook Zeitzone	Steuert die Verarbeitung von Datumswerten. Ohne Einstellung wird UTC verwendet.
Anzahl Tage bis Aktualisierung des Zeitfensters	Legt fest, in welchem Intervall eine vollständige Prüfung durchgeführt wird.

Microsoft 365 OAuth 2.0

Einstellung	Beschreibung
Authentifizierungsmethode	Auswahl des Verfahrens (Client-Secret, Refresh-Token, Benutzer-Token)
Verzeichnis-ID (Mandant)	Mandantenkennung der registrierten Anwendung
Anwendungs-ID (Client)	Client-ID der registrierten Anwendung
Client-Geheimschlüssel	Secret für die App-Authentifizierung
Redirect URI	Weiterleitungs-URI für OAuth-Freigaben
Ist Public Client	Gibt an, ob die Anwendung ohne Secret (Public Client) arbeitet
Scopes	Anzufordernde Berechtigungen

Benutzerauswahl

Einstellung	Beschreibung
Methode für Auswahl von Benutzern	Auswahlverfahren: Filter, Liste, Gruppe oder Benutzerzustimmung.
Filter für Benutzer	Definiert Benutzer in OData-Syntax, z. B. `userType eq 'Member'`.
Benutzerliste	Semikolongetrennte Liste von E-Mail-Adressen.
Gruppenname für Benutzerauswahl	Name einer Microsoft 365-Gruppe.
Vorhandene Benutzerzustimmungen	Schreibgeschütztes Feld, zeigt aktive Zustimmungen.

Besonderheiten

Aufgaben und Benutzerzustimmungen

Aufgaben erfordern immer eine Benutzerzustimmung über OAuth. Die Redirect-URI muss auf eine Seite zeigen, die den Autorisierungscode entgegennimmt (z. B. CustomPages/MicrosoftConsent.asp). Öffentliche Clientflows müssen aktiviert sein.

Ereignisse

Ereignisse, Aufgaben und Kontakte werden über eine Liste von Benutzern ermittelt. Da die ID eines Ereignisses abhängig vom Benutzer ist, über den die Abfrage ausgeführt wurde, wird die Antwort wie folgt verarbeitet. Wenn der aktuelle Benutzer gleich dem Organisator des Ereignisses ist, wird der Datensatz übernommen und die ID z.B. in Datensatz-Abbildungen verwendet. Wenn der aktuelle Benutzer nicht gleich dem Organisator ist (nur Teilnehmer) und der Organisator aber durch die Benutzerauswahl erfasst wird, wird der Datensatz verworfen, damit keine Dubletten angelegt werden (Synchronisation über den Organisator). Wenn der Organisator nicht durch die Benutzerauswahl erfasst wird, wird der Termin übernommen und alle Teilnehmer entfernt, die in der Benutzerauswahl enthalten sind und nicht dem aktuellen Benutzer entsprechen. Dieses Verfahren stellt sicher, dass auch geteilte Ereignisse identifiziert werden können und keine Datensätze doppelt verarbeitet werden.

Delta-Funktion

Die Delta-Funktion erlaubt inkrementelle Synchronisationen. Ein gespeicherter Änderungstoken ermöglicht den Abruf nur geänderter oder gelöschter Datensätze. Das Zeitfenster verschiebt sich täglich, um eine kontinuierliche Synchronisation zu gewährleisten.

Gelöschte Ereignisse werden über isDeleted = true markiert.

Delta-Abfragen benötigen einen spezialisierten Sync.

Abfragen aus Transformation

Eine Abfrage an den Konnektor überprüft immer die gesamte Benutzerauswahl, was zu viele zusätzliche Abfragen führen kann. Eine Datenabfrage aus der Transformation "Daten abfragen" kann in Feldnotation einen einzelnen Datensatz abfragen. Dies kann auch mit einer Benutzereinschränkung ergänzt werden, da sonst alle Benutzer geprüft werden müssen.

Beispiel:

id|:|ABC|;|
oder
id|:|ABC|;|user|:|benutzer@domain.de|;|

SharePoint-Zugriff

Der Konnektor unterstützt den Zugriff auf folgende Schemaobjekte:

Objekt	Beschreibung
site	SharePoint-Seite, ggf. mit Unterseiten
drive	Dokumentenbibliothek oder Benutzer-OneDrive
driveItem	Datei oder Verzeichnis (Inhalt über „FileContent“ als Base64 verfügbar)

Für den Zugriff auf Dateien steht der spezielle Sync "Universal Sync für Microsoft Dateisystemobjekte" zur Verfügung. Dieser ermöglicht die Definition einer Site oder eines Drive mit einem Parameter. Hier muss die ID hinterlegt werden. Dieser Sync ermöglicht außerdem eine Änderungserkennung für die Site oder Drive. Als Quelle werden driveItems verwendet. Dieser Sync stellt automatisch auch den Dateiinhalt zur Verfügung.

Filterparameter

Bei anderen Zugriffen muss der Dateiinhalt explizit mit dem Filterparameter "content" angefordert werden. Mit dem Filterparameter "children" werden die untergeordneten driveItems zu einem driveItem ausgelesen. Dies kann genutzt werden, um den Verzeichnisinhalt auszulesen. Mit dem Filterparameter "path" kann auch direkt ein kompletter Pfad zu den driveItems übergeben werden.

site

siteid: Einzelne Seite, entspricht Lesen per ID
path: Seite wird über den Pfad aufgelöst. Dies erfordert den zusätzlichen Filterparameter "hostname"

drive

siteId: Eine Seite wird zum Abrufen von drives immer benötigt. Mit "root" wird die Standardwebseite der Organisation verwendet.
driveid: Einzelnes Laufwerk, entspricht Lesen per ID
path: Wählt ein Laufwerk über den Pfad aus. Dieser wird mit der webUrl (Abschluss) verglichen
name: Wählt ein Laufwerk über den Namen aus.

driveItem

siteId: Einzelne Seite, Seite oder Laufwerk müssen angegeben werden.
driveId: einzelnes Laufwerk, Seite oder Laufwerk müssen angegeben werden.
itemId: einzelnes Item, z.B. Verzeichnis, ohne wird "root" verwendet
path: zur Auswahl eines Verzeichnisses
children: Liefert die Liste der untergeordneten Einträge
content: Der Dateiinhalt wird zusätzlich abgerufen und als "FileContent" bereitgestellt.

E-Mail-Synchronisation

E-Mails werden über die Objekte message und mailfolder synchronisiert. Der Sync „Universal Sync für Microsoft Nachrichten“ unterstützt Nachbearbeitungen und die Definition von Postfächern und Ordnern.

Mit dem Feld HtmlBodyInlineImages wird eine Version des HTML-Inhalts bereitgestellt, bei der eingebettete Bilder (CIDs) korrekt aufgelöst werden.

Syncs für Termine, Aufgaben und Kontakte

Für eine vollständige Synchronisation stehen spezialisierte Syncs zur Verfügung, die auch Serien und Löschungen berücksichtigen.