Comment supprimer les comptes utilisateurs inactifs dans Matrix Synapse via l'API d'administration

Dans Matrix Synapse, il est important de distinguer la suppression d'un compte inactif de sa désactivation . L'API d'administration documentée de Synapse ne propose pas de point de terminaison de suppression définitive générique permettant de supprimer tous les enregistrements de la base de données associés à un utilisateur. La procédure d'administration recommandée consiste à identifier un compte, à le vérifier, puis à appeler le point de terminaison de désactivation. Vous pouvez également choisir "erase": truede supprimer les informations de profil et de marquer l'utilisateur comme supprimé.

Un bon résultat ne se limite donc pas à la simple disparition de l'identifiant utilisateur de toutes les tables Synapse. Il s'agit plutôt de rendre l'utilisateur indisponible, de supprimer les jetons et appareils actifs, de retirer le compte des salons, de supprimer les identifiants tiers et, si votre politique l'exige, d'effacer le profil. Les médias téléchargés et l'historique des messages constituent un cas distinct et ne sont pas automatiquement supprimés lors de la désactivation du compte.

Ce guide utilise la documentation de l'API d'administration Synapse en vigueur en octobre 2026. Comparez toujours les exemples avec la documentation de la version de Synapse installée sur votre serveur, notamment si vous utilisez un déploiement de longue durée ou le service d'authentification Matrix. Les documents de référence sont la documentation de l'API d'administration utilisateur Synapse , la présentation de l'API d'administration Synapse et la documentation de l'API d'administration multimédia Synapse .

Quel résultat devez-vous viser ?

Avant toute modification, définissez la politique de nettoyage. « Inactif » ne correspond pas à l’état d’un compte Synapse ; il s’agit d’une règle que vous créez à partir de champs tels que last_seen_tsle type de compte, le statut administratif et le contexte métier.

En cas de doute sur l'abandon d'un compte, ne last_seen_tsvous basez pas uniquement sur ce critère. Les comptes de service, les utilisateurs de services applicatifs, les administrateurs d'urgence, les bots, les comptes d'assistance et les utilisateurs liés par authentification unique peuvent présenter des habitudes de connexion inhabituelles. Une procédure de nettoyage fiable comprend une liste d'exclusion explicite et une étape de vérification.

Étape 1 : Lister les utilisateurs locaux et collecter les données d'activité

Les requêtes API d'administration nécessitent un jeton d'accès appartenant à un administrateur de serveur , et non à un administrateur de salle. Authorization: BearerDans la mesure du possible, transmettez le jeton dans l'en-tête HTTP plutôt que dans une URL ou l'historique du terminal.

Synapse décrit le point de terminaison de la liste des utilisateurs V3 comme suit :

GET /_synapse/admin/v3/users

Une requête de base ressemble à ceci :

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 de liste d'utilisateurs prend en charge la pagination. Lorsque la réponse contient une pagination next_token, demandez la page suivante en utilisant cette valeur from. Ne considérez pas que la première page représente l'intégralité du serveur.

L'API expose des champs utiles pour les décisions de nettoyage, notamment si un compte est administrateur, son type d'utilisateur, s'il est déjà désactivé, sa date de création et sa dernière connexion. La documentation définit cette dernière last_seen_tscomme l'horodatage de la dernière activité de l'utilisateur en millisecondes depuis l'époque Unix.

Qu’est-ce qui est considéré comme « inactif » ?

Une politique courante consiste à interdire toute activité pendant 180 jours, mais la durée optimale dépend du contexte. Un petit serveur privé peut raisonnablement se contenter de 90 jours. Une université, une association saisonnière ou un service des anciens élèves peut avoir besoin de 365 jours, voire plus.

Utilisez un horodatage absolu plutôt que de comparer des dates formatées. Par exemple, une tâche Python peut calculer le seuil en millisecondes :

from datetime import datetime, timezone, timedelta

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

Considérez alors un utilisateur comme inactif uniquement lorsque son compte est actif, non administratif, non protégé par une politique et que son last_seen_tsancienneté dépasse le seuil requis.

Traitez avec prudence toute valeur de dernière connexion manquante ou nulle. Cela peut signifier que le compte n'a jamais produit les données d'activité attendues, mais pas nécessairement qu'il est sans risque de le supprimer. Vérifiez la date de création, le type de compte, le mappage SSO et le propriétaire du compte avant de l'inclure.

Étape 2 : Constituer une liste de candidats à la suppression automatique en cas d’inactivité, et non une liste de suppression automatique

La qualité de cette étape est plus importante que la rapidité des appels API. Votre objectif doit être une liste de candidats vérifiés ne contenant que les comptes pouvant être désactivés en toute sécurité.

À tout le moins, exclure :

