Gruppensynchronisation

Die Gruppensynchronisation (GroupSync) gleicht die Verzeichnisgruppen einer Datasource mit dem Verzeichnis ab. Verzeichnisgruppen sind Gruppen aus Active Directory, Entra ID oder SCIM, die in primedocs onboardet wurden. Der Name einer Gruppe folgt danach dem Verzeichnis, und ihr Sync-Status zeigt, ob das Verzeichnis sie noch kennt. Gruppen, die nicht mehr gefunden werden, lassen sich optional automatisch löschen, in denselben Stufen wie beim Offboarding von Benutzern. App-Gruppen von primedocs sind nie betroffen.

Die Gruppensynchronisation ist von der Benutzersynchronisation unabhängig: Sie hat einen eigenen Schalter, einen eigenen Zeitpunkt des letzten Laufs und eine eigene Konfiguration (GroupSyncConfig). Die UserSyncConfig wirkt nicht auf Gruppen.

Voraussetzungen

• Für die Datasource ist ein Verzeichnis-Konnektor konfiguriert (Active Directory, Microsoft Graph / Entra ID oder SCIM), siehe Identitätsanbieter. Ohne Konnektor wird die Gruppensynchronisation übersprungen.
• Die Datasource wird nicht ohne Application permissions betrieben. In diesem Betrieb fragt primedocs Microsoft Graph nicht ab, die Gruppensynchronisation wird übersprungen, und Gruppen werden weder markiert noch gelöscht.
• Der JobHost läuft regelmässig, etwa als geplante Aufgabe, siehe Background Jobs konfigurieren. Die Gruppensynchronisation läuft nur im JobHost.

Aktivieren

Die Gruppensynchronisation ist standardmässig ausgeschaltet. Sie wird über die Einstellung GroupSyncActivated eingeschaltet. Fehlt die Einstellung, bleibt sie aus, auch wenn die Benutzersynchronisation aktiv ist. Eingeschaltet wird an einer dieser Stellen:

• Web-Admin: unter Integrationen › Benutzerdaten › Gruppensynchronisation in der Karte Sync-Pipeline den Schalter Aktiviert einschalten und speichern.
• Admin API: PUT .../Admin/Settings/GroupSync mit activated und der bestehenden Konfiguration in xml, denn ein fehlendes xml entfernt die Konfiguration, siehe Admin API.

Nach einem vollständigen Lauf speichert primedocs den Zeitpunkt in GroupSyncLastRun. Der Web-Admin zeigt ihn als letzten Lauf an.

Konfiguration

Die Konfiguration steht im XML der Einstellung GroupSyncConfig. Sie wird im Web-Admin in der Karte Gruppen-Sync-XML visuell oder als XML bearbeitet. Ohne Konfiguration gelten die Standardwerte, und nicht mehr gefundene Gruppen werden nur als «Fehler» markiert, aber nie gelöscht.

<GroupSyncConfig batchSize="10" syncTimeoutInSeconds="60">
  <AutomaticGroupDeletion mode="enabledWithoutAutomaticDeletion">
    <StatusChangesAfterUnavailabilityDuration>
      <SetToPendingDeletion days="30" />
      <SetToFlaggedForDeletion days="60" />
    </StatusChangesAfterUnavailabilityDuration>
  </AutomaticGroupDeletion>
</GroupSyncConfig>

Attribut / Element	Standard	Beschreibung
batchSize	10	Anzahl Gruppen, die der Job in einem Stapel verarbeitet. Erlaubt sind 1 bis 100, andere Werte fallen auf den Standard zurück.
syncTimeoutInSeconds	60	Zeit, nach der eine Gruppe, die im Status «Synchronisierung läuft» hängen geblieben ist, auf «Zeitüberschreitung» gesetzt und erneut abgeglichen wird. Erlaubt sind 10 bis 3600, andere Werte fallen auf den Standard zurück.
AutomaticGroupDeletion	—	Automatische Löschung nicht mehr gefundener Gruppen. Fehlt das Element, wird nichts gelöscht.
mode	disabled	disabled: keine automatische Löschung. enabledWithoutAutomaticDeletion: Gruppen werden nur markiert. enabled: Gruppen werden markiert und danach gelöscht.
SetToPendingDeletion days	30	Tage ohne Fund im Verzeichnis bis zum Status «Löschung ausstehend»
SetToFlaggedForDeletion days	60	Tage ohne Fund im Verzeichnis bis zum Status «Zur Löschung markiert»

