자체 호스팅 Matrix 서버에서 사용자 등록을 제한하는 방법

자체 호스팅 Matrix 서버에서 "가입 제한"은 모든 공개 가입을 차단하는 것부터 초대 코드가 있는 사람만 가입할 수 있도록 허용하는 것까지 다양한 의미를 가질 수 있습니다. Synapse의 경우 가장 간단한 방법은 공개 가입을 비활성화하는 것입니다. 새로운 사용자가 가입할 수 있도록 하려면 가입 토큰을 요구하고 각 사용자에게 사용 기간이 제한된 토큰을 발급하세요. 이러한 설정은 새로운 로컬 계정 생성에만 적용되며, 기존 사용자를 삭제하거나 Matrix 연동을 비활성화하지는 않습니다.

서버에 맞는 컨트롤을 선택하세요.

목표	시냅스 접근법	주요 절충점
관리자만 계정을 생성할 수 있습니다.	설정 `enable_registration: false`; 관리자 CLI 또는 제어된 관리자 워크플로를 사용하십시오.	Matrix 클라이언트에서는 회원가입이 불가능합니다. 공유된 등록 비밀 키는 반드시 보호하십시오.
소규모 커뮤니티를 초대하세요	회원가입을 활성화하고 회원가입 토큰을 필수로 설정하며, 일회용 단기 토큰을 발급합니다.	관리자는 토큰을 배포하고 관리해야 합니다. 유효한 토큰을 받은 사람은 누구나 해당 토큰을 사용할 수 있습니다.
누구나 가입할 수 있도록 허용	회원가입은 계속 열어두고, CAPTCHA나 토큰과 같은 적절한 악용 방지 조치와 함께 가입 속도 제한 및 모니터링 기능을 추가하세요.	정당한 사용자에게 더 많은 불편함이 초래되고, 어떤 단일 검증 절차도 악용으로부터의 보호를 보장하지 못합니다.
ID 공급자를 사용하세요	접근 권한에 사전 승인이 필요한 경우, 공급자의 Synapse 설정에서 SSO를 구성하고 자동 계정 생성을 비활성화하십시오.	ID 공급자 관리가 필요합니다. 유효한 SSO 로그인이 반드시 기존 Matrix 계정을 의미하는 것은 아닙니다.

아래 예시는 Synapse를 기준으로 작성되었습니다. Dendrite, Conduit 및 기타 홈서버 구현은 다른 구성 및 관리 인터페이스를 사용합니다. Synapse 설정을 적용하기 전에 해당 서버의 설명서를 참조하십시오.

옵션 1: 공개 등록 기능을 끄기

개인용 홈 서버, 소규모 조직 또는 관리자가 각 계정을 프로비저닝하는 서버의 경우 활성 Synapse 구성에서 클라이언트 등록을 비활성화하십시오.

enable_registration: false

Synapse 문서에는 이 설정이 기본적으로 비활성화되어 있다고 나와 있습니다. 서비스 또는 컨테이너가 실제로 로드하는 구성 파일을 편집하고 YAML 유효성을 검사한 다음 일반적인 서비스 관리 프로세스에 따라 Synapse를 다시 시작하십시오. Docker 배포의 경우 호스트 경로에서 구성을 마운트할 수 있으므로 컨테이너 내부의 유사한 이름의 파일을 편집해도 시작 시 사용되는 파일이 변경되지 않을 수 있습니다.

등록 기능이 비활성화된 경우, 사용자는 일반적인 클라이언트 등록 절차를 통해 새 계정을 만들 수 없습니다. 관리자는 지원되는 관리 방법을 통해 계정을 계속 생성할 수 있습니다. Synapse는 이 설정이 비활성화된 registration_shared_secret경우에도 해당 암호를 사용하여 계정 enable_registration을 생성할 수 있도록 허용한다는 점을 명확히 경고합니다. 암호는 매우 중요한 자격 증명으로 취급해야 합니다. 저장소, 채팅 및 공개 환경 덤프에 암호를 노출하지 말고, 접근을 제한하고, 관리 워크플로에 필요한 경우에만 보관하십시오. 암호를 아는 사람은 관리자 계정을 포함하여 누구나 계정을 생성할 수 있습니다.

