Come eliminare gli account utente inattivi in ​​Matrix Synapse tramite API di amministrazione

In Matrix Synapse, esiste un'importante distinzione tra l'eliminazione di un account inattivo e la sua disattivazione . L'API di amministrazione di Synapse, così come documentata, non fornisce un endpoint di eliminazione definitiva generico che rimuova tutti i record del database associati a un utente. Il flusso di lavoro amministrativo supportato prevede l'identificazione di un account, la sua revisione e la successiva chiamata all'endpoint di disattivazione. È possibile, facoltativamente, impostare "erase": truela rimozione delle informazioni del profilo e contrassegnare l'utente come cancellato.

Un buon risultato non è quindi "l'ID utente scompare da tutte le tabelle di Synapse". Un buon risultato è che l'utente non possa più autenticarsi, i token e i dispositivi attivi vengano rimossi, l'account venga disattivato dalle stanze, gli identificativi di terze parti vengano rimossi e, se la policy lo richiede, il profilo venga cancellato. I contenuti multimediali caricati e i messaggi storici sono questioni separate e non vengono eliminati automaticamente con la disattivazione dell'account.

Questa guida utilizza la documentazione API di amministrazione di Synapse disponibile a ottobre 2026. Confronta sempre gli esempi con la documentazione relativa alla versione di Synapse in esecuzione sul tuo server domestico, soprattutto se gestisci un'installazione a lungo termine o utilizzi Matrix Authentication Service. I riferimenti autorevoli sono la documentazione API di amministrazione utenti di Synapse , la panoramica API di amministrazione di Synapse e la documentazione API di amministrazione media di Synapse .

Quale risultato dovresti puntare a ottenere?

Prima di apportare qualsiasi modifica, definisci la politica di pulizia. "Inattivo" non è uno stato dell'account Synapse; è una regola che crei a partire da campi quali last_seen_tstipo di account, stato amministrativo e contesto aziendale.

Se non si è certi che un account sia stato abbandonato, non basarsi last_seen_tssolo su questo criterio. Gli account di servizio, gli utenti dei servizi applicativi, gli amministratori di emergenza, i bot, gli account di supporto e gli utenti collegati tramite SSO possono presentare schemi di accesso insoliti. Un processo di pulizia affidabile prevede un elenco esplicito di esclusione e una fase di revisione.

Passaggio 1: Elencare gli utenti locali e raccogliere i dati di attività

Le richieste API di amministrazione richiedono un token di accesso appartenente a un amministratore del server , che è diverso da un amministratore di stanza. Authorization: BearerSe possibile, inviare il token nell'intestazione HTTP anziché inserirlo nell'URL o nella cronologia della shell.

Synapse documenta l'endpoint della lista utenti V3 come segue:

GET /_synapse/admin/v3/users

Una richiesta di base si presenta così:

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"

L'API user-list supporta la paginazione. Quando la risposta contiene next_token, richiedi la pagina successiva utilizzando quel valore come from. Non presumere che la prima pagina rappresenti l'intero server.

L'API espone campi utili per le decisioni di pulizia, tra cui se un account è un amministratore, il suo tipo di utente, se è già disattivato, quando è stato creato e quando è stato visualizzato l'ultima volta. La documentazione definisce last_seen_tscome il timestamp dell'ultima attività dell'utente in millisecondi dall'epoca Unix.

Cosa si intende per "inattivo"?

Una politica comune è "nessuna attività per 180 giorni", ma la soglia giusta dipende dal contesto. Un piccolo server privato può ragionevolmente utilizzare 90 giorni. Un'università, un'organizzazione stagionale o un servizio per ex-alunni potrebbero aver bisogno di 365 giorni o più.

Utilizza un timestamp di cutoff assoluto anziché confrontare date formattate. Ad esempio, un processo Python può calcolare la soglia in millisecondi:

from datetime import datetime, timezone, timedelta

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

Un utente viene quindi considerato inattivo solo quando l'account è attivo, non amministrativo, non protetto da policy e ha last_seen_tsun'età superiore alla soglia.

Trattate con cautela i valori mancanti o nulli relativi all'ultima visualizzazione. Potrebbe significare che l'account non ha mai prodotto i dati di attività previsti, ma non necessariamente che sia sicuro rimuoverlo. Prima di includerlo, verificate la data di creazione, il tipo di account, la mappatura SSO e la proprietà aziendale.

Passaggio 2: crea un elenco di candidati per l'inattività, non un elenco di eliminazione automatica.

La qualità di questa fase è più importante della velocità delle chiamate API. L'obiettivo dovrebbe essere un elenco di candidati verificato, contenente solo account che possono essere disattivati ​​in sicurezza.

Come minimo, escludere:

