So konfigurieren Sie Single Sign-On (SSO) mit Keycloak in Element Web

Element Web authentifiziert sich nicht direkt bei Keycloak. Element fragt seinen Matrix-Homeserver nach unterstützten Anmeldemethoden; der Homeserver führt eine OpenID Connect-Authentifizierung (OIDC) mit Keycloak durch und leitet den Benutzer an Element weiter. Bei einer Synapse-Bereitstellung mit integrierter OIDC-Unterstützung konfigurieren Sie einen vertraulichen OIDC-Client in Keycloak, fügen diesen Provider zu Synapse hinzu und passen optional die Einstellungen von Element Web an, config.jsonum SSO anzuzeigen oder automatisch zu starten.

Diese Anleitung verwendet den in Synapse integrierten OIDC-Provider, der ein gängiger Bereitstellungsweg ist. Falls Ihr Homeserver die Authentifizierung an den Matrix Authentication Service (MAS) delegiert, verwenden Sie stattdessen die unten beschriebene MAS-Callback- und Provider-Konfiguration. Die beiden Callback-URLs unterscheiden sich. Die Anweisungen wurden am 6. Oktober 2026 anhand der Element-Web-Konfigurationsdokumentation, der Synapse-OIDC-Anleitung (Version 1.144), der aktuellen MAS-SSO-Anleitung und des Keycloak-Administrationshandbuchs (Version 26.8.0) geprüft. Bereitstellungspakete und UI-Bezeichnungen können je nach Version variieren.

Ermitteln Sie zunächst, welchen Authentifizierungspfad Sie verwenden.

Prüfen Sie Ihre Synapse-Konfigurations- und Bereitstellungsdokumentation, bevor Sie einen Client erstellen. Der Callback muss zu der Komponente gehören, die mit Keycloak kommuniziert; registrieren Sie nicht die Website-URL von Element als Callback.

Was Sie benötigen

• Eine öffentliche HTTPS-URL für Synapse, wie z. B. https://matrix.example.com, und ein erreichbarer Keycloak-Realm-Aussteller, wie z. B. https://sso.example.com/realms/company.
• Administrativer Zugriff auf den Keycloak-Bereich sowie die Synapse-Konfiguration und den Synapse-Dienst.
• Eine Sicherung der aktuellen Konfiguration und eine Möglichkeit, Synapse-Protokolle oder eine Serverkonsole zu verwenden, falls die Anmeldung fehlschlägt.
• Eine Entscheidung über die Kontobereitstellung: Welche Keycloak-Benutzer dürfen sich anmelden, welcher Anspruch identifiziert sie und ob bestehende Matrix-Konten beibehalten werden müssen.

Keycloak für Synapse OIDC konfigurieren

1. Erstellen Sie einen vertraulichen OIDC-Client.

Erstellen Sie im Bereich für Matrix-Konten einen Client für Synapse mithilfe des OpenID Connect-Protokolls. Aktivieren Sie die Autorisierungscode- oder Standard-Flow- und Client-Authentifizierung, damit Synapse am Token-Endpunkt ein Client-Geheimnis verwenden kann. Legen Sie die Client-ID auf einen Wert fest, den Sie auch in Synapse verwenden, z. B. „10 synapse...

Legen Sie die gültige Umleitungs-URI auf den exakten Synapse-Callback fest:

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

Ersetzen Sie den Beispiel-Hostnamen durch die tatsächlich für Synapse konfigurierte öffentliche Basis-URL. Verwenden Sie keinen allgemeinen Platzhalter wie *in der Produktionsumgebung. Keycloak validiert Umleitungs-URIs. Eine Abweichung von Hostname, Schema, Pfad oder abschließendem Schrägstrich kann daher zu einem Fehler „Umleitungs-URI nicht zulässig“ führen.

Speichern Sie den Client, kopieren Sie das generierte Geheimnis und speichern Sie es als serverseitiges Geheimnis. Halten Sie es von den öffentlichen Bereichen von Element Web config.json, der Quellcodeverwaltung, Screenshots und clientseitigem JavaScript fern. Die Keycloak-Administrationskonsole kann die Client-Authentifizierung oder Anmeldeinformationen in verschiedenen Versionen unterschiedlich bezeichnen; stellen Sie sicher, dass der resultierende Client vertraulich ist und den Standard-Autorisierungscode-Ablauf verwenden kann.

2. Emittent und Ansprüche bestätigen.