• administrateurs de serveurs domestiques ;
• comptes de services applicatifs et d'intégration connus ;
• bots et comptes de support intentionnellement inactifs ;
• comptes d'urgence ou de bris de glace ;
• comptes figurant sur une liste d'exceptions de conservation légale ;
• utilisateurs ayant récemment changé de fournisseur d'identité ou de mappage de compte ;
• Utilisateurs déjà désactivés, sauf si vous effectuez un audit des travaux de nettoyage précédents.

Un enregistrement de candidat simple doit contenir l'identifiant utilisateur Matrix, last_seen_tsla date et l'heure de création, le statut d'administrateur, le type de compte et le motif du non-respect de la règle d'inactivité. La conservation de ces informations facilite grandement les décisions ultérieures de révision et de restauration.

Comment savoir si la sélection des candidats est suffisamment bonne ?

Recherchez trois signes :

• Exhaustivité : votre script a été paginé sur l’ensemble de la liste des utilisateurs locaux.
• Explicabilité : chaque candidat a une raison visible, telle que « dernière connexion il y a 242 jours, compte non administrateur, compte non lié au service ».
• Faible risque de faux positifs : les comptes spéciaux et les exceptions commerciales ont été filtrés avant tout appel destructeur.

Si vous ne pouvez pas satisfaire à ces contrôles, modifiez le processus avant de poursuivre. Par exemple, ajoutez une étape d'approbation humaine, envoyez un avertissement en cas d'inactivité ou commencez par une suspension plutôt que par une désactivation.

Étape 3 : Examiner chaque compte avant sa désactivation

Pour un utilisateur local spécifique, la documentation Synapse :

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

Exemple:

USER_ID="@olduser:example.com"

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

La réponse peut inclure l'état administratif du compte, les indicateurs de désactivation et de suppression, les dates de création et de dernière connexion, les identités externes et les identifiants tiers. C'est à ce stade que l'on vérifie qu'il s'agit bien du compte concerné.

Faut-il utiliser la fonction « effacer vrai » ou « effacer faux » ?

Utilisez cette option "erase": falselorsque l'objectif est de désactiver l'accès tout en conservant les informations de profil. D'après la documentation Synapse actuelle, la désactivation standard supprime les jetons d'accès actifs, le hachage du mot de passe, les appareils et les clés de chiffrement de bout en bout, les outils de diffusion, les identifiants tiers, les appartenances aux salons, les données du compte, les invitations en attente et les informations de validité du compte.

Utilisez cette fonction "erase": truelorsque votre politique exige également la suppression du nom d'affichage, de l'URL de l'avatar, des champs de profil personnalisés et le marquage de l'utilisateur comme supprimé. La suppression ne signifie pas la destruction de toutes les données historiques. Synapse précise que les messages envoyés précédemment ne sont pas supprimés par cette API, et que les médias téléchargés ne sont pas non plus supprimés automatiquement.

Cette distinction est essentielle. Si votre politique exige la suppression de contenu au-delà de la simple suppression du profil, la désactivation du compte ne suffit pas.

Étape 4 : Test à blanc, désactivation et vérification

Avant d'appliquer les modifications, enregistrez les identifiants utilisateur définitifs dans un fichier texte brut ou JSON et vérifiez-le. Une simulation doit rester inchangée pendant toute la durée de la période de modification : si le script de génération des candidats est modifié pendant la désactivation des utilisateurs, interrompez le processus et régénérez la liste des utilisateurs approuvés.

Pour chaque utilisateur local autorisé, appelez le point de terminaison de désactivation documenté :

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

Exemple sans effacement de profil :

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"

Exemple avec suppression de profil :

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"

Ensuite, interrogez à nouveau le compte :

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

Un résultat opérationnel positif devrait s'afficher "deactivated": true. Si vous avez demandé une suppression, vérifiez également "erased": true. Ne vous basez pas uniquement sur le code HTTP 2xx renvoyé par l'API ; consultez l'enregistrement utilisateur après la modification.

Qu'est-ce que la désactivation supprime réellement ?

La documentation actuelle de Synapse répertorie plusieurs conséquences de la désactivation. Parmi celles-ci figurent la suppression des jetons d'accès actifs, des identifiants tiers, des appareils, des clés de chiffrement de bout en bout, des pushers, des hachages de mots de passe, des appartenances aux salons, des invitations en attente et des données du compte. L'utilisateur est également supprimé de l'annuaire.

Avec cette fonction erase: true, Synapse supprime également le nom d'affichage, l'URL de l'avatar, les champs de profil personnalisés et marque le compte comme effacé.

