Element Web에서 Keycloak을 사용하여 싱글 사인온(SSO)을 구성하는 방법

Element Web은 Keycloak에 대해 직접 인증하지 않습니다. Element는 Matrix 홈서버에 지원되는 로그인 방법을 요청하고, 홈서버는 Keycloak과 함께 OpenID Connect(OIDC) 인증을 완료한 후 사용자를 Element로 반환합니다. Synapse의 내장 OIDC 지원 기능을 사용하는 경우, Keycloak에서 기밀 OIDC 클라이언트를 구성하고 해당 공급자를 Synapse에 추가한 다음, Element Web에서 config.jsonSSO를 표시하거나 자동으로 시작하도록 설정을 조정할 수 있습니다.

이 가이드에서는 일반적인 배포 경로인 Synapse의 내장 OIDC 공급자를 사용합니다. 홈서버에서 Matrix Authentication Service(MAS)로 인증을 위임하는 경우, 아래 설명된 MAS 콜백 및 공급자 구성을 사용하십시오. 두 콜백 URL은 서로 다릅니다. 본 지침은 2026년 10월 6일에 Element Web 구성 문서, Synapse v1.144 OIDC 가이드, 최신 MAS 업스트림 SSO 가이드 및 Keycloak 26.8.0 관리 가이드를 기준으로 검토되었습니다. 배포 패키징 및 UI 레이블은 버전에 따라 다를 수 있습니다.

먼저, 어떤 인증 경로를 사용하는지 확인하십시오.

클라이언트를 생성하기 전에 Synapse 구성 및 배포 문서를 확인하십시오. 콜백은 Keycloak과 통신하는 구성 요소에 속해야 하며, Element의 웹사이트 URL을 콜백으로 등록하지 마십시오.

필요한 것