Der Aussteller identifiziert den Realm, nicht den Keycloak-Server-Root. Verwenden Sie in diesem Beispiel https://sso.example.com/realms/company. Stellen Sie sicher, dass die OpenID-Konfiguration des Realms unter erreichbar ist <issuer>/.well-known/openid-configurationund dass der angegebene Aussteller exakt mit dem Wert übereinstimmt, den Sie in Synapse angeben.

Synapse benötigt einen stabilen Identitätsanspruch, um das Keycloak-Konto einem Matrix-Benutzer zuzuordnen. Der OIDC-Anbieter identifiziert das externe Subjekt üblicherweise mithilfe des OIDC-Subjektanspruchs; die untenstehende Benutzernamenzuordnung verwendet diesen preferred_usernameals Matrix-Localpart. Stellen Sie sicher, dass Keycloak diesen Anspruch tatsächlich zurückgibt und dass Benutzernamen gemäß Ihrer Kontorichtlinie eindeutig und stabil sind. Wenn Ihre Organisation Änderungen an Benutzernamen zulässt, wählen und testen Sie vor der Produktivsetzung eine Zuordnungsstrategie; eine unerwartete Zuordnungsänderung kann Einfluss darauf haben, welches Matrix-Konto eine Person erreicht.

Synapse konfigurieren

3. Fügen Sie den OIDC-Anbieter hinzu.

Fügen Sie einen Provider-Eintrag zur Hauptkonfiguration von Synapse hinzu (üblicherweise `/provider/`) homeserver.yaml. Führen Sie ihn mit der bestehenden YAML-Datei zusammen, anstatt andere Einstellungen zu ersetzen. Ersetzen Sie `<realm issuer>` und `<client secret>` durch Ihren Realm Issuer.

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

Die angeforderten Bereiche steuern, welche Benutzerinformationen Keycloak zurückgeben darf; sie garantieren jedoch nicht, dass alle Ansprüche erfüllt werden. Wenn Sie keine E-Mail-Adresse oder keinen Anzeigenamen importieren müssen, reduzieren Sie die Bereiche und die Zuordnung entsprechend. Stellen Sie sicher, dass die Konfigurationsdatei nur für den Dienstadministrator und den Synapse-Prozess lesbar ist, wie es Ihre Bereitstellung erfordert. Wenn Sie Synapse über Container oder ein Chart verwalten, speichern Sie die Provider-Einstellungen in der unterstützten Konfigurationsquelle, anstatt eine generierte Datei zu bearbeiten, die überschrieben wird.

4. Optional: Back-Channel-Logout konfigurieren

Standardmäßig beendet das Abmelden von einem Dienst nicht zwangsläufig die Browsersitzung aller anderen Dienste. Wenn Sie möchten, dass Keycloak-Abmeldebenachrichtigungen die Synapse-Sitzung beenden, aktivieren Sie die entsprechende Option backchannel_logout_enabled: trueunter dem Keycloak-Anbieter in Synapse und legen Sie die Backchannel-Abmelde-URL von Keycloak wie folgt fest:

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

Dies ist optional und hängt von Ihrer Abmelderichtlinie und Clientkonfiguration ab. Testen Sie beide Abmelderichtungen: Synapse-Abmeldung und Keycloak-Abmeldung. Gehen Sie nicht davon aus, dass die Abmeldung von Element allein die Keycloak-Sitzung beendet.

5. Synapse neu starten und testen

Validieren Sie die YAML-Datei anhand der Konfigurationsprüfungen Ihrer Bereitstellung und starten Sie Synapse anschließend neu oder laden Sie es neu, indem Sie die von Ihrem Paket oder Container-Setup unterstützte Methode verwenden. Überprüfen Sie die Synapse-Protokolle auf Fehler bei der OIDC-Erkennung, der Client-Authentifizierung, dem Rückruf oder der Anspruchszuordnung. Verwenden Sie zunächst ein Testkonto und vergewissern Sie sich, dass dessen Matrix-ID und Anzeigename den erwarteten Werten entsprechen.

Element Web konfigurieren

6. SSO optional halten oder automatische Weiterleitung anbieten.

Sobald Synapse die OIDC-Anmeldung ankündigt, kann Element Web seine SSO-Anmeldeoption anbieten. sso_redirect_optionsDie Einstellungen von Element steuern das Browserverhalten; sie konfigurieren weder Keycloak noch speichern sie das Client-Geheimnis. Fügen Sie eine ähnliche Einstellung zu den von Element Web bereitgestellten Dateien hinzu, config.jsonwenn nicht authentifizierte Besucher, die auf die Willkommens- oder Anmeldeseite gelangen, zum verfügbaren SSO-Ablauf weitergeleitet werden sollen:

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

