So löschen Sie inaktive Benutzerkonten in Matrix Synapse über die Admin-API

In Matrix Synapse wird zwischen dem Löschen und dem Deaktivieren eines inaktiven Kontos unterschieden . Die dokumentierte Admin-API von Synapse bietet keinen allgemeinen Endpunkt zum endgültigen Löschen, der alle mit einem Benutzer verknüpften Datenbankeinträge entfernt. Der empfohlene administrative Workflow sieht vor, ein Konto zu identifizieren, es zu überprüfen und anschließend den Deaktivierungsendpunkt aufzurufen. Optional können Sie festlegen, dass Profilinformationen entfernt und der Benutzer als gelöscht markiert werden soll."erase": true

Ein gutes Ergebnis ist daher nicht, dass die Benutzer-ID aus allen Synapse-Tabellen verschwindet. Ein gutes Ergebnis ist vielmehr, dass sich der Benutzer nicht mehr authentifizieren kann, aktive Token und Geräte entfernt werden, das Konto aus Räumen entfernt wird, Drittanbieter-Kennungen entfernt werden und – falls Ihre Richtlinien dies erfordern – das Profil gelöscht wird. Hochgeladene Medien und der Nachrichtenverlauf sind davon ausgenommen und werden bei der Kontodeaktivierung nicht automatisch gelöscht.

Diese Anleitung verwendet die aktuelle Synapse-Admin-API-Dokumentation (Stand: Oktober 2026). Vergleichen Sie die Beispiele stets mit der Dokumentation der auf Ihrem Heimserver installierten Synapse-Version, insbesondere bei Langzeitinstallationen oder Verwendung des Matrix-Authentifizierungsdienstes. Die maßgeblichen Referenzen sind die Synapse-Benutzer-Admin-API-Dokumentation , die Synapse-Admin-API-Übersicht und die Synapse-Medien-Admin-API-Dokumentation .

Welches Ergebnis sollten Sie anstreben?

Bevor Sie Änderungen vornehmen, definieren Sie die Bereinigungsrichtlinie. „Inaktiv“ ist kein Synapse-Kontostatus, sondern eine Regel, die Sie anhand von Feldern wie last_seen_tsKontotyp, administrativem Status und Geschäftskontext erstellen.

Wenn Sie sich nicht sicher sind, ob ein Konto inaktiv ist, sollten Sie dies nicht last_seen_tsals einziges Kriterium heranziehen. Dienstkonten, Anwendungsbenutzer, Notfalladministratoren, Bots, Supportkonten und SSO-verknüpfte Benutzer können ungewöhnliche Anmeldemuster aufweisen. Ein zuverlässiger Bereinigungsprozess umfasst eine explizite Ausschlussliste und einen Überprüfungsschritt.

Schritt 1: Lokale Benutzer auflisten und Aktivitätsdaten erfassen

Anfragen an die Admin-API erfordern ein Zugriffstoken eines Serveradministrators , nicht eines Raumadministrators. Senden Sie das Token Authorization: Bearernach Möglichkeit im HTTP-Header und nicht in der URL oder im Shell-Verlauf.

Synapse dokumentiert den V3-Benutzerlisten-Endpunkt wie folgt:

GET /_synapse/admin/v3/users

Eine einfache Anfrage sieht folgendermaßen aus:

export SYNAPSE_URL="https://matrix.example.com"
export ADMIN_ACCESS_TOKEN="REDACTED"

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v3/users?limit=100"

Die Benutzerlisten-API unterstützt Paginierung. Wenn die Antwort ein Leerzeichen enthält next_token, fordern Sie die nächste Seite mit diesem Wert als Leerzeichen an from. Gehen Sie nicht davon aus, dass die erste Seite den gesamten Server repräsentiert.

Die API stellt nützliche Felder für Bereinigungsentscheidungen bereit, darunter Informationen darüber, ob ein Konto ein Administratorkonto ist, seinen Benutzertyp, ob es bereits deaktiviert ist, wann es erstellt wurde und wann es zuletzt verwendet wurde. Die Dokumentation definiert last_seen_tsden letzten Aktivitätszeitpunkt des Benutzers in Millisekunden seit der Unix-Epoche.

Was gilt als „inaktiv“?

Eine gängige Richtlinie lautet „180 Tage keine Aktivität“, doch der optimale Zeitraum hängt von den jeweiligen Gegebenheiten ab. Ein kleiner privater Server kann mit 90 Tagen ausreichend sein. Eine Universität, eine saisonale Organisation oder ein Alumni-Netzwerk benötigt hingegen möglicherweise 365 Tage oder mehr.

