Matrix Synapse에서 관리자 API를 통해 비활성 사용자 계정을 삭제하는 방법

Matrix Synapse에서는 비활성 계정을 삭제하는 것과 비활성화하는 것에 중요한 차이가 있습니다 . Synapse의 공식 관리자 API는 사용자와 관련된 모든 데이터베이스 레코드를 완전히 삭제하는 일반적인 계정 영구 삭제 엔드포인트를 제공하지 않습니다. 지원되는 관리 워크플로는 계정을 식별하고 검토한 후 비활성화 엔드포인트를 호출하는 것입니다. 필요에 따라 "erase": true프로필 정보를 삭제하고 사용자를 삭제된 것으로 표시할 수 있습니다.

따라서 바람직한 결과는 "사용자 ID가 모든 Synapse 테이블에서 사라지는 것"이 ​​아닙니다. 바람직한 결과는 사용자가 더 이상 인증할 수 없게 되고, 활성 토큰과 장치가 제거되고, 계정이 채팅방에서 제외되고, 제3자 식별자가 삭제되며, 정책에 따라 프로필이 완전히 삭제되는 것입니다. 업로드된 미디어와 과거 메시지는 별개의 문제이며 계정 비활성화 시 자동으로 삭제되지 않습니다.

이 가이드는 2026년 10월 기준 최신 Synapse 관리자 API 문서를 사용합니다. 특히 장기간 운영되는 Synapse 환경을 구축했거나 Matrix 인증 서비스를 사용하는 경우, 예제를 사용 중인 홈서버 버전의 문서와 반드시 비교하십시오. 공식적인 참조 자료는 Synapse 사용자 관리자 API 문서 , Synapse 관리자 API 개요 및 Synapse 미디어 관리자 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는 페이지네이션을 지원합니다. 응답에 `<page>`가 포함되어 있으면 next_token해당 값을 사용하여 다음 페이지를 요청하십시오 from. 첫 번째 페이지가 서버의 전체 페이지를 나타낸다고 가정하지 마십시오.

API는 계정 정리 결정을 위한 유용한 필드를 제공합니다. 여기에는 계정이 관리자인지 여부, 사용자 유형, 이미 비활성화되었는지 여부, 생성 날짜 및 마지막 접속 시간이 포함됩니다. 문서에서는 last_seen_ts마지막 접속 시간을 유닉스 에포크 이후 밀리초 단위로 나타낸 사용자의 마지막 활동 타임스탬프로 정의합니다.

“비활성”이란 무엇을 의미하나요?

일반적으로 "180일 동안 활동 금지" 정책이 통용되지만, 적절한 기간은 환경에 따라 다릅니다. 소규모 개인 서버는 90일이면 충분할 수 있습니다. 대학, 계절별 운영 단체 또는 동창회 서비스 기관은 365일 이상이 필요할 수도 있습니다.

형식화된 날짜를 비교하는 대신 절대적인 시간 차이를 기준으로 타임스탬프를 설정하세요. 예를 들어, 파이썬 작업을 통해 임계값을 밀리초 단위로 계산할 수 있습니다.

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생성 타임스탬프, 관리자 플래그, 계정 유형 및 비활성 규칙을 통과한 이유가 포함되어야 합니다. 이러한 증거를 보관하면 향후 검토 및 롤백 결정을 훨씬 쉽게 내릴 수 있습니다.

후보자 선정 과정이 충분히 훌륭하다고 어떻게 확신하시나요?

다음 세 가지 징후를 찾아보세요:

• 완전성: 스크립트가 로컬 사용자 목록 전체를 페이지별로 순회합니다.
• 설명 가능성: 각 후보에는 "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, 제3자 식별자 등이 포함될 수 있습니다. 이 단계에서 해당 계정이 의도한 계정인지 확인해야 합니다.

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 문서에는 비활성화 시 발생하는 여러 가지 효과가 나열되어 있습니다. 이러한 효과에는 활성 액세스 토큰, 타사 식별자, 장치, 종단 간 암호화 키, 푸셔, 암호 해시, 회의실 멤버십, 보류 중인 초대 및 계정 데이터 제거가 포함됩니다. 또한 사용자 디렉터리에서 사용자가 삭제됩니다.

이 기능을 사용하면 erase: trueSynapse에서 표시 이름, 아바타 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 미디어 저장소에 저장된 로컬 미디어와 썸네일을 삭제합니다. 문서에는 운영상 중요한 두 가지 제한 사항이 명시되어 있습니다. 첫째, 외부 미디어 저장소에 저장된 미디어는 이 API의 영향을 받지 않습니다. 둘째, 제한을 설정하지 않으면 엔드포인트는 요청당 100개의 파일을 삭제하므로 미디어 이력이 많은 사용자는 여러 번 호출해야 할 수 있습니다.

