Matrix SynapseでAdmin APIを使用して非アクティブなユーザーアカウントを削除する方法

Matrix Synapseでは、非アクティブなアカウントを削除することと、アカウントを非アクティブ化することには重要な違いがあります。Synapseのドキュメントに記載されている管理APIには、ユーザーに関連付けられたすべてのデータベースレコードを削除する汎用的なハード削除エンドポイントは用意されていません。サポートされている管理ワークフローは、アカウントを特定し、内容を確認してから、非アクティブ化エンドポイントを呼び出すことです。必要に応じて、"erase": trueプロファイル情報を削除し、ユーザーを削除済みとしてマークするように設定できます。

したがって、良い結果とは「ユーザーIDがすべてのSynapseテーブルから消える」ことではありません。良い結果とは、ユーザーが認証できなくなり、アクティブなトークンとデバイスが削除され、アカウントがルームから削除され、サードパーティ識別子が削除され、ポリシーで要求されている場合はプロファイルが消去されることです。アップロードされたメディアと過去のメッセージは別の問題であり、アカウントの無効化によって自動的に削除されることはありません。

このガイドでは、2026年10月時点で利用可能な最新のSynapse Admin APIドキュメントを使用しています。特に長期運用環境やMatrix Authentication Serviceを使用している場合は、必ずホームサーバーで実行されているSynapseバージョンのドキュメントと例を比較してください。公式な参考資料としては、Synapse User Admin APIドキュメント、Synapse Admin API概要、およびSynapse Media Admin APIドキュメントがあります。

どのような結果を目指すべきでしょうか？

last_seen_ts変更を加える前に、クリーンアップポリシーを定義してください。「非アクティブ」はSynapseアカウントの状態ではなく、アカウントタイプ、管理ステータス、ビジネスコンテキストなどのフィールドから作成するルールです。

アカウントが放棄されているかどうか確信が持てない場合は、last_seen_ts唯一の判断基準にしないでください。サービスアカウント、アプリケーションサービスユーザー、緊急管理者、ボット、サポートアカウント、SSOリンクされたユーザーは、通常とは異なるログインパターンを示す可能性があります。確実なクリーンアッププロセスには、明示的な除外リストとレビュー手順が含まれます。

ステップ1：ローカルユーザーを一覧表示し、アクティビティデータを収集する

管理者APIリクエストには、サーバー管理者のアクセストークンが必要です。これはルーム管理者とは異なります。可能な限り、トークンはAuthorization: BearerURLやシェル履歴ではなく、HTTPヘッダーに含めて送信してください。

SynapseはV3ユーザーリストエンドポイントを次のように文書化しています。

GET /_synapse/admin/v3/users

基本的なリクエストは次のようになります。

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"

ユーザーリストAPIはページネーションをサポートしています。レスポンスに が含まれている場合はnext_token、その値を として使用して次のページをリクエストしてくださいfrom。最初のページがサーバー全体の情報を表していると想定しないでください。

API は、アカウントが管理者であるかどうか、ユーザーの種類、既に無効化されているかどうか、作成日時、最終アクセス日時など、クリーンアップの判断に役立つフィールドを公開しています。ドキュメントでは、最終アクセス日時は、last_seen_tsUnix エポックからのミリ秒単位でのユーザーの最終アクティビティのタイムスタンプとして定義されています。

「非アクティブ」とはどういう意味ですか？

一般的なポリシーは「180日間は活動停止」ですが、適切な期間は環境によって異なります。小規模なプライベートサーバーであれば90日間で十分でしょう。大学、季節限定の組織、同窓会サービスなどでは、365日以上が必要になる場合もあります。

フォーマットされた日付を比較するのではなく、絶対的なカットオフタイムスタンプを使用してください。たとえば、Pythonジョブはしきい値をミリ秒単位で計算できます。

from datetime import datetime, timezone, timedelta

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

last_seen_tsアカウントがアクティブであり、管理者権限がなく、ポリシーによって保護されておらず、かつそのアカウントの作成時期がしきい値よりも古い場合にのみ、ユーザーを非アクティブとみなします。

最終確認値が欠落またはnullの場合は、慎重に処理してください。これは、アカウントが期待どおりのアクティビティデータを生成したことがないことを意味する可能性があり、必ずしも削除しても安全であるとは限りません。含める前に、作成日時、アカウントの種類、SSOマッピング、および事業所有権を相互に確認してください。

ステップ2：自動削除リストではなく、非アクティブ候補リストを作成する

このステップでは、API呼び出しの速度よりも品質が重要です。目標は、無効化しても安全なアカウントのみを含む、審査済みの候補リストを作成することです。