Synapse conserve également des données importantes qui ne sont pas supprimées par cette opération. Il s'agit notamment des messages envoyés et reçus, des fichiers multimédias téléchargés, des mappages SSO, des horodatages de création, des dérogations aux limites de débit, des enregistrements mensuels d'utilisateurs actifs et de certaines informations de consentement. Cette liste n'est pas exhaustive ; par conséquent, la désactivation s'apparente à la fermeture d'un compte et non à une suppression totale des données.

Faut-il également supprimer les fichiers multimédias téléchargés par l'utilisateur ?

Si votre politique de rétention exige la suppression des médias stockés localement et téléchargés par l'utilisateur, Synapse fournit un point de terminaison distinct :

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

Exemple:

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

L'API de gestion des médias utilisateur supprime les fichiers multimédias locaux et leurs vignettes stockés dans le dépôt multimédia Synapse. La documentation précise deux limites importantes : premièrement, les fichiers multimédias stockés dans un dépôt externe ne sont pas concernés par cette API ; deuxièmement, si aucune limite n'est définie, le point de terminaison supprime 100 fichiers par requête, ce qui peut nécessiter plusieurs appels pour les utilisateurs ayant un historique multimédia important.

N’activez pas la suppression automatique des médias, sauf si votre politique de conservation le prévoit. Cette action est beaucoup plus destructrice que la désactivation du compte et peut affecter les médias encore référencés dans les salles historiques.

Quand faut-il plutôt utiliser la suspension ?

Synapse propose également une API de suspension de compte. La suspension bloque certaines actions comme l'envoi de messages, l'accès aux salons, l'envoi d'invitations, la modification des informations de profil et la plupart des actions de masquage, tout en proposant une procédure de récupération différente de celle de la désactivation.

La suspension est plus appropriée lorsqu'une restriction administrative réversible est nécessaire, en cas d'inactivité incertaine ou lorsqu'une procédure de départ est en cours. La désactivation est la solution la plus radicale lorsqu'il convient de supprimer définitivement l'accès et de retirer les jetons, appareils, abonnements aux salles et données du compte.

Pour un nettoyage automatisé, une politique par étapes est souvent plus sûre :

1. signaler un compte après le seuil d'inactivité ;
2. notifiez-le ou examinez-le ;
3. Suspendre la procédure en cas d'incertitude quant à la propriété ;
4. Ne pas désactiver uniquement après l'expiration du délai de conservation ou d'approbation.

Comment automatiser le nettoyage en toute sécurité ?

La découverte et la désactivation doivent être effectuées séparément. La tâche de découverte doit être en lecture seule et générer un fichier candidat. La tâche d'exécution doit traiter uniquement un fichier approuvé et consigner chaque requête et son statut de réponse.

Un flux de travail de qualité production doit également :

• suivre tous les jetons de pagination ;
• limiter le débit des requêtes groupées plutôt que d'en envoyer des milliers simultanément ;
• Exclure par défaut les administrateurs de serveur et les comptes de service nommés ;
• stocker les horodatages en UTC ;
• enregistrer la version de la politique de nettoyage qui a sélectionné chaque compte ;
• arrêt en cas d'authentification, d'autorisation ou d'erreurs serveur répétées ;
• réinterroger chaque utilisateur après désactivation ;
• Évitez d'inclure les jetons d'accès administratif dans le code source et les journaux.

Si la vérification après modification ne correspond pas à l'état demandé, ne poursuivez pas le traitement du lot restant sans analyse. Examinez les premiers échecs afin de déterminer si le problème provient des autorisations, de la compatibilité de la version de l'API, d'un problème de configuration du proxy, de l'intégration du service d'authentification Matrix ou d'une condition spécifique au compte.

Liste de vérification finale

• Utilisez un jeton porteur d'administrateur de serveur.
• Énumérez toutes les pages des utilisateurs locaux, et pas seulement celles des 100 premiers.
• Définir l'inactivité avec un seuil documenté et des exclusions.
• Examinez individuellement les comptes à haut risque avant d'entreprendre toute action.
• Générer et approuver une liste de répétitions à blanc.
• Utilisez le point de terminaison de désactivation plutôt que de supposer que Synapse prend en charge la suppression définitive du compte.
• Choisissez cette option erase: trueuniquement si la suppression du profil fait partie de la politique de l'entreprise.
• Gérez les médias téléchargés séparément lorsque cela est nécessaire.
• Vérifier deactivatedet, le cas échéant, erasedaprès chaque modification.

Le nettoyage le plus fiable est celui dont on peut expliquer le déroulement a posteriori : quelle règle d’inactivité a sélectionné un compte, quelles exceptions ont été vérifiées, quelle action API a été effectuée et quel champ post-modification a confirmé l’état souhaité. Cette approche est plus pertinente que de simplement maximiser le nombre de comptes traités en une seule opération.