Tage unter 1 fallen auf die Standardwerte 30 und 60 zurück. Als mode gelten nur die drei genannten Namen. Web-Admin und Admin API speichern eine Konfiguration mit ungültigem XML oder einem unbekannten Modus nicht. Liegt dennoch eine unlesbare Konfiguration vor, verwendet der Job die Standardwerte für Stapelgrösse und Timeout, und die automatische Löschung bleibt ausgeschaltet. Der Job schreibt dazu eine Warnung ins Log.

Ablauf

Ein Lauf gleicht alle Verzeichnisgruppen ab, die nicht vom Sync ausgeschlossen sind. Ein Intervall wie bei der Benutzersynchronisation gibt es nicht.

1. Der Job prüft, ob der Verzeichnis-Konnektor erreichbar ist. Ist er es nicht, schreibt der Job nichts und der Lauf gilt als fehlgeschlagen. Beim SCIM-Konnektor gibt es diese Prüfung nicht.
2. Gruppen, die länger als syncTimeoutInSeconds im Status «Synchronisierung läuft» stehen, werden auf «Zeitüberschreitung» gesetzt und im selben Lauf erneut abgeglichen.
3. Die Gruppen werden in Stapeln von batchSize abgeglichen, die am längsten nicht synchronisierten zuerst. Für jede Gruppe fragt der Job den Konnektor über die SID ab, ohne Principal-Cache.
4. Sind alle Gruppen abgeglichen, speichert der Job GroupSyncLastRun und startet die automatische Gruppenlöschung.

Ändert ein anderer Prozess gleichzeitig dieselben Gruppen, bricht der Lauf ab. Er gilt dann als unvollständig: GroupSyncLastRun bleibt unverändert, und es folgt keine Löschung. Der JobHost wiederholt den Lauf, siehe JobHost.

Ergebnis pro Gruppe

Fall	Sync-Ergebnis	Wirkung
Gruppe im Verzeichnis gefunden	OK	Der Name aus dem Verzeichnis wird übernommen, der Zeitpunkt des letzten erfolgreichen Syncs aktualisiert. Eine anstehende automatische Löschung wird aufgehoben.
Nicht gefunden, oder die SID gehört im Verzeichnis nicht zu einer Gruppe	Fehler	Name und Zeitpunkt des letzten erfolgreichen Syncs bleiben erhalten. Nur solche Gruppen erfasst die automatische Löschung.
Abfrage fehlgeschlagen, etwa wegen eines Verbindungs- oder Berechtigungsfehlers oder mehrdeutiger Treffer	Warnung	Name, Zeitpunkt und Löschstatus bleiben unverändert. Der Grund steht im Sync-Bericht. Die automatische Löschung erfasst die Gruppe nicht.
Bekannte System-SID (Everyone, Authenticated Users) oder die interne SID für anonymes Connect	—	Die Gruppe wird ohne Abfrage auf «Vom Sync ausgeschlossen» gesetzt und nie gelöscht.

Nach dem ersten Lauf ist der Name aus dem Verzeichnis massgebend. Eine Umbenennung in primedocs überschreibt der nächste Lauf wieder. Gruppen, die beim Verzeichniswechsel eine Platzhalter-SID erhalten haben, sind ebenfalls vom Sync ausgeschlossen.

Sync-Status und Bericht

Den Stand pro Gruppe zeigen:

• Web-Admin: In der Gruppenliste die Spalte Sync-Status mit Filter. Bei «Fehler» nennt ein Tooltip, wann die Gruppe zuletzt gefunden wurde, bei laufender Löschung erscheinen «Löschung ausstehend» und «Zur Löschung markiert». Die Detailseite einer Verzeichnisgruppe zeigt im Bereich Synchronisation Sync-Status, Sync-Ergebnis, letzten Sync, letzten erfolgreichen Sync, den Status der automatischen Löschung und den Sync-Bericht. Ist eine Gruppe zur Löschung markiert und lautet das letzte Ergebnis «Fehler», erscheint ein Warnhinweis.
• Admin API: Die Felder syncStatus, syncResult, syncTimeUtc, syncLastSucceededOnUtc und syncAutomaticDeletionStatus bei den UserGroups, in der Detailansicht zusätzlich syncReport.