• amministratori di server domestici;
• Account noti per servizi applicativi e di integrazione;
• bot e account di supporto intenzionalmente inattivi;
• conti di emergenza o per interventi rapidi;
• conti inclusi in un elenco di eccezioni per blocco legale o conservazione;
• utenti che hanno recentemente modificato il provider di identità o la mappatura dell'account;
• utenti già disattivati, a meno che non si stia verificando un precedente lavoro di pulizia.

Un semplice record candidato dovrebbe contenere l'ID utente Matrix, last_seen_tsla data e l'ora di creazione, il flag di amministratore, il tipo di account e il motivo per cui ha superato la regola di inattività. Conservare queste prove semplifica notevolmente le successive decisioni di revisione e di ripristino.

Come si fa a sapere se la selezione dei candidati è sufficientemente valida?

Cerca tre segnali:

• Completezza: il tuo script è impaginato attraverso l'intero elenco degli utenti locali.
• Spiegabilità: ogni candidato ha una motivazione visibile, come ad esempio "ultimo accesso 242 giorni fa, account non amministratore, account non di servizio".
• Basso rischio di falsi positivi: i conti speciali e le eccezioni aziendali sono stati filtrati prima di qualsiasi chiamata distruttiva.

Se non è possibile superare tali verifiche, è necessario modificare il processo prima di procedere. Ad esempio, si può aggiungere una fase di approvazione umana, inviare un avviso di inattività o iniziare con la sospensione anziché con la disattivazione.

Passaggio 3: Ispezionare ogni account prima della disattivazione

Per uno specifico utente locale, Synapse documenta:

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

Esempio:

USER_ID="@olduser:example.com"

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

La risposta può includere lo stato amministrativo dell'account, i flag di disattivazione e cancellazione, le date di creazione e ultimo accesso, le identità esterne e gli identificatori di terze parti. Questo è il momento di verificare che l'account sia effettivamente quello che si intende modificare.

È meglio usare erase true o erase false?

Da utilizzare "erase": falsequando l'obiettivo operativo è disabilitare l'accesso mantenendo le informazioni del profilo. Secondo la documentazione attuale di Synapse, la disattivazione normale rimuove i token di accesso attivi, l'hash della password, i dispositivi e le chiavi di crittografia end-to-end, i pusher, gli ID di terze parti, l'appartenenza alle stanze, i dati dell'account, gli inviti in sospeso e le relative informazioni sulla validità dell'account.

Da utilizzare "erase": truequando la policy prevede anche la rimozione del nome visualizzato, dell'URL dell'avatar, dei campi del profilo personalizzati e la marcatura dell'utente come eliminato. L'eliminazione non implica la distruzione di ogni elemento storico. Synapse specifica esplicitamente che i messaggi inviati in precedenza non vengono eliminati da questa API e che i contenuti multimediali caricati non vengono eliminati automaticamente.

Questa distinzione è fondamentale. Se la tua policy richiede la cancellazione dei contenuti oltre alla semplice eliminazione del profilo, la disattivazione dell'account non è sufficiente.

Passaggio 4: Eseguire una simulazione, disattivare e verificare

Prima di eseguire le modifiche, scrivi gli ID utente finali in un file di testo semplice o JSON e rivedilo. Una prova generale dovrebbe rimanere immutabile per tutta la durata della finestra di modifica: se lo script di generazione dei candidati cambia mentre stai disattivando gli utenti, interrompi e rigenera l'elenco approvato.

Per ogni utente locale autorizzato, chiamare l'endpoint di disattivazione documentato:

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

Esempio senza cancellazione del profilo:

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"

Esempio con cancellazione del profilo:

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"

Dopodiché, interroga nuovamente l'account:

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

Un risultato operativo positivo dovrebbe essere visualizzato "deactivated": true. Se hai richiesto la cancellazione, verifica anche "erased": true. Non utilizzare "l'API ha restituito HTTP 2xx" come unico criterio di successo; leggi il record utente dopo la modifica.

Cosa viene effettivamente rimosso tramite la disattivazione?

La documentazione attuale di Synapse elenca diversi effetti della disattivazione. Tra questi, la rimozione dei token di accesso attivi, degli identificatori di terze parti, dei dispositivi, delle chiavi di crittografia end-to-end, dei pusher, degli hash delle password, delle appartenenze alle stanze, degli inviti in sospeso e dei dati dell'account. La disattivazione comporta anche la rimozione dell'utente dalla directory degli utenti.

Con questa opzione erase: true, Synapse rimuove anche il nome visualizzato, l'URL dell'avatar, i campi del profilo personalizzati e contrassegna l'account come eliminato.