Verwenden Sie einen absoluten Grenzwert anstelle des Vergleichs formatierter Datumsangaben. Beispielsweise kann ein Python-Job den Schwellenwert in Millisekunden berechnen:

from datetime import datetime, timezone, timedelta

cutoff = datetime.now(timezone.utc) - timedelta(days=180)
cutoff_ms = int(cutoff.timestamp() * 1000)

Ein Benutzer gilt nur dann als inaktiv, wenn sein Konto aktiv, nicht-administrativ und nicht durch Richtlinien geschützt ist und last_seen_tsälter als der Schwellenwert ist.

Behandeln Sie fehlende oder leere Werte für „Zuletzt gesehen“ mit Vorsicht. Dies kann bedeuten, dass das Konto nie die erwarteten Aktivitätsdaten generiert hat, nicht unbedingt, dass es bedenkenlos entfernt werden kann. Überprüfen Sie Erstellungszeitpunkt, Kontotyp, SSO-Zuordnung und Unternehmensinhaberschaft, bevor Sie das Konto hinzufügen.

Schritt 2: Erstellen Sie eine Liste inaktiver Kandidaten, keine Liste für die automatische Löschung.

Die Qualität dieses Schrittes ist wichtiger als die Geschwindigkeit der API-Aufrufe. Ihr Ziel sollte eine geprüfte Kandidatenliste sein, die ausschließlich Konten enthält, die gefahrlos deaktiviert werden können.

Mindestens ausschließen:

• Heimserver-Administratoren;
• bekannte Anwendungs-, Service- und Integrationskonten;
• Bots und Support-Accounts, die absichtlich inaktiv sind;
• Notfallkonten oder Konten für Glasbruch;
• Konten, die auf einer Liste von Ausnahmen für die Aufbewahrungspflicht stehen;
• Benutzer, die kürzlich ihren Identitätsanbieter oder ihre Kontozuordnung geändert haben;
• bereits deaktivierte Benutzer, es sei denn, Sie überprüfen frühere Aufräumarbeiten.

Ein einfacher Kandidatendatensatz sollte die Matrix-Benutzer-ID, last_seen_tsden Erstellungszeitpunkt, das Administratorkennzeichen, den Kontotyp und den Grund für das Nichtbeachten der Inaktivitätsregel enthalten. Die Speicherung dieser Informationen erleichtert spätere Überprüfungen und Entscheidungen zur Rücknahme von Änderungen erheblich.

Woran erkennt man, dass die Kandidatenauswahl gut genug ist?

Achten Sie auf drei Anzeichen:

• Vollständigkeit: Ihr Skript durchlief die gesamte lokale Benutzerliste.
• Erklärbarkeit: Jeder Kandidat hat einen sichtbaren Grund, wie z. B. „zuletzt gesehen vor 242 Tagen, kein Administrator-, kein Service-Konto“.
• Geringes Risiko falsch-positiver Ergebnisse: Sonderkonten und Geschäftsausnahmen wurden vor jedem destruktiven Anruf herausgefiltert.

Wenn Sie diese Prüfungen nicht bestehen, ändern Sie den Prozess, bevor Sie fortfahren. Fügen Sie beispielsweise eine manuelle Genehmigungsphase hinzu, versenden Sie eine Inaktivitätswarnung oder beginnen Sie mit einer Sperrung anstatt mit einer Deaktivierung.

Schritt 3: Überprüfen Sie jedes Konto vor der Deaktivierung

Synapse dokumentiert für einen bestimmten lokalen Benutzer:

GET /_synapse/admin/v2/users/<user_id>

Beispiel:

USER_ID="@olduser:example.com"

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v2/users/$USER_ID"

Die Antwort kann Informationen zum Verwaltungsstatus des Kontos, Deaktivierungs- und Löschvermerke, Erstellungs- und letzte Aktivitätszeitpunkte, externe Identitäten und Kennungen von Drittanbietern enthalten. An dieser Stelle gilt es zu überprüfen, ob es sich tatsächlich um das Konto handelt, das Sie bearbeiten möchten.

Sollte man „erase true“ oder „erase false“ verwenden?

Verwenden Sie diese Option "erase": false, wenn das operative Ziel darin besteht, den Zugriff zu deaktivieren, aber Profilinformationen beizubehalten. Laut der aktuellen Synapse-Dokumentation werden bei einer normalen Deaktivierung aktive Zugriffstoken, der Passwort-Hash, Geräte und Ende-zu-Ende-Verschlüsselungsschlüssel, Pusher, Drittanbieter-IDs, Raummitgliedschaften, Kontodaten, ausstehende Einladungen und zugehörige Kontogültigkeitsinformationen entfernt.