最低限、以下を除外してください。

• ホームサーバー管理者;
• 既知のアプリケーションサービスおよび統合アカウント。
• 意図的に休止状態にあるボットおよびサポートアカウント。
• 緊急時用口座または非常用口座。
• 法的保留リストまたは保持例外リストに掲載されているアカウント。
• 最近IDプロバイダーまたはアカウントマッピングを変更したユーザー。
• 既に無効化されているユーザーは除外してください。ただし、以前のクリーンアップ作業を監査する場合は除きます。

シンプルな候補レコードには、MatrixユーザーID last_seen_ts、作成タイムスタンプ、管理者フラグ、アカウントタイプ、および非アクティブルールを通過した理由を含める必要があります。これらの証拠を保持しておくことで、後々のレビューやロールバックの判断がはるかに容易になります。

候補者の選定が十分であると、どのように判断するのですか？

次の3つの兆候を探してください。

• 完全性：スクリプトはローカルユーザーリスト全体をページ分割して表示します。
• 説明可能性：各候補者には、「最後にアクセスされたのは242日前、管理者アカウントでもサービスアカウントでもない」など、明確な理由が表示されます。
• 誤検知のリスクが低い：特別なアカウントやビジネス例外は、悪意のある通話が発生する前にフィルタリングされます。

これらのチェック項目を満たせない場合は、先に進む前にプロセスを変更してください。例えば、人間による承認段階を追加したり、非アクティブ状態警告を送信したり、非アクティブ化ではなく一時停止から始めたりしてください。

ステップ3：アカウントを無効化する前に、各アカウントを検査する

特定のローカルユーザーの場合、Synapse は以下を文書化します。

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

例：

USER_ID="@olduser:example.com"

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

応答には、アカウントの管理状態、無効化および削除フラグ、作成および最終アクセス日時、外部ID、サードパーティ識別子などが含まれる場合があります。ここで、対象のアカウントが意図したアカウントであることを確認してください。

erase trueとerase falseのどちらを使うべきでしょうか？

プロファイル情報を保持したままアクセスを無効にすることが運用上の目的である場合に使用します"erase": false。現在のSynapseのドキュメントによると、通常の無効化では、アクティブなアクセストークン、パスワードハッシュ、デバイスとエンドツーエンド暗号化キー、プッシャー、サードパーティID、ルームメンバーシップ、アカウントデータ、保留中の招待、および関連するアカウントの有効性情報が削除されます。

"erase": trueポリシーで表示名、アバターURL、カスタムプロファイルフィールドの削除、およびユーザーの削除済みマークも要求されている場合に使用します。削除とは、すべての履歴データが消去されることを意味するものではありません。Synapseは、このAPIでは以前に送信されたメッセージは削除されず、アップロードされたメディアも自動的に削除されないことを明示的に文書化しています。

その区別は非常に重要です。ポリシーでプロフィールの削除だけでなくコンテンツの削除も求められている場合、アカウントの無効化だけでは不十分です。

ステップ4：ドライラン、無効化、および検証

変更を実行する前に、最終的なユーザーIDをプレーンテキストまたはJSONファイルに書き込んで確認してください。ドライランは変更期間中は変更できない状態にしておく必要があります。ユーザーの無効化中に候補生成スクリプトが変更された場合は、処理を停止して承認済みリストを再生成してください。

承認済みのローカルユーザーごとに、ドキュメントに記載されている非アクティブ化エンドポイントを呼び出します。

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

プロファイル消去なしの例：

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"

プロファイル削除の例：

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"

その後、再度アカウントを照会してください。

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

正常に処理された場合は、 と表示されるはずです"deactivated": true。消去を要求した場合は、 も確認してください"erased": true。「API が HTTP 2xx を返した」という結果だけを成功の基準にしないでください。変更後にユーザーレコードを読み取ってください。

無効化によって実際に何が削除されるのですか？

現在のSynapseのドキュメントには、無効化による影響がいくつか記載されています。その中には、アクティブなアクセストークン、サードパーティ識別子、デバイス、エンドツーエンド暗号化キー、プッシャー、パスワードハッシュ、ルームメンバーシップ、保留中の招待、アカウントデータの削除が含まれます。また、ユーザーディレクトリからもユーザーが削除されます。

Synapseを使用するとerase: true、表示名、アバター URL、カスタム プロファイル フィールドも削除され、アカウントが削除済みとしてマークされます。