보존 정책에 명시되어 있지 않은 한 미디어 자동 삭제 기능을 추가하지 마십시오. 이는 계정 비활성화보다 훨씬 더 심각한 손상을 초래할 수 있으며, 기록 보관소에 여전히 참조되고 있는 미디어에도 영향을 미칠 수 있습니다.

언제 현탁액을 사용해야 할까요?

Synapse는 계정 정지 API에 대한 문서도 제공합니다. 계정 정지는 메시지 전송, 채팅방 참여, 초대 전송, 프로필 정보 변경 및 대부분의 개인 정보 삭제와 같은 활동을 차단하며, 계정 비활성화와는 다른 복구 경로를 제공합니다.

일시 정지는 관리자의 일시 중단 조치가 필요할 때, 활동이 없는 이유가 불확실할 때, 또는 퇴사 검토가 진행 중일 때 더 적합합니다. 계정 비활성화는 접근 권한을 완전히 종료하고 토큰, 기기, 회의실 멤버십 및 계정 데이터를 삭제해야 할 때 더 강력한 선택입니다.

자동화된 정리 작업의 경우, 단계별 정책을 사용하는 것이 더 안전한 경우가 많습니다.

1. 일정 기간 동안 활동이 없으면 계정에 플래그를 지정합니다.
2. 이를 알리거나 검토하십시오.
3. 소유권이 불확실한 경우 중단하십시오.
4. 보존 기간이나 승인 기간이 지난 후에만 비활성화하십시오.

정리 작업을 안전하게 자동화하려면 어떻게 해야 할까요?

검색과 비활성화를 별도의 작업으로 유지하십시오. 검색 작업은 읽기 전용이어야 하며 후보 파일을 생성해야 합니다. 실행 작업은 승인된 파일만 사용하고 모든 요청 및 응답 상태를 로그에 기록해야 합니다.

고품질 프로덕션 워크플로는 다음과 같은 사항도 포함해야 합니다.

• 모든 페이지네이션 토큰을 따르십시오.
• 수천 건의 요청을 동시에 보내는 대신 대량 요청에 대한 속도 제한을 적용합니다.
• 기본적으로 서버 관리자와 명명된 서비스 계정은 제외됩니다.
• 타임스탬프를 UTC로 저장합니다.
• 각 계정에 적용된 정리 정책 버전을 기록합니다.
• 인증, 권한 부여 또는 반복적인 서버 오류 발생 시 중지합니다.
• 사용자 비활성화 후 각 사용자에 대해 다시 조회합니다.
• 관리자 액세스 토큰을 소스 코드와 로그에 포함시키지 마십시오.

변경 후 검증 결과가 요청된 상태와 일치하지 않으면 나머지 배치 작업을 무턱대고 진행하지 마십시오. 초기 실패 원인을 조사하여 권한 문제, API 버전 호환성 문제, 프록시 구성 문제, Matrix 인증 서비스 통합 문제 또는 계정별 조건 중 어떤 것이 문제의 원인인지 파악하십시오.

최종 체크리스트

• 서버 관리자용 베어러 토큰을 사용하십시오.
• 처음 100명의 사용자뿐만 아니라 모든 로컬 사용자 페이지를 열거하십시오.
• 문서화된 임계값 및 제외 기준을 사용하여 비활성 상태를 정의하십시오.
• 위험도가 높은 계좌는 조치를 취하기 전에 개별적으로 검토하십시오.
• 사전 테스트 목록을 생성하고 승인합니다.
• Synapse가 계정의 완전한 영구 삭제를 지원한다고 가정하기보다는 비활성화 엔드포인트를 사용하십시오.
• erase: true프로필 삭제가 정책에 포함된 경우에만 선택하세요 .
• 업로드된 미디어는 필요한 경우 별도로 처리합니다.
• 변경 사항을 확인 deactivated하고, 필요한 경우 erased변경 후 다시 확인하십시오.

가장 신뢰할 수 있는 정리 방법은 사후에 설명이 가능한 방법입니다. 즉, 어떤 비활성 규칙이 계정을 선택했는지, 어떤 예외를 확인했는지, 어떤 API 작업을 수행했는지, 그리고 어떤 변경 후 필드가 원하는 상태를 증명했는지 등을 설명할 수 있어야 합니다. 이러한 기준은 단순히 한 번에 처리하는 계정 수를 최대화하는 것보다 훨씬 유용합니다.