Połącz Element Web z Keycloak przez Synapse OIDC

Aby dodać logowanie Keycloak do Element Web, skonfiguruj Keycloak jako dostawcę OpenID Connect (OIDC) w Synapse, a następnie upewnij się, że Element Web korzysta z tego serwera domowego Synapse. Synapse obsługuje przekierowanie uwierzytelniania i wywołanie zwrotne; Element Web nie potrzebuje tajnego klucza klienta Keycloak.

Przykładowy scenariusz (hipotetyczny): mała organizacja korzysta z Element Web pod adresem chat.example.org, Synapse pod adresem matrix.example.orgi Keycloak pod adresem login.example.org. Ta sama sekwencja dotyczy innych nazw hostów, ale każdy adres URL musi być zgodny z rzeczywistą konfiguracją publiczną. Ten przykład ma charakter ilustracyjny, a nie jest raportem z konfiguracji na żywo.

Czego potrzebujesz przed zmianą ustawień

Użyj publicznych adresów URL HTTPS dla Keycloak i Synapse. Dokumentacja OIDC usługi Synapse wymaga bezpiecznego źródła dla dostawcy tożsamości, a jego wywołanie zwrotne musi być dostępne poprzez publiczny adres URL usługi Synapse. Potwierdź nazwę domeny w Keycloak, adresie usługi Synapse public_baseurloraz adres URL serwera domowego dostarczony do Element Web. Jeśli przed którąkolwiek z usług znajduje się odwrotny serwer proxy, musi on przekazywać żądania do odpowiedniego zaplecza i zachować zewnętrzny host i schemat HTTPS.

Obecna konfiguracja Synapse korzysta z oidc_providerslisty. Starszy oidc_configformularz pojedynczego dostawcy jest przestarzały. Zachowaj działający login administratora i kopię bieżącej konfiguracji podczas testów. Nie wyłączaj logowania ani rejestracji hasłem, dopóki nie zweryfikujesz przepływu logowania jednokrotnego (SSO) i nie zdecydujesz, w jaki sposób będą tworzone konta.

1. Zarejestruj Synapse jako klienta w Keycloak

W domenie Keycloak, w której znajdują się użytkownicy Twojej organizacji, utwórz klienta OpenID Connect dla Synapse. Oficjalny przykład Keycloak dla Synapse używa poufnego klienta o identyfikatorze klienta synapse. Ustaw prawidłowy URI przekierowania na dokładnie to wywołanie zwrotne, zastępując nazwę hosta Synapse:

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

W przypadku konfiguracji hipotetycznej ustaw typ dostępu klienta na poufny i włącz klienta. Na karcie „Dane uwierzytelniające” skopiuj wygenerowany klucz tajny klienta do systemu zarządzania kluczami tajnymi; nie umieszczaj go w katalogu publicznym Element Web config.jsonani nie publikuj w repozytorium.

Adres URI przekierowania jest częstym źródłem błędów. Musi on używać publicznego adresu URL Synapse, dokładnej /_synapse/client/oidc/callbackścieżki oraz tego samego schematu i nazwy hosta, które Synapse widzi w przeglądarce. Unikaj szerokiego wywołania zwrotnego z symbolem wieloznacznym, gdy dokładny adres URI będzie działał. Jeśli później włączysz wylogowywanie z kanału zwrotnego, dodaj udokumentowany punkt końcowy kanału zwrotnego Synapse również w Keycloak; jest to opcjonalne i niezależne od podstawowego logowania.

2. Dodaj dostawcę Keycloak do Synapse

Edytuj aktywny homeserver.yaml. Zastąp poniższe domeny i sekret swoimi wartościami i potwierdź adres URL wystawcy z dokumentu OpenID Discovery domeny. Standardowy wystawca domeny Keycloak ma następującą postać:

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

W przypadku wdrożenia wykorzystującego standardowy punkt końcowy wykrywania i oświadczenia pokazane w przykładzie Keycloak firmy Synapse wpis dostawcy wygląda następująco:

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

Wydawca musi być zgodny z wystawcą domeny Keycloak, a nie tylko z głównym serwerem Keycloak. Discovery pozwala Synapse uzyskać punkty końcowe autoryzacji, tokenu i informacji o użytkowniku od tego wystawcy. Mapowanie wykorzystuje Keycloak preferred_usernamedo utworzenia lokalnej części Matrix i namejako nazwę wyświetlaną; upewnij się, że te żądania są obecne i stabilne dla użytkowników. Lokalna część Matrix to identyfikator konta, więc późniejsza zmiana mapowania może utrudnić dopasowanie konta lub spowodować inny identyfikator Matrix.