Verwenden Sie diese Option "erase": true, wenn Ihre Richtlinie auch das Entfernen des Anzeigenamens, der Avatar-URL und benutzerdefinierter Profilfelder sowie das Markieren des Benutzers als gelöscht vorsieht. Löschen bedeutet nicht , dass alle historischen Daten vernichtet werden. Synapse dokumentiert ausdrücklich, dass zuvor gesendete Nachrichten durch diese API nicht gelöscht werden und auch hochgeladene Medien nicht automatisch gelöscht werden.

Diese Unterscheidung ist entscheidend. Wenn Ihre Richtlinie die Löschung von Inhalten über die Profillöschung hinaus erfordert, reicht die alleinige Deaktivierung des Kontos nicht aus.

Schritt 4: Testlauf, Deaktivierung und Überprüfung

Bevor Sie Änderungen vornehmen, speichern Sie die endgültigen Benutzer-IDs in einer Klartext- oder JSON-Datei und überprüfen Sie diese. Ein Testlauf sollte während des gesamten Änderungszeitraums unveränderlich sein: Falls sich das Skript zur Kandidatengenerierung ändert, während Sie Benutzer deaktivieren, stoppen Sie den Vorgang und generieren Sie die genehmigte Liste neu.

Rufen Sie für jeden genehmigten lokalen Benutzer den dokumentierten Deaktivierungsendpunkt auf:

POST /_synapse/admin/v1/deactivate/<user_id>

Beispiel ohne Profillöschung:

curl -sS -X POST   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data '{"erase": false}'   "$SYNAPSE_URL/_synapse/admin/v1/deactivate/@olduser:example.com"

Beispiel mit Profillöschung:

curl -sS -X POST   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data '{"erase": true}'   "$SYNAPSE_URL/_synapse/admin/v1/deactivate/@olduser:example.com"

Anschließend sollten Sie das Konto erneut abfragen:

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v2/users/@olduser:example.com"

Ein erfolgreiches Ergebnis sollte angezeigt werden "deactivated": true. Wenn Sie eine Löschung beantragt haben, überprüfen Sie dies ebenfalls "erased": true. Verwenden Sie „Die API hat HTTP 2xx zurückgegeben“ nicht als einziges Erfolgskriterium; lesen Sie den Benutzerdatensatz nach der Änderung.

Was genau wird durch die Deaktivierung entfernt?

Die aktuelle Synapse-Dokumentation listet verschiedene Auswirkungen der Deaktivierung auf. Dazu gehören die Entfernung aktiver Zugriffstoken, Drittanbieter-Kennungen, Geräte, Ende-zu-Ende-Verschlüsselungsschlüssel, Pusher, Passwort-Hashes, Raummitgliedschaften, ausstehender Einladungen und Kontodaten. Außerdem wird der Benutzer aus dem Benutzerverzeichnis entfernt.

Mit erase: trueSynapse werden zusätzlich der Anzeigename, die Avatar-URL und die benutzerdefinierten Profilfelder entfernt sowie das Konto als gelöscht markiert.

Synapse dokumentiert außerdem wichtige Elemente, die bei diesem Vorgang nicht gelöscht werden. Dazu gehören gesendete und empfangene Nachrichten, hochgeladene Medien, SSO-Zuordnungen, Erstellungszeitstempel, Ratenbegrenzungsüberschreibungen, monatlich aktive Nutzerdatensätze und einige Einwilligungsinformationen. Die dokumentierte Liste ist nicht unbedingt vollständig. Behandeln Sie die Deaktivierung daher als Kontoschließung – nicht als vollständige Datenlöschung.

Müssen auch die vom Benutzer hochgeladenen Medien gelöscht werden?

Falls Ihre Aufbewahrungsrichtlinie das Löschen lokal gespeicherter, vom Benutzer hochgeladener Medien erfordert, bietet Synapse einen separaten Endpunkt:

DELETE /_synapse/admin/v1/users/<user_id>/media

Beispiel:

curl -sS -X DELETE   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v1/users/@olduser:example.com/media"

Die Benutzermedien-API löscht lokale Medien und Miniaturansichten, die im Synapse-Medienrepository gespeichert sind. Die Dokumentation weist auf zwei wichtige Einschränkungen hin: Erstens sind Medien, die in einem externen Medienrepository gespeichert sind, von dieser API nicht betroffen. Zweitens löscht der Endpunkt ohne festgelegtes Limit 100 Dateien pro Anfrage. Benutzer mit großen Medienverläufen müssen daher unter Umständen mehrere Aufrufe tätigen.