• Synapse의 공개 HTTPS URL(예: https://matrix.example.com)과 연결 가능한 Keycloak 영역 발급자(예: )입니다 https://sso.example.com/realms/company.
• Keycloak 영역 및 Synapse 구성 및 서비스에 대한 관리자 액세스 권한.
• 현재 구성의 백업과 로그인 실패 시 Synapse 로그 또는 서버 콘솔을 사용할 수 있는 방법이 필요합니다.
• 계정 프로비저닝에 대한 결정: 어떤 Keycloak 사용자가 로그인할 수 있는지, 어떤 클레임으로 사용자를 식별하는지, 그리고 기존 Matrix 계정을 유지해야 하는지 여부.

Synapse OIDC용 Keycloak 구성

1. 기밀 OIDC 클라이언트를 생성합니다.

Matrix 계정에 사용되는 영역에서 OpenID Connect 프로토콜을 사용하여 Synapse용 클라이언트를 생성합니다. Synapse에서 토큰 엔드포인트에 클라이언트 암호를 사용할 수 있도록 인증 코드 또는 표준 흐름 및 클라이언트 인증을 활성화합니다. 클라이언트 ID는 Synapse에서도 사용할 값으로 설정합니다(예: ) synapse.

유효한 리디렉션 URI를 정확한 Synapse 콜백으로 설정하십시오.

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

예시 호스트 이름을 Synapse에 실제로 구성된 공개 기본 URL로 바꾸십시오. *프로덕션 환경에서처럼 광범위한 와일드카드를 사용하지 마십시오. Keycloak은 리디렉션 URI를 검증하므로 호스트, 스키마, 경로 또는 후행 슬래시가 일치하지 않으면 "리디렉션 URI가 허용되지 않습니다" 오류가 발생할 수 있습니다.

클라이언트를 저장하고 생성된 비밀 키를 복사하여 서버 측 비밀 키로 저장하십시오. Element Web의 공개 저장소 config.json, 소스 코드 관리 시스템, 스크린샷 및 클라이언트 측 JavaScript에 해당 비밀 키를 노출하지 마십시오. Keycloak 관리 콘솔은 릴리스 버전에 따라 클라이언트 인증 또는 자격 증명에 대한 명칭이 다를 수 있으므로, 생성된 클라이언트가 기밀성을 유지하고 표준 인증 코드 흐름을 사용할 수 있는지 확인하십시오.

2. 발행자 및 청구 내용을 확인하십시오.

발급자는 Keycloak 서버 루트가 아닌 영역을 식별합니다. 이 예에서는 를 사용합니다 https://sso.example.com/realms/company. 영역의 OpenID 구성에 에서 접근할 수 있는지 <issuer>/.well-known/openid-configuration, 그리고 광고된 발급자가 Synapse에 지정할 값과 정확히 일치하는지 확인하십시오.

Synapse는 Keycloak 계정을 Matrix 사용자와 연결하기 위해 안정적인 ID 클레임이 필요합니다. Synapse의 OIDC 공급자는 일반적으로 OIDC 주체 클레임을 사용하여 외부 주체를 식별합니다. 아래의 사용자 이름 매핑은 preferred_usernameMatrix 로컬 파트로 이 클레임을 사용합니다. Keycloak이 해당 클레임을 실제로 반환하는지, 그리고 사용자 이름이 계정 정책에 따라 고유하고 안정적인지 확인하십시오. 조직에서 사용자 이름 변경을 허용하는 경우, 프로덕션 환경 구축 전에 매핑 전략을 선택하고 테스트하십시오. 예기치 않은 매핑 변경은 사용자가 어떤 Matrix 계정에 접속하는지에 영향을 줄 수 있습니다.

Synapse 구성

3. OIDC 공급자를 추가합니다.

Synapse의 기본 구성(일반적으로 `<Provider>`)에 공급자 항목을 추가합니다 homeserver.yaml. 다른 설정을 덮어쓰지 말고 기존 YAML 파일과 병합합니다. 영역 발급자와 실제 클라이언트 암호를 바꿔 입력하세요.

oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://sso.example.com/realms/company"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_CLIENT_SECRET"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

요청된 범위는 Keycloak이 반환할 수 있는 사용자 정보를 제어하며, 모든 클레임이 채워진다는 것을 보장하지는 않습니다. 이메일이나 표시 이름 가져오기가 필요하지 않은 경우 범위와 매핑을 그에 맞게 줄이십시오. 구성 파일은 배포 환경에 따라 서비스 관리자와 Synapse 프로세스만 읽을 수 있도록 설정하십시오. 컨테이너 또는 차트를 통해 Synapse를 관리하는 경우, 덮어쓰기될 생성된 파일을 편집하는 대신 지원되는 구성 소스에 공급자 설정을 입력하십시오.

4. 선택적으로 백채널 로그아웃을 구성할 수 있습니다.

기본적으로 한 서비스에서 로그아웃해도 다른 모든 서비스의 브라우저 세션이 자동으로 종료되는 것은 아닙니다. Keycloak 로그아웃 알림을 통해 Synapse 세션도 종료되도록 하려면 backchannel_logout_enabled: trueSynapse의 Keycloak 공급자 설정에서 해당 기능을 활성화하고 Keycloak의 백채널 로그아웃 URL을 다음과 같이 설정하십시오.

https://matrix.example.com/_synapse/client/oidc/backchannel_logout

이 기능은 선택 사항이며 로그아웃 정책 및 클라이언트 설정에 따라 달라집니다. Synapse 로그아웃과 Keycloak 로그아웃, 두 가지 로그아웃 방향을 모두 테스트하십시오. Element에서 로그아웃하는 것만으로 Keycloak 세션이 종료된다고 가정하지 마십시오.

5. Synapse를 재시작하고 테스트합니다.

배포 구성 검사를 통해 YAML 파일의 유효성을 검사한 다음, 패키지 또는 컨테이너 설정에서 지원하는 방법을 사용하여 Synapse를 다시 시작하거나 재로드하십시오. Synapse 로그에서 OIDC 검색, 클라이언트 인증, 콜백 또는 클레임 ​​매핑 오류를 확인하십시오. 먼저 테스트 계정을 사용하여 Matrix ID와 표시 이름이 예상 값인지 확인하십시오.

Element Web 구성

6. SSO를 선택 사항으로 유지하거나 자동으로 리디렉션합니다.

Synapse에서 OIDC 로그인을 알리면 Element Web은 SSO 로그인 옵션을 제공할 수 있습니다. Element의 sso_redirect_options설정은 브라우저 환경을 제어하며 Keycloak을 구성하거나 클라이언트 암호를 저장하지 않습니다. config.json환영 페이지 또는 로그인 페이지에 접속한 인증되지 않은 방문자를 사용 가능한 SSO 흐름으로 보내려면 Element Web에 다음과 같은 설정을 추가하세요.

{
  "sso_redirect_options": {
    "immediate": false,
    "on_welcome_page": true,
    "on_login_page": true
  }
}

SSO 로그인만 필요한 배포 환경에서는 "immediate": true인증되지 않은 모든 사용자에 대해 SSO를 시작하도록 설정하십시오. 이렇게 하면 비밀번호 또는 다른 로그인 옵션에 접근하기가 더 어려워질 수 있으므로, 적용하기 전에 복구 및 관리자 접근을 테스트해야 합니다. 사용자가 SSO와 다른 로그인 방법 중에서 선택해야 하는 경우, 자동 리디렉션을 비활성화하고 로그인 흐름에 SSO 옵션이 표시되는지 테스트하십시오.

Synapse가 Matrix 인증 서비스를 사용하는 경우

MAS는 별도의 인증 서비스이며 Keycloak의 OIDC 클라이언트 역할을 할 수 있습니다. 이 아키텍처에서는 Keycloak의 리디렉션 URI를 다음과 같이 구성해야 합니다 https://auth.example.com/upstream/callback/<provider-id>. 여기서 공급자 ID는 MAS 구성과 일치해야 합니다. MAS의 설정에서 공급자를 구성하면 upstream_oauth2.providers홈서버의 MAS 기반 인증 흐름을 사용하게 됩니다. 이 상위 연결에는 Synapse의 내장 기능을 사용하지 마십시오 /_synapse/client/oidc/callback. MAS는 권한 부여 코드 흐름을 지원하는 OIDC 공급자가 필요합니다. MAS의 구성 형식, 필수 공급자 ID 및 마이그레이션 단계는 Synapse의 내장 기능과 다릅니다 oidc_providers.

흔히 발생하는 오해와 해결책

• "Element 설정만 변경하면 됩니다." Element는 브라우저 흐름을 제어하고, Synapse 또는 MAS는 OIDC를 처리합니다. 먼저 홈서버 측 공급자를 올바르게 구성하십시오.
• "Keycloak 로그인 성공은 계정 매핑이 올바르다는 것을 증명합니다." 잘못된 로컬 파트 또는 프로필 클레임이 선택된 경우에도 인증이 성공할 수 있습니다. 비운영 사용자 계정으로 테스트하고 결과로 생성된 Matrix ID를 확인하십시오.
• "SSO는 자동으로 암호 및 등록 기능을 비활성화합니다." 이러한 정책은 홈서버 및 배포 환경에 따라 제어됩니다. Synapse의 로그인 및 등록 설정을 별도로 검토하고 승인된 정책을 확인하십시오.
• "Element에서 로그아웃하면 모든 곳에서 로그아웃됩니다." 하지만 Keycloak에서는 브라우저 세션이 활성 상태로 유지될 수 있습니다. 중앙 집중식 세션 종료가 필요한 경우 백채널 로그아웃을 구성하고 테스트하십시오.

검증 체크리스트

• Keycloak 클라이언트는 권한 부여 코드 흐름, 클라이언트 인증 및 Synapse 또는 MAS에 대한 정확한 콜백을 사용합니다.
• 발급자 URL은 영역의 검색 메타데이터와 일치하며 클라이언트 비밀 키는 서버 측에 저장됩니다.
• Synapse 또는 MAS는 OIDC 구성 오류 없이 시작되며 의도된 로그인 방법을 표시합니다.
• 테스트 사용자는 새 브라우저 세션에서 로그인하여 예상되는 Matrix 계정에 접속하고 일반적인 Element 세션을 완료할 수 있습니다.
• 로그아웃 동작, 기존 계정, 등록 제한 및 대체 관리자 액세스 권한이 정책과 일치하는지 확인하십시오.

공식 참고 자료

• Synapse v1.144 OpenID Connect 가이드 (Keycloak 클라이언트 및 콜백 설정 포함)
• Element Web 구성: SSO 리디렉션 옵션
• Matrix 인증 서비스: 상위 SSO 공급자 구성
• Keycloak 26.8.0 서버 관리 가이드