Jak skonfigurować logowanie jednokrotne (SSO) za pomocą Keycloak w Element Web

Element Web nie uwierzytelnia się bezpośrednio w Keycloak. Element pyta swój serwer domowy Matrix o obsługiwane metody logowania; serwer domowy nawiązuje połączenie OpenID Connect (OIDC) z Keycloak i odsyła użytkownika do Element. W przypadku wdrożenia Synapse z wbudowaną obsługą OIDC, należy skonfigurować poufnego klienta OIDC w Keycloak, dodać tego dostawcę do Synapse i opcjonalnie dostosować ustawienia Element Web, config.jsonaby wyświetlały lub automatycznie uruchamiały logowanie jednokrotne.

W tym przewodniku wykorzystano wbudowanego dostawcę OIDC Synapse, który jest powszechną ścieżką wdrażania. Jeśli serwer domowy deleguje uwierzytelnianie do usługi Matrix Authentication Service (MAS), należy zamiast tego użyć konfiguracji wywołania zwrotnego MAS i dostawcy opisanej poniżej. Te dwa adresy URL wywołania zwrotnego różnią się. Instrukcje zostały sprawdzone pod kątem dokumentacji konfiguracji Element Web, przewodnika OIDC Synapse v1.144, aktualnego przewodnika MAS upstream SSO oraz przewodnika administracyjnego Keycloak 26.8.0 z 6 października 2026 r.; pakiety wdrożeniowe i etykiety interfejsu użytkownika mogą się różnić w zależności od wersji.

Najpierw zidentyfikuj ścieżkę uwierzytelniania, której używasz

Przed utworzeniem klienta sprawdź dokumentację konfiguracji i wdrożenia Synapse. Wywołanie zwrotne musi należeć do komponentu, który komunikuje się z Keycloak; nie rejestruj adresu URL witryny Element jako wywołania zwrotnego.

Czego potrzebujesz

• Publiczny adres URL HTTPS dla usługi Synapse, taki jak https://matrix.example.com, oraz dostępny wystawca domeny Keycloak, taki jak https://sso.example.com/realms/company.
• Dostęp administracyjny do domeny Keycloak oraz konfiguracji i usługi Synapse.
• Kopia zapasowa bieżącej konfiguracji i sposób na wykorzystanie dzienników Synapse lub konsoli serwera w przypadku niepowodzenia logowania.
• Decyzja dotycząca tworzenia kont: którzy użytkownicy Keycloak mogą się logować, które roszczenie ich identyfikuje i czy istniejące konta Matrix muszą zostać zachowane.

Skonfiguruj Keycloak dla Synapse OIDC

1. Utwórz poufnego klienta OIDC

W domenie używanej dla kont Matrix utwórz klienta dla Synapse, używając protokołu OpenID Connect. Włącz kod autoryzacji lub standardowy przepływ i uwierzytelnianie klienta, aby Synapse mógł używać tajnego klucza klienta w punkcie końcowym tokena. Ustaw identyfikator klienta na wartość, której będziesz używać również w Synapse, na przykład synapse.

Ustaw prawidłowy adres URI przekierowania na dokładne wywołanie zwrotne Synapse:

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

Zastąp przykładową nazwę hosta publicznym adresem URL bazowym, który jest faktycznie skonfigurowany dla Synapse. Nie używaj szerokiego symbolu wieloznacznego, takiego jak *w środowisku produkcyjnym. Keycloak weryfikuje adresy URI przekierowań, więc niezgodność hosta, schematu, ścieżki lub ukośnika może spowodować błąd „adres URI przekierowania jest niedozwolony”.

Zapisz klienta, skopiuj wygenerowany klucz tajny i przechowuj go jako klucz tajny po stronie serwera. Nie udostępniaj go publicznie config.json, w systemie kontroli źródła, zrzutach ekranu ani w kodzie JavaScript po stronie klienta w Element Web. Konsola administracyjna Keycloak może oznaczać uwierzytelnianie klienta lub dane uwierzytelniające inaczej w różnych wersjach; sprawdź, czy wygenerowany klient jest poufny i może korzystać ze standardowego przepływu kodu autoryzacyjnego.