Fügen Sie die automatische Medienlöschung nur dann hinzu, wenn Ihre Aufbewahrungsrichtlinie dies vorsieht. Sie ist wesentlich schädlicher als die Deaktivierung des Kontos und kann Medien betreffen, auf die noch in historischen Räumen verwiesen wird.

Wann sollte man stattdessen eine Federung verwenden?

Synapse dokumentiert auch eine API zur Kontosperrung. Die Sperrung blockiert Aktivitäten wie das Senden von Nachrichten, das Beitreten zu Räumen, das Versenden von Einladungen, das Ändern von Profilinformationen und die meisten Schwärzungen, wobei ein anderer Wiederherstellungspfad als bei der Deaktivierung erhalten bleibt.

Eine Sperrung eignet sich besser, wenn eine reversible administrative Sperre erforderlich ist, die Inaktivität unklar ist oder eine Überprüfung des Austritts noch läuft. Eine Deaktivierung ist die bessere Wahl, wenn der Zugriff beendet und Tokens, Geräte, Raummitgliedschaften und Kontodaten entfernt werden sollen.

Für die automatisierte Bereinigung ist ein stufenweises Vorgehen oft sicherer:

1. Ein Konto nach Überschreiten der Inaktivitätsschwelle kennzeichnen;
2. benachrichtigen oder überprüfen;
3. Aussetzung bei unklarer Eigentumslage;
4. Die Deaktivierung erfolgt erst nach Ablauf der Aufbewahrungs- oder Genehmigungsfrist.

Wie lässt sich die Bereinigung sicher automatisieren?

Die Erkennung und Deaktivierung sollten als separate Prozesse durchgeführt werden. Der Erkennungsprozess sollte schreibgeschützt sein und eine Kandidatendatei erzeugen. Der Ausführungsprozess sollte nur eine genehmigte Datei verarbeiten und jeden Anfrage- und Antwortstatus protokollieren.

Ein Workflow in Produktionsqualität sollte außerdem Folgendes berücksichtigen:

• Alle Seitenumbruchzeichen beachten;
• Massenanfragen mit einer Ratenbegrenzung versehen, anstatt Tausende gleichzeitig abzuschicken;
• Serveradministratoren und benannte Dienstkonten sind standardmäßig ausgeschlossen;
• Zeitstempel in UTC speichern;
• Die Version der Bereinigungsrichtlinie, die für jedes Konto ausgewählt wurde, protokollieren;
• Abbruch bei Authentifizierungs-, Autorisierungs- oder wiederholten Serverfehlern;
• Nach der Deaktivierung jeden Benutzer erneut abfragen;
• Administrative Zugriffstoken sollten nicht im Quellcode oder in Protokolldateien gespeichert werden.

Wenn die Überprüfung nach der Änderung nicht dem angeforderten Status entspricht, fahren Sie nicht einfach mit dem restlichen Batch fort. Untersuchen Sie die ersten Fehler und ermitteln Sie, ob das Problem auf Berechtigungen, API-Versionskompatibilität, ein Proxy-Konfigurationsproblem, die Integration des Matrix Authentication Service oder eine kontospezifische Bedingung zurückzuführen ist.

Abschließende Checkliste

• Verwenden Sie ein Server-Admin-Bearer-Token.
• Alle lokalen Benutzerseiten auflisten, nicht nur die der ersten 100 Benutzer.
• Inaktivität wird anhand eines dokumentierten Schwellenwerts und Ausschlusskriterien definiert.
• Hochrisikokonten sollten vor jeglichen Maßnahmen einzeln geprüft werden.
• Erstellen und genehmigen Sie eine Testlaufliste.
• Verwenden Sie den Deaktivierungsendpunkt, anstatt davon auszugehen, dass Synapse die vollständige, endgültige Löschung von Konten unterstützt.
• Diese Option sollte nur dann gewählt werden erase: true, wenn die Profillöschung Teil der Richtlinie ist.
• Hochgeladene Mediendateien müssen bei Bedarf separat behandelt werden.
• Überprüfen Sie die Änderungen deactivatedund gegebenenfalls erasednach jeder Änderung.

Die zuverlässigste Bereinigung ist diejenige, die sich im Nachhinein erklären lässt: Welche Inaktivitätsregel hat ein Konto ausgewählt, welche Ausnahmen wurden geprüft, welche API-Aktion wurde ausgeführt und welches Feld nach der Änderung hat den gewünschten Zustand bestätigt. Dieser Standard ist sinnvoller als die bloße Maximierung der Anzahl der in einem Durchlauf verarbeiteten Konten.