Synapse OIDC를 통해 Element Web을 Keycloak에 연결합니다.

Element Web에 Keycloak 로그인 기능을 추가하려면 Synapse에서 Keycloak을 OpenID Connect(OIDC) 공급자로 구성한 다음 Element Web이 해당 Synapse 홈서버를 사용하도록 설정해야 합니다. Synapse가 인증 리디렉션 및 콜백을 처리하므로 Element Web에는 Keycloak 클라이언트 시크릿이 필요하지 않습니다.

예시 시나리오(가상): 소규모 조직에서 Element Web(주소: ) chat.example.org, Synapse(주소: ) matrix.example.org, Keycloak(주소: )을 운영하고 있습니다 login.example.org. 다른 호스트 이름에도 동일한 순서가 적용되지만, 모든 URL은 실제 공개 구성과 일치해야 합니다. 이 예시는 설명을 위한 것이며, 실제 운영 환경을 나타내는 것은 아닙니다.

설정을 변경하기 전에 필요한 사항

Keycloak과 Synapse에는 공개 HTTPS URL을 사용하십시오. Synapse의 OIDC 문서에서는 ID 공급자에 보안 오리진이 필요하며, 콜백은 공개 Synapse URL을 통해 접근 가능해야 한다고 명시하고 있습니다. Keycloak, Synapse의 영역 이름 public_baseurl과 Element Web에 제공되는 홈서버 URL을 확인하십시오. 리버스 프록시가 두 서비스 중 하나 앞에 있는 경우, 요청을 올바른 백엔드로 전달하고 외부 HTTPS 호스트 및 스키마를 유지해야 합니다.

Synapse의 현재 구성은 oidc_providers목록을 사용합니다. 기존의 단일 공급자 oidc_config형식은 더 이상 사용되지 않습니다. 테스트하는 동안 유효한 관리자 로그인 정보와 현재 구성 사본을 보관하십시오. SSO 흐름을 확인하고 계정 프로비저닝 방식을 결정하기 전까지는 암호 로그인 또는 등록을 비활성화하지 마십시오.

1. Keycloak에 Synapse를 클라이언트로 등록합니다.

조직의 사용자가 있는 Keycloak 환경에서 Synapse용 OpenID Connect 클라이언트를 생성합니다. Synapse의 공식 Keycloak 예제에서는 클라이언트 ID가 인 기밀 클라이언트를 사용합니다 synapse. 유효한 리디렉션 URI를 이 콜백으로 설정하되, Synapse 호스트 이름은 사용자 환경에 맞게 변경하십시오.

https://matrix.example.org/_synapse/client/oidc/callback

가상 설정에서 클라이언트 액세스 유형을 기밀로 설정하고 클라이언트를 활성화하십시오. 자격 증명 탭에서 생성된 클라이언트 암호를 암호 관리 시스템에 복사하십시오. Element Web의 공개 영역에 저장 config.json하거나 저장소에 게시하지 마십시오.

리디렉션 URI는 오류의 주요 원인 중 하나입니다. 반드시 Synapse의 공개 URL, 정확한 /_synapse/client/oidc/callback경로, 그리고 Synapse가 브라우저에서 인식하는 것과 동일한 스키마 및 호스트 이름을 사용해야 합니다. 정확한 URI로 충분한 경우, 광범위한 와일드카드 콜백을 사용하지 마십시오. 나중에 백채널 로그아웃을 활성화하는 경우, Keycloak에도 Synapse의 공식 백채널 엔드포인트를 추가해야 합니다. 이는 선택 사항이며 기본 로그인과는 별개입니다.

2. Synapse에 Keycloak 공급자를 추가합니다.

활성 항목을 편집하세요 homeserver.yaml. 아래의 영역과 비밀 키를 사용자 값으로 바꾸고, 영역의 OpenID 검색 문서에서 발급자 URL을 확인하세요. 표준 Keycloak 영역 발급자는 다음과 같은 형식을 갖습니다.

https://login.example.org/realms/your-realm

Synapse의 Keycloak 예제에 나와 있는 표준 검색 엔드포인트와 클레임을 사용하는 배포의 경우 공급자 항목은 다음과 같습니다.