2. Potwierdź wystawcę i roszczenia

Wystawca identyfikuje domenę, a nie katalog główny serwera Keycloak. W tym przykładzie użyj https://sso.example.com/realms/company. Sprawdź, czy konfiguracja OpenID domeny jest dostępna pod adresem <issuer>/.well-known/openid-configurationi czy jej reklamowany wystawca dokładnie odpowiada wartości, którą podasz Synapse.

Synapse potrzebuje stabilnego oświadczenia tożsamości, aby powiązać konto Keycloak z użytkownikiem Matrix. Dostawca OIDC zazwyczaj identyfikuje podmiot zewnętrzny za pomocą oświadczenia podmiotu OIDC; mapowanie nazwy użytkownika poniżej wykorzystuje preferred_usernamelokalną część Matrix. Upewnij się, że Keycloak faktycznie zwraca to oświadczenie i że nazwy użytkowników są unikalne i stabilne zgodnie z polityką Twojego konta. Jeśli Twoja organizacja zezwala na zmiany nazw użytkowników, wybierz i przetestuj strategię mapowania przed rozpoczęciem produkcji; nieoczekiwana zmiana w mapowaniu może wpłynąć na to, do którego konta Matrix uzyska dostęp dana osoba.

Konfiguruj Synapse

3. Dodaj dostawcę OIDC

Dodaj wpis dostawcy do głównej konfiguracji Synapse, zazwyczaj homeserver.yaml. Scal go z istniejącym plikiem YAML zamiast zastępować inne ustawienia. Zastąp wystawcę domeny i prawdziwy klucz tajny klienta:

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 }}"

Żądane zakresy kontrolują, jakie informacje o użytkowniku może zwrócić Keycloak; nie gwarantują one, że każde zgłoszenie zostanie wypełnione. Jeśli nie potrzebujesz importu adresu e-mail ani nazwy wyświetlanej, odpowiednio zmniejsz zakresy i mapowanie. Plik konfiguracyjny powinien być dostępny do odczytu tylko dla administratora usługi i procesu Synapse, stosownie do potrzeb wdrożenia. Jeśli zarządzasz Synapse za pomocą kontenerów lub diagramu, umieść ustawienia dostawcy w obsługiwanym źródle konfiguracji, zamiast edytować wygenerowany plik, który zostanie nadpisany.

4. Opcjonalnie skonfiguruj wylogowanie z kanału tylnego

Domyślnie wylogowanie z jednej usługi nie musi kończyć sesji przeglądarki w pozostałych usługach. Jeśli chcesz, aby powiadomienia o wylogowaniu Keycloak kończyły sesję Synapse, włącz tę opcję backchannel_logout_enabled: truew dostawcy Keycloak w Synapse i ustaw adres URL wylogowania Backchannel Keycloak na:

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

Jest to opcjonalne i zależy od polityki wylogowywania oraz konfiguracji klienta. Przetestuj oba kierunki wylogowania: wylogowanie z Synapse i wylogowanie z Keycloak. Nie zakładaj, że samo wylogowanie z Element zakończy sesję Keycloak.

5. Uruchom ponownie i przetestuj Synapse

Sprawdź plik YAML za pomocą kontroli konfiguracji wdrożenia, a następnie uruchom ponownie lub przeładuj Synapse, używając metody obsługiwanej przez konfigurację pakietu lub kontenera. Przejrzyj logi Synapse pod kątem błędów wykrywania OIDC, uwierzytelniania klienta, wywołania zwrotnego lub mapowania roszczeń. Najpierw użyj konta testowego i upewnij się, że jego identyfikator macierzy i nazwa wyświetlana są wartościami oczekiwanymi.

Konfiguruj Element Web

6. Zachowaj opcję SSO lub przekieruj automatycznie

Gdy Synapse ogłosi logowanie OIDC, Element Web może udostępnić opcję logowania jednokrotnego (SSO). Ustawienie Element Web sso_redirect_optionskontroluje działanie przeglądarki; nie konfiguruje Keycloak ani nie przechowuje tajnego klucza klienta. Dodaj takie ustawienie do obsługiwanych ustawień Element Web, config.jsonjeśli chcesz, aby nieuwierzytelnieni użytkownicy odwiedzający stronę powitalną lub stronę logowania byli kierowani do dostępnego przepływu logowania jednokrotnego (SSO):

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