OIDC, CAS 또는 다른 SSO 통합을 사용하는 경우 해당 공급자의 자동 등록 설정도 확인하십시오. Synapse는 공급자 수준의 등록 스위치를 문서화하는데, 그렇지 않으면 첫 번째 SSO 로그인 성공 시 사용자가 자동으로 생성될 수 있기 때문입니다. OIDC의 경우 oidc_providers[].enable_registration일반 등록 설정도 검토하십시오.

옵션 2: 토큰을 통해서만 등록을 허용합니다.

회원이 직접 계정을 생성할 수 있어야 하지만, 가입은 관리자의 승인 또는 배포가 필요한 경우 등록 토큰을 사용하십시오. Synapse 구성에서 두 값을 모두 설정하십시오.

enable_registration: true
registration_requires_token: true

두 가지 모두 필요합니다. 토큰 설정을 하려면 등록 시 토큰이 필요하며, 등록 자체도 활성화되어 있어야 합니다. 변경 사항을 적용하고 Synapse를 다시 시작하십시오. 이 설정을 변경해도 기존 계정과 이전에 생성된 토큰은 삭제되지 않습니다.

사용 횟수가 제한된 토큰을 생성하세요

Synapse는 등록 토큰 관리자 API를 제공합니다. 요청에는 관리자 액세스 토큰이 필요합니다. 예를 들어, 다음 요청은 하나의 등록을 완료할 수 있는 토큰을 생성합니다.

curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/registration_tokens/new" \
  -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"uses_allowed": 1}'

환경 변수를 홈서버 기본 URL과 관리자 액세스 토큰으로 바꾸세요. 관리자 토큰은 비공개로 유지하고, 실제 자격 증명이 포함된 명령어를 공유 로그나 지원 게시물에 붙여넣지 마세요. API는 유닉스 에포크 이후 밀리초 단위의 만료 시간도 허용합니다. 개별 초대에는 일회용 토큰을 사용하고, 워크플로에서 만료 시간을 안정적으로 계산하고 관리할 수 있을 때 만료 시간을 설정하세요. 사용 횟수 제한이 없는 토큰은 사용 횟수 제한이 없고 만료 시간이 없을 수 있으므로 배포하기 전에 반환되는 필드를 검토하세요.

토큰을 확인하려면 관리자는 해당 API를 호출할 수 있습니다 GET /_synapse/admin/v1/registration_tokens. 응답에는 허용된 사용 횟수, 등록 대기 중, 등록된 완료 횟수 및 만료일이 포함됩니다. 토큰이 유출된 경우, 허용된 사용 횟수를 0으로 업데이트하거나 문서화된 관리자 API를 통해 삭제하십시오. 토큰은 가입 자격 증명이며 Matrix 회의실 초대가 아닙니다. 따라서 새 계정을 자동으로 회의실에 초대하는 것은 아닙니다.

중요 호환성 참고 사항: Matrix Authentication Service(MAS) 통합이 활성화된 경우 Synapse의 등록 토큰 관리자 API가 비활성화됩니다. 이 경우 배포 환경에 맞게 작성된 MAS 관리자 API 또는 MAS CLI를 사용하십시오. Synapse 토큰 명령이 MAS에서도 변경 없이 작동할 것이라고 가정하지 마십시오.

옵션 3: 공개 등록에 확인 절차 추가

누구나 계정을 요청할 수 있도록 하려면 토큰을 요구하는 것은 지나치게 제한적일 수 있습니다. Synapse 구성 문서에는 CAPTCHA 및 타사 식별자 요구 사항이 가능한 확인 절차로 명시되어 있습니다. CAPTCHA는 제공업체가 올바르게 구성되어 있어야 작동하며 접근성 및 개인정보 보호 측면에서 추가적인 부담을 줄 수 있습니다. 이메일 주소나 전화번호를 요구하는 것은 설정 및 검증에 필요한 추가적인 절차를 요구할 수 있으며, 각 계정을 개별적으로 승인하는 것과는 다릅니다. 타사 식별자(3PID)를 요구하기 전에 사용 중인 버전과 클라이언트 흐름에서 실제로 지원하는 인증 서비스를 확인하십시오.