Synapse documenta anche elementi importanti che non vengono rimossi da questa operazione. Questi includono messaggi inviati e ricevuti, file multimediali caricati, mappature SSO, timestamp di creazione, override dei limiti di frequenza, record degli utenti attivi mensili e alcune informazioni relative al consenso. L'elenco documentato non è necessariamente esaustivo, quindi la disattivazione va considerata come la chiusura dell'account e non come una cancellazione completa dei dati.

Devi eliminare anche i file multimediali caricati dall'utente?

Se la tua politica di conservazione richiede l'eliminazione dei file multimediali archiviati localmente e caricati dall'utente, Synapse fornisce un endpoint separato:

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

Esempio:

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

L'API per i file multimediali degli utenti elimina i file multimediali locali e le miniature archiviati nel repository multimediale di Synapse. La documentazione segnala due limiti rilevanti dal punto di vista operativo. In primo luogo, i file multimediali archiviati in un repository esterno non sono interessati da questa API. In secondo luogo, se non si imposta un limite, l'endpoint elimina 100 file per richiesta, pertanto gli utenti con una cronologia multimediale estesa potrebbero dover effettuare chiamate ripetute.

Non attivare la cancellazione automatica dei file multimediali a meno che la tua politica di conservazione non lo preveda. Questa operazione è sostanzialmente più distruttiva della disattivazione dell'account e potrebbe influire sui file multimediali ancora presenti nelle cartelle storiche.

Quando è preferibile utilizzare le sospensioni?

Synapse documenta anche un'API per la sospensione dell'account. La sospensione blocca attività come l'invio di messaggi, l'accesso alle stanze, l'invio di inviti, la modifica delle informazioni del profilo e la maggior parte delle oscurazioni, preservando al contempo un percorso di recupero diverso rispetto alla disattivazione.

La sospensione è più indicata quando è necessario un blocco amministrativo reversibile, quando l'inattività è incerta o quando è ancora in corso una procedura di disattivazione. La disattivazione è la scelta più drastica quando l'accesso deve essere interrotto e devono essere rimossi token, dispositivi, abbonamenti alle sale e dati dell'account.

Per la pulizia automatizzata, una politica a fasi è spesso più sicura:

1. Segnalare un account dopo il raggiungimento della soglia di inattività;
2. notificarlo o rivederlo;
3. sospenderlo se la proprietà è incerta;
4. Disattivare solo dopo che il periodo di conservazione o di approvazione è trascorso.

Come automatizzare le operazioni di pulizia in modo sicuro?

Mantenere le fasi di rilevamento e disattivazione come processi separati. Il processo di rilevamento deve essere di sola lettura e produrre un file candidato. Il processo di esecuzione deve utilizzare solo il file approvato e registrare ogni richiesta e lo stato della risposta.

Un flusso di lavoro di qualità professionale dovrebbe inoltre:

• seguire tutti i simboli di paginazione;
• limitare la frequenza delle richieste in blocco anziché inviarne migliaia contemporaneamente;
• Escludi per impostazione predefinita gli amministratori del server e gli account di servizio denominati;
• memorizza i timestamp in formato UTC;
• registrare la versione dei criteri di pulizia selezionata per ciascun account;
• Interruzione in caso di autenticazione, autorizzazione o errori ripetuti del server;
• Eseguire una nuova query su ciascun utente dopo la disattivazione;
• Evitare di includere i token di accesso amministrativo nel codice sorgente e nei log.

Se la verifica successiva alla modifica non corrisponde allo stato richiesto, non procedere ciecamente con il batch rimanente. Analizza i primi errori e determina se il problema riguarda le autorizzazioni, la compatibilità della versione dell'API, un problema di configurazione del proxy, l'integrazione con Matrix Authentication Service o una condizione specifica dell'account.

Lista di controllo finale

• Utilizzare un token bearer server-admin.
• Elenca tutte le pagine degli utenti locali, non solo quelle dei primi 100 utenti.
• Definisci l'inattività con una soglia documentata ed esclusioni.
• Prima di intraprendere qualsiasi azione, esaminare singolarmente i conti ad alto rischio.
• Genera e approva un elenco di prove a secco.
• Utilizza l'endpoint di disattivazione anziché presumere che Synapse supporti la cancellazione definitiva dell'account.
• Selezionare questa opzione erase: truesolo se la cancellazione del profilo è prevista dalle norme.
• Gestisci i file multimediali caricati separatamente, se necessario.
• Verificare deactivatede, se necessario, eraseddopo ogni modifica.

La pulizia più affidabile è quella che si può spiegare a posteriori: quale regola di inattività ha selezionato un account, quali eccezioni sono state verificate, quale azione API è stata eseguita e quale campo post-modifica ha dimostrato lo stato desiderato. Questo standard è più utile del semplice massimizzare il numero di account elaborati in una singola esecuzione.