W przypadku wdrożenia, które faktycznie wymaga logowania tylko za pomocą logowania jednokrotnego (SSO), należy skonfigurować "immediate": trueuruchamianie logowania jednokrotnego (SSO) dla wszystkich nieuwierzytelnionych użytkowników. Może to utrudnić dostęp do hasła lub innych opcji logowania, dlatego przed wymuszeniem tej opcji należy przetestować odzyskiwanie i dostęp administratora. Jeśli użytkownicy muszą wybierać między logowaniem jednokrotnym (SSO) a inną metodą, należy wyłączyć automatyczne przekierowywanie i sprawdzić, czy opcja logowania jednokrotnego (SSO) pojawia się w procesie logowania.

Jeśli Synapse używa usługi uwierzytelniania Matrix

MAS to oddzielna usługa uwierzytelniania, która może działać jako klient OIDC dla Keycloak. W tej architekturze należy skonfigurować adres URI przekierowania Keycloak jako https://auth.example.com/upstream/callback/<provider-id>, gdzie identyfikator dostawcy jest zgodny z konfiguracją MAS. Skonfiguruj dostawcę w MAS upstream_oauth2.providers; element następnie używa przepływu uwierzytelniania opartego na MAS serwera domowego. Nie należy używać Synapse /_synapse/client/oidc/callbackdo tego połączenia nadrzędnego. MAS wymaga dostawcy OIDC obsługującego przepływ kodu autoryzacji. Format konfiguracji, wymagany identyfikator dostawcy i kroki migracji różnią się od wbudowanego w Synapse oidc_providers.

Typowe nieporozumienia i sposoby ich rozwiązania

• „Muszę tylko zmienić konfigurację Elementu”. Element kontroluje przepływ przeglądarki, a Synapse lub MAS obsługuje OIDC. Najpierw skonfiguruj odpowiedniego dostawcę po stronie serwera domowego.
• „Pomyślne logowanie do Keycloak dowodzi poprawności mapowania konta”. Uwierzytelnianie może się powieść, nawet jeśli wybrano nieprawidłową część lokalną lub deklarację profilu. Przetestuj z użytkownikiem spoza środowiska produkcyjnego i zweryfikuj otrzymany identyfikator Matrix.
• „SSO automatycznie wyłącza hasła i rejestrację”. Zasady te są kontrolowane przez serwer domowy i wdrożenie. Sprawdź osobno ustawienia logowania i rejestracji w Synapse i potwierdź zatwierdzoną zasadę.
• „Wylogowanie z Elementu powoduje wylogowanie ze wszystkich stron”. Sesje przeglądarki mogą pozostać aktywne w Keycloak. Skonfiguruj i przetestuj wylogowanie z kanału zwrotnego, jeśli wymagane jest scentralizowane zamykanie sesji.

Lista kontrolna weryfikacji

• Klient Keycloak wykorzystuje przepływ kodu autoryzacji, uwierzytelnianie klienta i dokładne wywołanie zwrotne dla Synapse lub MAS.
• Adres URL wystawcy jest zgodny z metadanymi wykrywania domeny, a tajny klucz klienta jest przechowywany po stronie serwera.
• Synapse lub MAS uruchamia się bez błędów konfiguracji OIDC i ujawnia zamierzoną metodę logowania.
• Użytkownik testowy może zalogować się z nowej sesji przeglądarki, przejść na oczekiwane konto Matrix i ukończyć normalną sesję Element.
• Zachowanie po wylogowaniu, istniejące konta, ograniczenia rejestracji i ewentualny zapasowy dostęp administratora są zgodne z Twoją polityką.

Oficjalne referencje

• Przewodnik po Synapse v1.144 OpenID Connect, obejmujący klienta Keycloak i ustawienia wywołania zwrotnego
• Konfiguracja Element Web: opcje przekierowania SSO
• Usługa uwierzytelniania Matrix: konfigurowanie dostawcy SSO w górnym biegu rzeki
• Podręcznik administratora serwera Keycloak 26.8.0