oidc_providers:
  - idp_id: keycloak
    idp_name: "Company Login"
    issuer: "https://login.example.org/realms/your-realm"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_KEYCLOAK_SECRET"
    scopes: ["openid", "profile"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

발급자는 Keycloak 서버 루트가 아닌 Keycloak의 영역 발급자와 일치해야 합니다. 검색 기능을 통해 Synapse는 해당 발급자로부터 권한 부여, 토큰 및 사용자 정보 엔드포인트를 가져올 수 있습니다. 매핑은 Keycloak의 로컬파트를 사용하여 preferred_usernameMatrix 로컬파트와 name표시 이름을 생성합니다. 따라서 이러한 클레임이 사용자에게 존재하고 안정적인지 확인해야 합니다. Matrix 로컬파트는 계정 식별자이므로 나중에 매핑을 변경하면 계정 일치가 혼란스러워지거나 다른 Matrix ID가 생성될 수 있습니다.

다른 ID 공급자가 구성되어 있는 경우 기존 oidc_providers목록을 유지하고, 관련 없는 공급자를 교체하는 대신 이 항목을 추가하십시오. 클라이언트 암호를 비밀로 보호하고 배포 환경에 따라 파일 권한을 설정하십시오. YAML 들여쓰기를 확인한 다음 설치에 따라 서비스 또는 컨테이너 절차에 따라 Synapse를 다시 시작하십시오. 패키지 설치에는 이미 OIDC 종속성이 포함되어 있을 수 있습니다. 가상 환경 설치의 경우 Synapse 문서에서 설치 방법을 matrix-synapse[oidc]참조하십시오. 다른 설치 방법은 패키지 관리자의 지침을 따르십시오.

3. Point Element Web을 동일한 홈서버에 설치합니다.

Element Web은 config.jsonSynapse 서버를 홈서버로 식별해야 합니다 default_server_config.mHomeserver.base_url. 예를 들어, `/etc/elementweb.com ...

가상의 예시를 들자면, Element Web은 에 호스팅되어 https://chat.example.org에 연결됩니다 https://matrix.example.org. 사용자가 Element의 로그인 화면에서 SSO 옵션을 선택하면 브라우저는 Synapse의 로그인 흐름을 따라 Keycloak 영역으로 이동한 후 Synapse의 콜백으로 돌아와야 합니다. 정확한 버튼 문구와 로그인 화면 레이아웃은 Element Web 릴리스 및 서버 구성에 따라 다를 수 있으므로 특정 레이블에 의존하기보다는 동작을 테스트해야 합니다.

4. SSO를 적용하기 전에 하나의 계정으로 테스트하십시오.

개인 정보 보호 브라우저 창에서 Element Web을 열고 SSO 로그인 옵션을 선택합니다. 테스트용 Keycloak 사용자로 로그인하고, 액세스 권한이 요청되면 승인한 다음, 브라우저가 의도한 홈서버로 돌아가 예상되는 Matrix 계정이 열리는지 확인합니다. 생성된 Matrix ID에 의도한 localpart가 포함되어 있는지 확인합니다. 브라우저에서 오류가 발생하면 Synapse 및 Keycloak 로그를 검토합니다.

리디렉션이 실패하면 Keycloak의 콜백 URL과 Synapse의 공개 콜백 URL을 문자 단위로 비교하십시오. "발급자 불일치"는 잘못된 영역 발급자 또는 역방향 프록시 호스트 이름을 나타냅니다. 사용자 이름 누락 또는 매핑 오류는 구성된 클레임이 없거나 적합하지 않음을 의미합니다. 테스트 사용자의 클레임을 검사하고 매핑을 신중하게 조정하십시오. 브라우저가 Keycloak에 도달했지만 응답하지 않으면 Synapse 콜백에 대한 TLS 인증서 및 프록시 라우팅을 확인하십시오.

선택적 로그아웃: Synapse는 OIDC 백채널 로그아웃을 지원합니다. 이를 사용하려면 backchannel_logout_enabled: true해당 공급자 설정에서 로그아웃을 활성화하고 Keycloak의 백채널 로그아웃 URL을 구성하십시오 https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse는 Keycloak에서 세션 필수 옵션을 활성화하는 방법도 안내합니다. 이 옵션은 공급자가 시작하는 로그아웃 알림을 처리하며, 초기 SSO 로그인에는 필수 사항이 아닙니다.

배포 전: SSO를 통해 새로운 Matrix 사용자를 생성할지, 아니면 별도로 프로비저닝한 계정만 인증할지 결정한 다음, 설치된 버전의 Synapse OIDC 옵션을 검토하세요. 구성 레이블과 Keycloak 관리 UI는 릴리스 간에 변경될 수 있습니다. 여기에 설명된 단계는 2026년 10월 10일에 공개된 Synapse OIDC 문서를 따르며, 표준 Keycloak 영역과 문서화된 공급자 형식을 사용하는 Synapse 배포를 가정합니다. 버전별 설정을 적용하기 전에 Synapse OpenID Connect 및 Keycloak 가이드 , Synapse 구성 참조 및 Keycloak 공식 문서를 참조하세요 . 테스트 계정이 올바르게 로그인되고 복구 경로가 확보되면 관리자를 위해 최종 콜백, 발급자 및 클레임 매핑을 문서화하세요.

댓글 남기기

Synapse OIDC를 통해 Element Web을 Keycloak에 연결합니다.

Element Web 사용자가 클라이언트 암호를 노출하지 않고 ID 서버를 통해 로그인할 수 있도록 Keycloak OIDC 클라이언트와 Synapse 공급자를 구성하십시오.

Element Key 백업 및 교차 서명을 안전하게 설정하는 방법

Element Key 백업 및 교차 서명을 안전하게 설정하는 방법

복구 키를 저장하고, Element 세션을 확인하고, 암호화된 메시지 키를 백업과 계정 암호를 혼동하지 않고 복원할 수 있는지 확인하십시오.

클라이언트 동기화 중 Matrix Synapse 메모리 충돌 방지

Synapse 동기화 중 메모리 부족 오류를 진단하고, 캐싱을 안전하게 조정하고, 요청 백로그를 식별하고, 안정적인 메모리 사용을 확인합니다.

Synapse Federation TLS 인증서 오류 해결

보안 검사를 비활성화하지 않고 매트릭스 페더레이션 인증서 오류를 올바른 서버로 추적하고, TLS 체인 또는 CA 신뢰를 복구하고, 수정 사항을 확인합니다.

Synapse Matrix 서버를 Cloudflare 뒤에 안전하게 배치하세요

Synapse Matrix 서버를 Cloudflare 뒤에 안전하게 배치하세요

Cloudflare의 HTTPS 443 포트를 통해 Matrix 클라이언트와 페더레이션을 라우팅하여 Synapse 검색 기능을 유지하고 API 트래픽 캐싱이나 미디어 업로드 오류를 방지합니다.

PostgreSQL 덤프를 사용하여 Matrix Synapse를 안전하게 복원하세요

pg_dump를 사용하여 Synapse를 백업하고, 서명 키와 미디어를 보호하고, 오래된 일회용 키를 재사용하지 않고 깨끗한 PostgreSQL 데이터베이스에 복원하세요.

Docker를 사용하여 Mjölnir를 Matrix Room 관리 봇으로 실행하세요

Docker를 사용하여 Mjölnir를 Matrix Room 관리 봇으로 실행하세요

Mjölnir를 전용 Matrix 계정, 암호화된 관리실, Docker Compose, 정책 목록 및 권한 검사와 함께 설정하십시오.

모바일 로딩 속도 향상을 위해 네이티브 매트릭스 슬라이딩 동기화를 활성화하세요.

모바일 로딩 속도 향상을 위해 네이티브 매트릭스 슬라이딩 동기화를 활성화하세요.

기존 프록시를 건너뛰고 Synapse에 내장된 슬라이딩 동기화 기능을 구성하십시오. 클라이언트 검색을 확인한 다음 호환되는 전화기에서 회의실 목록 로딩 및 재연결 동작을 측정하십시오.

사용자 지정 홈서버를 사용하여 Nginx에서 Host Element Web을 운영합니다.

Element Web을 정적 사이트로 배포하고, Matrix 홈서버를 가리키도록 설정하고, HTTPS를 추가하고, Nginx를 구성하여 오래된 파일 없이 업데이트를 제공하도록 하십시오.

Raspberry Pi 4에서 경량 Matrix 홈서버 실행하기

64비트 라즈베리 파이 4에 Conduit를 설치하여 영구 데이터 저장, HTTPS 연동, 보호된 회원가입, 그리고 홈서버 작동 여부 확인 기능을 구성합니다.