Zachowaj istniejącą oidc_providerslistę, jeśli skonfigurowano innych dostawców tożsamości; dodaj ten wpis zamiast zastępować niezwiązanych dostawców. Chroń sekret klienta jako sekret i ustaw uprawnienia do plików zgodnie z wdrożeniem. Sprawdź poprawność wcięcia YAML, a następnie uruchom ponownie Synapse, używając procedury usługi lub kontenera dla swojej instalacji. Instalacje pakietowe mogą już zawierać zależności OIDC; w przypadku instalacji w środowisku wirtualnym dokumentacja Synapse opisuje instalację matrix-synapse[oidc]. Postępuj zgodnie ze wskazówkami opiekuna pakietu dotyczącymi innych metod instalacji.

3. Punkt Element Web na tym samym serwerze domowym

Element Web config.jsonpowinien identyfikować serwer Synapse jako swój serwer domowy, na przykład poprzez default_server_config.mHomeserver.base_url. Użyj rzeczywistego adresu URL serwera domowego, a nie wystawcy Keycloak. Element Web to klient statyczny: po zmianie adresu URL serwera domowego należy ponownie wdrożyć lub przeładować jego konfigurację za pomocą metody hostingu. Nie umieszczaj tajnego klucza klienta Keycloak w tym pliku, ponieważ przeglądarki mogą go odczytać.

W hipotetycznym przykładzie Element Web jest hostowany https://chat.example.orgi łączy się z https://matrix.example.org. Gdy użytkownik wybierze opcję SSO na ekranie logowania Element, przeglądarka powinna przejść przez proces logowania Synapse do domeny Keycloak i powrócić do wywołania zwrotnego Synapse. Dokładne brzmienie przycisków i układ ekranu logowania mogą się różnić w zależności od wersji Element Web i konfiguracji serwera; należy przetestować działanie, zamiast polegać na konkretnej etykiecie.

4. Przetestuj na jednym koncie przed wymuszeniem logowania jednokrotnego

Otwórz Element Web w prywatnym oknie przeglądarki i wybierz opcję logowania jednokrotnego (SSO). Zaloguj się jako testowy użytkownik Keycloak, zatwierdź żądany dostęp, jeśli zostaniesz o to poproszony, i potwierdź, że przeglądarka powraca do właściwego serwera domowego i otwiera oczekiwane konto Matrix. Sprawdź, czy wynikowy identyfikator Matrix zawiera właściwy element lokalny (localpart). Sprawdź logi Synapse i Keycloak, jeśli przeglądarka zwróci błąd.

Jeśli przekierowanie się nie powiedzie, porównaj adres URL wywołania zwrotnego w Keycloak znak po znaku z publicznym adresem URL wywołania zwrotnego Synapse. „Niezgodność wystawcy” wskazuje na nieprawidłowego wystawcę domeny lub nazwę hosta odwrotnego serwera proxy. Brak nazwy użytkownika lub błąd mapowania oznacza, że ​​skonfigurowane oświadczenie jest nieobecne lub nieodpowiednie; sprawdź oświadczenia użytkownika testowego i celowo dostosuj mapowanie. Jeśli przeglądarka połączy się z Keycloak, ale nie zwróci połączenia, sprawdź certyfikaty TLS i routing proxy dla wywołania zwrotnego Synapse.

Opcjonalne wylogowanie: Synapse obsługuje wylogowanie z kanału zwrotnego OIDC. Aby z niego skorzystać, należy ustawić go backchannel_logout_enabled: truew tym dostawcy i skonfigurować adres URL wylogowania z kanału zwrotnego Keycloak jako https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse dokumentuje również włączenie opcji wymaganej sesji w Keycloak. Obsługuje ona powiadomienia o wylogowaniu inicjowane przez dostawcę; nie jest wymagana do uruchomienia początkowego logowania jednokrotnego (SSO).