Synapseは、この操作では削除されない重要な項目も記録します。これには、送受信メッセージ、アップロードされたメディア、SSOマッピング、作成タイムスタンプ、レート制限の上書き、月間アクティブユーザー記録、および一部の同意情報が含まれます。記録されたリストは必ずしも網羅的なものではないため、アカウントの無効化はデータの完全な削除ではなく、アカウントのシャットダウンとして扱ってください。

ユーザーがアップロードしたメディアも削除する必要がありますか？

保持ポリシーでユーザーがアップロードしたローカルに保存されたメディアを削除する必要がある場合、Synapse は別のエンドポイントを提供します。

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

例：

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

ユーザーメディアAPIは、Synapseメディアリポジトリに保存されているローカルメディアとサムネイルを削除します。ドキュメントには、運用上重要な2つの制限事項が記載されています。まず、外部メディアリポジトリに保存されているメディアはこのAPIの影響を受けません。次に、制限を設定しない場合、エンドポイントはリクエストごとに100ファイルを削除するため、メディア履歴が多いユーザーは複数回の呼び出しが必要になる場合があります。

保持ポリシーで定められていない限り、メディアの自動削除は追加しないでください。これはアカウントの無効化よりもはるかに大きな影響を与え、履歴ルームで参照されているメディアにも影響を及ぼす可能性があります。

サスペンションを使うべきなのはどんな時ですか？

Synapseはアカウント停止APIについても文書化しています。アカウント停止中は、メッセージの送信、ルームへの参加、招待の送信、プロフィール情報の変更、およびほとんどの編集などのアクティビティがブロックされますが、アカウント無効化とは異なる復旧方法が提供されます。

一時停止は、一時的な管理上の保留が必要な場合、非アクティブ状態が不明確な場合、または退会手続きが進行中の場合に適しています。一方、アクセスを完全に停止し、トークン、デバイス、ルームメンバーシップ、アカウントデータなどを削除する必要がある場合は、無効化がより適切な選択肢となります。

自動クリーンアップの場合、段階的なポリシーの方が安全な場合が多い。

1. アカウントが一定期間利用されない場合にフラグを立てる。
2. 通知またはレビューする。
3. 所有権が不明確な場合は停止する。
4. 保持期間または承認期間が経過した後にのみ、無効化してください。

安全に清掃作業を自動化するにはどうすればよいでしょうか？

検出と非アクティブ化は別々のジョブとして実行してください。検出ジョブは読み取り専用とし、候補ファイルを生成します。実行ジョブは承認済みのファイルのみを処理し、すべてのリクエストとレスポンスのステータスをログに記録します。

生産品質のワークフローには、以下の点も含まれるべきです。

• すべてのページネーショントークンに従う。
• 数千件のリクエストを同時に送信するのではなく、大量のリクエストに対してレート制限を設ける。
• デフォルトでは、サーバー管理者と指定されたサービスアカウントを除外します。
• タイムスタンプをUTCで保存する。
• 各アカウントを選択したクリーンアップポリシーのバージョンを記録する。
• 認証、認可、またはサーバーエラーが繰り返し発生した場合に停止する。
• 無効化後に各ユーザーを再照会する。
• 管理アクセストークンはソースコードやログに含めないようにしてください。

変更後の検証結果が要求された状態と一致しない場合は、残りのバッチ処理をそのまま続行しないでください。最初の失敗の原因を調査し、問題が権限、APIバージョンの互換性、プロキシ構成の問題、Matrix Authentication Serviceとの統合、またはアカウント固有の条件のいずれであるかを判断してください。

最終チェックリスト

• サーバー管理者用のベアラートークンを使用してください。
• 最初の100ユーザーだけでなく、すべてのローカルユーザーページを列挙してください。
• 文書化された閾値と除外基準を用いて、非活動状態を定義する。
• 対策を講じる前に、リスクの高いアカウントを個別に検査してください。
• 予行演習リストを作成し、承認する。
• Synapseがアカウントの完全削除をサポートしていると想定するのではなく、アカウント無効化エンドポイントを使用してください。
• erase: trueプロフィールの削除がポリシーの一部となっている場合にのみ選択してください。
• 必要に応じて、アップロードされたメディアを個別に処理してください。
• 変更後deactivated、必要に応じて毎回確認してください。erased

最も信頼性の高いクリーンアップとは、後から説明できるものです。どの非アクティブルールでアカウントが選択されたのか、どの例外がチェックされたのか、どのAPIアクションが実行されたのか、そしてどの変更後フィールドで目的の状態が証明されたのかを明確に説明できるのです。このような基準は、一度に処理するアカウント数を最大化するよりもはるかに有用です。