Element Web über Synapse OIDC mit Keycloak verbinden

Um die Keycloak-Anmeldung in Element Web zu integrieren, konfigurieren Sie Keycloak als OpenID Connect (OIDC)-Anbieter in Synapse und stellen Sie sicher, dass Element Web diesen Synapse-Homeserver verwendet. Synapse übernimmt die Authentifizierungsumleitung und den Callback; Element Web benötigt das Keycloak-Clientgeheimnis nicht.

Beispielszenario (hypothetisch): Eine kleine Organisation betreibt Element Web unter chat.example.org, Synapse unter matrix.example.orgund Keycloak unter login.example.org. Die gleiche Reihenfolge gilt für andere Hostnamen, jedoch muss jede URL Ihrer tatsächlichen öffentlichen Konfiguration entsprechen. Dieses Beispiel dient der Veranschaulichung und stellt keine Beschreibung einer Live-Umgebung dar.

Was Sie vor dem Ändern der Einstellungen benötigen

Verwenden Sie öffentliche HTTPS-URLs für Keycloak und Synapse. Die OIDC-Dokumentation von Synapse erfordert einen sicheren Ursprung für den Identitätsanbieter, und dessen Callback muss über die öffentliche Synapse-URL erreichbar sein. Überprüfen Sie den Realm-Namen in Keycloak, in der Synapse-Konfiguration public_baseurlund die Homeserver-URL, die Element Web bereitgestellt wird. Falls ein Reverse-Proxy vorgeschaltet ist, muss dieser Anfragen an das korrekte Backend weiterleiten und den externen HTTPS-Host und das HTTPS-Schema beibehalten.

Synapse verwendet aktuell eine oidc_providersListe. Die ältere Einzelanbieter- oidc_configVariante ist veraltet. Bewahren Sie während der Testphase einen funktionierenden Administrator-Login und eine Kopie der aktuellen Konfiguration auf. Deaktivieren Sie die Passwortanmeldung oder -registrierung erst, nachdem Sie den SSO-Ablauf überprüft und die Kontobereitstellung festgelegt haben.

1. Synapse als Client in Keycloak registrieren

Erstellen Sie im Keycloak-Bereich, in dem sich die Benutzer Ihrer Organisation befinden, einen OpenID Connect-Client für Synapse. Das offizielle Keycloak-Beispiel von Synapse verwendet einen vertraulichen Client mit der Client-ID synapse. Legen Sie die gültige Umleitungs-URI auf genau diesen Callback fest und ersetzen Sie dabei durch Ihren Synapse-Hostnamen.

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

Für die hypothetische Konfiguration legen Sie den Clientzugriffstyp auf „vertraulich“ fest und aktivieren Sie den Client. Kopieren Sie auf der Registerkarte „Anmeldeinformationen“ das generierte Clientgeheimnis in Ihr Geheimnisverwaltungssystem; speichern Sie es nicht öffentlich in Element Web config.jsonund veröffentlichen Sie es nicht in einem Repository.

Die Redirect-URI ist eine häufige Fehlerquelle. Sie muss die öffentliche Synapse-URL, den exakten /_synapse/client/oidc/callbackPfad sowie dasselbe Schema und denselben Hostnamen verwenden, die Synapse vom Browser empfängt. Vermeiden Sie einen allgemeinen Wildcard-Callback, wenn eine exakte URI ausreicht. Falls Sie später den Back-Channel-Logout aktivieren, fügen Sie den dokumentierten Back-Channel-Endpunkt von Synapse auch in Keycloak hinzu; dies ist optional und unabhängig von der grundlegenden Anmeldung.

2. Fügen Sie den Keycloak-Provider zu Synapse hinzu.

Bearbeiten Sie den aktiven Bereich homeserver.yaml. Ersetzen Sie Realm und Secret unten durch Ihre Werte und bestätigen Sie die Aussteller-URL aus dem OpenID-Discovery-Dokument des Bereichs. Der Standard-Keycloak-Realm-Aussteller hat folgende Struktur:

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

Bei einer Bereitstellung mit dem Standard-Discovery-Endpunkt und den in Synapses Keycloak-Beispiel gezeigten Ansprüchen lautet der Provider-Eintrag:

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

Der Aussteller muss mit dem Realm-Aussteller von Keycloak übereinstimmen, nicht nur mit dem Keycloak-Server-Root. Die Erkennung ermöglicht es Synapse, die Endpunkte für Autorisierung, Token und Benutzerinformationen von diesem Aussteller abzurufen. Die Zuordnung verwendet Keycloak, preferred_usernameum ein Matrix-Localpart und nameden Anzeigenamen zu bilden. Stellen Sie sicher, dass diese Ansprüche für Ihre Benutzer vorhanden und stabil sind. Ein Matrix-Localpart ist eine Konto-ID. Daher kann eine spätere Änderung der Zuordnung zu Verwirrung bei der Kontozuordnung führen oder eine andere Matrix-ID erzeugen.