속도 제한은 반복적인 요청을 줄여주기 때문에 이러한 제어 기능과 함께 유용하지만, 누가 등록할 수 있는지를 결정하는 기능은 아닙니다. 등록 시도 및 서버 로그를 모니터링하고 트래픽 및 배포 환경에 맞게 제한을 조정하십시오. 설치된 Synapse 버전을 확인하지 않고 이전 구성 스니펫을 복사하지 마십시오. 등록 및 ID 서비스 옵션은 시간이 지남에 따라 변경되었습니다.

등록 종료가 변경하는 사항과 변경하지 않는 사항은 무엇입니까?

이 기능은 새로운 로컬 계정을 제어합니다. 등록을 비활성화하면 홈 서버에서 일반적인 계정 생성 절차가 차단됩니다.
이 기능은 계정을 삭제하지 않습니다. 기존 사용자는 별도로 계정을 정지하거나 비활성화하지 않는 한 계정을 유지합니다.
이 기능은 페더레이션을 비활성화하지 않습니다. 다른 홈서버의 사용자는 방 멤버십 및 페더레이션 설정에 따라 로컬 사용자 및 방과 계속 통신할 수 있습니다.
이 기능은 방을 초대 전용으로 만들지 않습니다. 방 참가 규칙은 별도의 설정이며, 등록 토큰은 방 초대 기능을 대체하지 않습니다.
모든 프로비저닝 경로를 차단하는 것은 아닙니다. 관리자 API, 구성된 공유 비밀 키, 애플리케이션 서비스 및 SSO 계정 생성 설정은 별도로 검토해야 합니다.

등록 URL을 숨기는 리버스 프록시 규칙은 추가적인 네트워크 계층 제어 수단이 될 수 있지만, 클라이언트 흐름을 방해하기 쉽고 홈서버 자체의 설정을 대체할 수는 없습니다. 애플리케이션 수준 설정을 기본 제어 수단으로 사용하고 프록시 설정을 변경한 후에는 실제 배포 환경을 테스트하십시오.

결과를 확인하세요

의도된 등록 값을 확인하려면 컨테이너 바인드 마운트 또는 생성된 구성을 포함한 유효 구성 소스를 확인하십시오.
Synapse를 다시 시작하고 시작 로그에서 YAML 오류 또는 지원되지 않는 설정이 있는지 확인하십시오.
Matrix 클라이언트에서 로그아웃한 상태로 새 회원가입을 시도해 보세요. 회원가입이 비활성화된 경우, 사용 가능한 공개 회원가입 페이지가 표시되지 않아야 합니다. 토큰 필수 회원가입이 활성화된 경우, 유효한 토큰이 없는 요청은 완료되지 않아야 합니다.
토큰 등록의 경우, 일회용 임시 토큰으로 테스트하여 계정이 하나만 생성되는지 확인하십시오. 관리자 API 응답에서 completed, pending, 만료 정보를 확인하십시오.
별도로 구성된 SSO 경로와 계정 프로비저닝 스크립트를 테스트하십시오. 이러한 요소들이 액세스 정책에 따라 제대로 작동하는지 확인하십시오.

실제 초대 토큰을 사용할 의도가 없다면 테스트 계정에 사용하지 마십시오. 설정이 적용되지 않는 경우, 먼저 Synapse가 실제로 로드하는 파일을 변경했는지, 그리고 서비스가 다시 시작되었는지 확인하십시오. 그런 다음 공유 등록 비밀 키, SSO 자동 등록 또는 다른 신뢰할 수 있는 프로비저닝 메커니즘을 확인하십시오.

공식 참고 자료

Synapse의 버전 관리 구성 및 관리자 API 문서는 옵션 이름과 요청 필드에 대한 정확한 정보를 제공하는 기준입니다. 위의 지침은 특정 운영 체제, 컨테이너 이미지, 리버스 프록시 또는 Matrix 클라이언트를 가정하지 않으므로, 변경 사항을 적용하기 전에 배포 환경별 세부 정보를 확인하십시오.