Der Sync-Bericht hat dasselbe JSON-Format wie bei der Benutzersynchronisation und enthält einen Eintrag mit der Quelle PrincipalConnector.Group. Solange eine Gruppe keinen abgeschlossenen Abgleich hat, liefert die Admin API kein Sync-Ergebnis (null).

Automatische Gruppenlöschung

Die automatische Gruppenlöschung arbeitet in denselben Stufen wie die automatische Benutzerlöschung. Gerechnet wird ab dem letzten erfolgreichen Sync der Gruppe, hat sie noch nie einen, ab ihrer Erstellung in primedocs:

1. Nach SetToPendingDeletion Tagen ohne Fund erhält die Gruppe den Status «Löschung ausstehend» (PendingDeletion).
2. Nach SetToFlaggedForDeletion Tagen erhält sie den Status «Zur Löschung markiert» (FlaggedForDeletion).
3. Im Modus enabled wird eine markierte Gruppe in einem späteren Lauf gelöscht. Im Modus enabledWithoutAutomaticDeletion bleibt es bei der Markierung.

Gelöscht wird wie beim manuellen Löschen: Die Gruppe wird samt ihren Berechtigungen, Rollen und Mitgliedschaften aus primedocs entfernt. Im Verzeichnis bleibt sie bestehen und lässt sich erneut onboarden. Die entfernten Berechtigungen und Rollen müssen danach neu vergeben werden.

Leitplanken

• Die Löschung läuft nur direkt nach einem vollständig abgeschlossenen Lauf der Gruppensynchronisation. War der Verzeichnis-Konnektor nicht erreichbar, wurde der Lauf abgebrochen oder ist die Gruppensynchronisation ausgeschaltet, wird weder markiert noch gelöscht.
• Erfasst werden nur Gruppen, deren letzter abgeschlossener Abgleich das Ergebnis «Fehler» hatte. Gruppen mit «Warnung», vom Sync ausgeschlossene, noch nie synchronisierte und gerade laufende Gruppen sind nie betroffen, App-Gruppen ebenfalls nie. Eine bereits markierte Gruppe wird nicht gelöscht, wenn der letzte Abgleich nur eine Warnung ergab.
• Gelöscht wird erst in einem Lauf nach der Markierung. Der Status «Zur Löschung markiert» ist so mindestens einen Lauf lang sichtbar.
• Wird eine Gruppe wieder gefunden, setzt die Gruppensynchronisation den Löschstatus zurück.

Verzeichniswechsel

Bei einem Wechsel des Verzeichnisses, etwa von Active Directory zu Entra ID, erhalten die Gruppen neue SIDs. Ohne vorherige Migration der SIDs findet der Konnektor die Gruppen nicht mehr, sie erhalten das Ergebnis «Fehler» und werden bei aktiver Löschung nach Ablauf der Fristen samt ihren Berechtigungen gelöscht. Vor dem Wechsel deshalb den Verzeichniswechsel im Web-Admin durchführen oder den Modus auf enabledWithoutAutomaticDeletion stellen.

tipp

Eine neue Konfiguration zuerst mit enabledWithoutAutomaticDeletion betreiben und die markierten Gruppen prüfen, bevor auf enabled umgestellt wird. Der visuelle Editor im Web-Admin beginnt beim Einschalten der Bereinigung mit diesem Modus.

JobHost

Ein Lauf des JobHost ohne Parameter führt die Gruppensynchronisation direkt nach der Benutzersynchronisation aus. Einzeln wird sie mit dem Verb GroupSync gestartet:

...\primedocs.JobHost.exe GroupSync

Short	Long	Required	Default	Beschreibung
-d	--DataSourceId	false	null	GUID der Zieldatenbank auf dem Server. Wenn weggelassen, wird der GroupSync auf allen konfigurierten Datenbanken ausgeführt.

Ist der Verzeichnis-Konnektor nicht erreichbar oder bricht der Lauf ab, wiederholt der JobHost ihn gemäss seiner Konfiguration für Wiederholungen. Scheitert auch der letzte Versuch, endet der JobHost mit dem Exitcode 1, und weitere Datasources werden in diesem Lauf nicht mehr abgeglichen. primedocs.JobHost.exe help GroupSync zeigt die Parameter an.