Behalten Sie die bestehende oidc_providersListe bei, falls weitere Identitätsanbieter konfiguriert sind. Fügen Sie diesen Eintrag hinzu, anstatt nicht zugehörige Anbieter zu ersetzen. Schützen Sie das Clientgeheimnis und legen Sie die Dateiberechtigungen entsprechend Ihrer Bereitstellung fest. Überprüfen Sie die YAML-Einrückung und starten Sie Synapse anschließend mithilfe der für Ihre Installation vorgesehenen Dienst- oder Containerprozedur neu. Paketinstallationen enthalten möglicherweise bereits OIDC-Abhängigkeiten. Für eine Virtualenv-Installation dokumentiert Synapse die Installation matrix-synapse[oidc]. Befolgen Sie die Anweisungen Ihres Paketbetreuers für andere Installationsmethoden.

3. Point Element Web auf demselben Homeserver

Element Web config.jsonsollte den Synapse-Server als Homeserver identifizieren, beispielsweise über die URL des Homeservers default_server_config.mHomeserver.base_url. Verwenden Sie die tatsächliche Homeserver-URL, nicht die des Keycloak-Ausstellers. Element Web ist ein statischer Client: Nach einer Änderung der Homeserver-URL müssen Sie die Konfiguration über Ihre Hosting-Methode neu bereitstellen oder laden. Speichern Sie das Client-Geheimnis von Keycloak nicht in dieser Datei, da Browser es lesen können.

In diesem hypothetischen Beispiel wird Element Web unter [URL] gehostet https://chat.example.orgund verbindet sich mit [URL] https://matrix.example.org. Wählt ein Benutzer auf dem Anmeldebildschirm von Element die SSO-Option aus, durchläuft der Browser den Synapse-Anmeldevorgang, wechselt zum Keycloak-Bereich und kehrt anschließend zur Synapse-Callback-Funktion zurück. Die genaue Beschriftung der Schaltflächen und das Layout des Anmeldebildschirms können je nach Element Web-Version und Serverkonfiguration variieren. Testen Sie daher das tatsächliche Verhalten, anstatt sich auf eine bestimmte Bezeichnung zu verlassen.

4. Testen Sie SSO zunächst mit einem einzelnen Konto, bevor Sie es erzwingen.

Öffnen Sie Element Web in einem privaten Browserfenster und wählen Sie die SSO-Anmeldeoption. Melden Sie sich mit einem Testbenutzer von Keycloak an, bestätigen Sie den angeforderten Zugriff, falls Sie dazu aufgefordert werden, und prüfen Sie, ob der Browser zum gewünschten Homeserver zurückkehrt und das erwartete Matrix-Konto öffnet. Stellen Sie sicher, dass die resultierende Matrix-ID den korrekten Localpart enthält. Überprüfen Sie die Synapse- und Keycloak-Protokolle, falls der Browser einen Fehler zurückgibt.

Schlägt die Weiterleitung fehl, vergleichen Sie die Callback-URL in Keycloak Zeichen für Zeichen mit der öffentlichen Callback-URL von Synapse. Ein „Issuer-Mismatch“ deutet auf einen falschen Realm-Aussteller oder einen falschen Reverse-Proxy-Hostnamen hin. Ein fehlender Benutzername oder ein Mapping-Fehler bedeutet, dass der konfigurierte Claim fehlt oder ungeeignet ist. Überprüfen Sie die Claims des Testbenutzers und passen Sie das Mapping gegebenenfalls an. Erreicht der Browser Keycloak, kehrt aber nicht zurück, überprüfen Sie die TLS-Zertifikate und das Proxy-Routing für den Synapse-Callback.

Optionale Abmeldung: Synapse unterstützt die OIDC-Back-Channel-Abmeldung. Um diese Funktion zu nutzen, konfigurieren Sie sie backchannel_logout_enabled: trueunter diesem Provider und geben Sie die Back-Channel-Abmelde-URL von Keycloak an https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse beschreibt außerdem die Aktivierung der Option „Sitzung erforderlich“ in Keycloak. Diese Option verarbeitet vom Provider initiierte Abmeldebenachrichtigungen; sie ist jedoch für die initiale SSO-Anmeldung nicht erforderlich.