Für eine Bereitstellung, die ausschließlich SSO-Anmeldung erfordert, "immediate": trueaktivieren Sie SSO für alle nicht authentifizierten Benutzer. Dadurch kann der Zugriff auf Passwörter oder andere Anmeldeoptionen erschwert werden. Testen Sie daher die Wiederherstellung und den Administratorzugriff, bevor Sie diese Funktion erzwingen. Wenn Benutzer zwischen SSO und einer anderen Methode wählen sollen, deaktivieren Sie die automatische Weiterleitung und testen Sie, ob die SSO-Option im Anmeldevorgang angezeigt wird.

Wenn Synapse den Matrix-Authentifizierungsdienst verwendet

MAS ist ein separater Authentifizierungsdienst und kann als OIDC-Client für Keycloak fungieren. Konfigurieren Sie in dieser Architektur die Keycloak-Umleitungs-URI wie folgt : `<Provider-ID> https://auth.example.com/upstream/callback/<provider-id>`, wobei die Provider-ID mit der MAS-Konfiguration übereinstimmt. Konfigurieren Sie den Provider unter `<Provider-ID>` von MAS upstream_oauth2.providers. Element verwendet dann den MAS-basierten Authentifizierungsablauf des Homeservers. Verwenden Sie /_synapse/client/oidc/callbackfür diese Upstream-Verbindung nicht die Synapse-eigene Authentifizierungsmethode. MAS benötigt einen OIDC-Provider, der den Autorisierungscode-Ablauf unterstützt. Das Konfigurationsformat, die erforderliche Provider-ID und die Migrationsschritte unterscheiden sich von der in Synapse integrierten Methode oidc_providers.

Häufige Missverständnisse und ihre Lösungen

• „Ich muss nur die Konfiguration von Element ändern.“ Element steuert den Browserablauf, während Synapse oder MAS die OIDC-Kommunikation übernehmen. Konfigurieren Sie zuerst den korrekten Provider auf dem Homeserver.
• „Eine erfolgreiche Keycloak-Anmeldung beweist, dass die Kontozuordnung korrekt ist.“ Die Authentifizierung kann jedoch auch dann erfolgreich sein, wenn der falsche Localpart oder Profilanspruch ausgewählt ist. Testen Sie dies mit einem Nicht-Produktionsbenutzer und überprüfen Sie die resultierende Matrix-ID.
• „SSO deaktiviert automatisch Passwörter und Registrierung.“ Diese Richtlinien werden vom Homeserver und der Bereitstellung gesteuert. Überprüfen Sie die Anmelde- und Registrierungseinstellungen von Synapse separat und bestätigen Sie die genehmigte Richtlinie.
• „Wenn ich mich bei Element abmelde, werde ich überall abgemeldet.“ Browsersitzungen können bei Keycloak aktiv bleiben. Konfigurieren und testen Sie die Abmeldung über den Backchannel, falls eine zentrale Sitzungsbeendigung erforderlich ist.

Prüfliste

• Der Keycloak-Client verwendet den Autorisierungscode-Flow, die Client-Authentifizierung und den exakten Callback für Synapse oder MAS.
• Die Aussteller-URL stimmt mit den Discovery-Metadaten des Realms überein, und das Client-Geheimnis wird serverseitig gespeichert.
• Synapse oder MAS startet ohne OIDC-Konfigurationsfehler und stellt die vorgesehene Anmeldemethode bereit.
• Ein Testbenutzer kann sich von einer neuen Browsersitzung aus anmelden, landet im erwarteten Matrix-Konto und kann eine normale Element-Sitzung abschließen.
• Das Abmeldeverhalten, bestehende Konten, Registrierungsbeschränkungen und alle alternativen Administratorzugriffsrechte entsprechen Ihrer Richtlinie.

Offizielle Referenzen

• Synapse v1.144 OpenID Connect-Anleitung, einschließlich Keycloak-Client- und Callback-Einstellungen
• Element Web-Konfiguration: SSO-Umleitungsoptionen
• Matrix Authentication Service: Konfigurieren eines Upstream-SSO-Anbieters
• Keycloak 26.8.0 Server-Administrationshandbuch