Przed wdrożeniem: zdecyduj, czy logowanie jednokrotne (SSO) powinno tworzyć nowych użytkowników Matrix, czy tylko uwierzytelniać konta, które aprowizujesz osobno, a następnie zapoznaj się z opcjami OIDC w Synapse dla zainstalowanej wersji. Etykiety konfiguracji i interfejs administracyjny Keycloak mogą się różnić w zależności od wersji. Poniższe kroki są zgodne z dokumentacją OIDC w Synapse, dostępną od 10 października 2026 r., i zakładają standardową domenę Keycloak oraz wdrożenie Synapse z wykorzystaniem udokumentowanego formatu dostawcy. Przed zastosowaniem ustawień specyficznych dla danej wersji zapoznaj się z podręcznikiem Synapse OpenID Connect i Keycloak , dokumentacją konfiguracji Synapse oraz oficjalną dokumentacją Keycloak . Po poprawnym zalogowaniu konta testowego i utworzeniu ścieżki odzyskiwania, udokumentuj ostateczne mapowanie wywołania zwrotnego, wystawcy i roszczeń dla administratorów.

Zostaw komentarz

Rozwiąż błędy uprawnień administratora pokoju Matrix za pomocą działania

Prześledź M_FORBIDDEN do poziomów mocy pokoju, członkostwa lub dostępu administratora serwera Synapse, a następnie przywróć tylko uprawnienia potrzebne do zablokowanej akcji.

Uczyń swój serwer Matrix Synapse dostępnym dla federacji

Uczyń swój serwer Matrix Synapse dostępnym dla federacji

Skonfiguruj wykrywanie Synapse, protokół HTTPS i routing proxy, aby inne serwery domowe Matrix mogły znaleźć Twój serwer i nawiązać z nim kontakt.

Połącz Element Web z Keycloak przez Synapse OIDC

Skonfiguruj klienta Keycloak OIDC i dostawcę Synapse, aby użytkownicy Element Web mogli logować się za pośrednictwem serwera tożsamości bez ujawniania tajnych danych klienta.

Bezpieczna konfiguracja kopii zapasowej klucza elementu i podpisywania krzyżowego

Bezpieczna konfiguracja kopii zapasowej klucza elementu i podpisywania krzyżowego

Zapisz klucz odzyskiwania, zweryfikuj sesje Element i sprawdź, czy zaszyfrowane klucze wiadomości można odzyskać, nie myląc kopii zapasowej z hasłem do konta.

Zatrzymaj awarię pamięci Matrix Synapse podczas synchronizacji klienta

Diagnozuj błędy braku pamięci w Synapse podczas synchronizacji, bezpiecznie dostosowuj buforowanie, identyfikuj zaległości w żądaniach i weryfikuj stabilne wykorzystanie pamięci.

Rozwiązywanie błędów certyfikatu TLS federacji Synapse

Śledź błędy certyfikatu federacji Matrix na właściwym serwerze, napraw łańcuch TLS lub zaufanie urzędu certyfikacji i zweryfikuj poprawkę bez wyłączania kontroli bezpieczeństwa.

Bezpiecznie umieść serwer Synapse Matrix za Cloudflare

Bezpiecznie umieść serwer Synapse Matrix za Cloudflare

Klienci i federacja Matrix korzystają z usługi Cloudflare na protokole HTTPS 443, zachowując wykrywanie Synapse i unikając buforowania ruchu API lub przerywania przesyłania multimediów.

Bezpieczne przywracanie Matrix Synapse za pomocą zrzutu PostgreSQL

Utwórz kopię zapasową Synapse za pomocą pg_dump, chroń jej klucz podpisu i nośnik, a następnie przywróć do czystej bazy danych PostgreSQL bez ponownego używania nieaktualnych kluczy jednorazowych.

Uruchom Mjölnir jako bota moderującego pokój Matrix za pomocą Dockera

Uruchom Mjölnir jako bota moderującego pokój Matrix za pomocą Dockera

Skonfiguruj Mjölnir przy użyciu dedykowanego konta Matrix, szyfrowanego pokoju zarządzania, Docker Compose, listy zasad i kontroli uprawnień.

Włącz natywną synchronizację Matrix Sliding, aby przyspieszyć ładowanie urządzeń mobilnych

Włącz natywną synchronizację Matrix Sliding, aby przyspieszyć ładowanie urządzeń mobilnych

Pomiń wycofany serwer proxy i skonfiguruj wbudowaną funkcję Sliding Sync w Synapse. Sprawdź wykrywanie klientów, a następnie zmierz ładowanie listy pokoi i zachowanie ponownego łączenia na kompatybilnym telefonie.