Vor der Einführung: Entscheiden Sie, ob SSO neue Matrix-Benutzer erstellen oder nur separat bereitgestellte Konten authentifizieren soll. Prüfen Sie anschließend die OIDC-Optionen von Synapse für Ihre installierte Version. Konfigurationsbezeichnungen und die Verwaltungsoberfläche von Keycloak können sich zwischen den Versionen ändern. Die hier beschriebenen Schritte orientieren sich an der OIDC-Dokumentation von Synapse (verfügbar ab dem 10. Oktober 2026) und setzen einen Standard-Keycloak-Realm sowie eine Synapse-Bereitstellung im dokumentierten Provider-Format voraus. Konsultieren Sie den Synapse OpenID Connect- und Keycloak-Leitfaden , die Synapse-Konfigurationsreferenz und die offizielle Keycloak-Dokumentation , bevor Sie versionsspezifische Einstellungen anwenden. Sobald sich das Testkonto erfolgreich anmeldet und ein Wiederherstellungspfad vorhanden ist, dokumentieren Sie die abschließende Callback-Funktion, den Aussteller und die Anspruchszuordnung für Administratoren.

Einen Kommentar hinterlassen

Element Web über Synapse OIDC mit Keycloak verbinden

Konfigurieren Sie einen Keycloak OIDC-Client und einen Synapse-Provider, damit sich Element Web-Benutzer über Ihren Identitätsserver anmelden können, ohne Client-Geheimnisse preiszugeben.

Element Key Backup und Cross-Signing sicher einrichten

Element Key Backup und Cross-Signing sicher einrichten

Speichern Sie einen Wiederherstellungsschlüssel, überprüfen Sie Ihre Element-Sitzungen und stellen Sie sicher, dass verschlüsselte Nachrichtenschlüssel wiederhergestellt werden können, ohne die Sicherung mit Ihrem Kontopasswort zu verwechseln.

Behebung von Matrix Synapse-Speicherabstürzen während der Client-Synchronisierung

Synapse-Speicherfehler während der Synchronisierung diagnostizieren, Caching sicher anpassen, Anfragerückstände identifizieren und eine stabile Speichernutzung überprüfen.

Behebung von Synapse Federation TLS-Zertifikatfehlern

Trace Matrix-Federationszertifikatfehler werden dem richtigen Server zugeordnet, die TLS-Kette oder die CA-Vertrauensstellung wird repariert und die Reparatur wird überprüft, ohne die Sicherheitsprüfungen zu deaktivieren.

Platzieren Sie einen Synapse Matrix-Server sicher hinter Cloudflare

Platzieren Sie einen Synapse Matrix-Server sicher hinter Cloudflare

Matrix-Clients und Föderation werden über Cloudflare auf HTTPS 443 geleitet, die Synapse-Erkennung bleibt erhalten und das Caching des API-Datenverkehrs sowie das Unterbrechen von Medien-Uploads werden vermieden.

Matrix Synapse sicher mit einem PostgreSQL-Dump wiederherstellen

Sichern Sie Synapse mit pg_dump, schützen Sie den Signaturschlüssel und die Speichermedien und stellen Sie die Daten in einer sauberen PostgreSQL-Datenbank wieder her, ohne veraltete Einmalschlüssel wiederzuverwenden.

Mjölnir als Matrix-Raummoderationsbot mit Docker ausführen

Mjölnir als Matrix-Raummoderationsbot mit Docker ausführen

Richten Sie Mjölnir mit einem dedizierten Matrix-Konto, einem verschlüsselten Verwaltungsraum, Docker Compose, einer Richtlinienliste und Berechtigungsprüfungen ein.

Aktivieren Sie die native Matrix-Gleitsynchronisierung für schnelleres Laden auf Mobilgeräten.

Aktivieren Sie die native Matrix-Gleitsynchronisierung für schnelleres Laden auf Mobilgeräten.

Überspringen Sie den veralteten Proxy und konfigurieren Sie die in Synapse integrierte Sliding-Sync-Funktion. Überprüfen Sie die Client-Erkennung und messen Sie anschließend das Ladeverhalten der Raumliste sowie das Verhalten bei der Wiederverbindung auf einem kompatiblen Telefon.

Host Element Web auf Nginx mit einem benutzerdefinierten Homeserver

Stellen Sie Element Web als statische Website bereit, verweisen Sie es auf Ihren Matrix-Homeserver, fügen Sie HTTPS hinzu und konfigurieren Sie Nginx so, dass Aktualisierungen ohne veraltete Dateien bereitgestellt werden.

Betreiben Sie einen ressourcenschonenden Matrix-Homeserver auf einem Raspberry Pi 4

Conduit auf einem 64-Bit Raspberry Pi 4 mit persistenten Daten, HTTPS-Federation, geschützter Registrierung und Überprüfungen auf einen funktionierenden Homeserver einrichten.