Verbind Element Web met Keycloak via Synapse OIDC.

Om Keycloak-aanmelding aan Element Web toe te voegen, configureert u Keycloak als een OpenID Connect (OIDC)-provider in Synapse en zorgt u ervoor dat Element Web die Synapse-homeserver gebruikt. Synapse verzorgt de authenticatie-redirect en de callback; Element Web heeft het Keycloak-clientgeheim niet nodig.

Voorbeeldscenario (hypothetisch): een kleine organisatie gebruikt Element Web op chat.example.org, Synapse op matrix.example.orgen Keycloak op login.example.org. Dezelfde volgorde geldt voor andere hostnamen, maar elke URL moet overeenkomen met uw daadwerkelijke publieke configuratie. Dit voorbeeld is ter illustratie en geen verslag van een live-installatie.

Wat je nodig hebt voordat je de instellingen wijzigt

Gebruik openbare HTTPS-URL's voor Keycloak en Synapse. De OIDC-documentatie van Synapse vereist een beveiligde oorsprong voor de identiteitsprovider, en de callback moet bereikbaar zijn via de openbare Synapse-URL. Controleer de realmnaam in Keycloak, die van Synapse public_baseurlen de homeserver-URL die aan Element Web wordt aangeboden. Als er een reverse proxy voor een van beide services staat, moet deze verzoeken doorsturen naar de juiste backend en de externe HTTPS-host en het schema behouden.

De huidige configuratie van Synapse maakt gebruik van een oidc_providerslijst. De oudere configuratie met één provider oidc_configis verouderd. Zorg ervoor dat u tijdens het testen een werkende beheerdersaccount en een kopie van de huidige configuratie bij de hand hebt. Schakel inloggen met een wachtwoord of registratie niet uit voordat u de SSO-procedure hebt geverifieerd en hebt bepaald hoe accounts worden aangemaakt.

1. Registreer Synapse als client in Keycloak.

Maak in het Keycloak-domein waar de gebruikers van uw organisatie zich bevinden een OpenID Connect-client voor Synapse aan. Het officiële Keycloak-voorbeeld van Synapse gebruikt een vertrouwelijke client met client-ID synapse. Stel de geldige redirect-URI in op deze exacte callback, waarbij u uw Synapse-hostnaam vervangt:

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

Voor de hypothetische configuratie stelt u het toegangstype van de client in op vertrouwelijk en schakelt u de client in. Kopieer op het tabblad 'Referenties' het gegenereerde clientgeheim naar uw systeem voor geheimbeheer; plaats het niet in de openbare repository van Element Web config.jsonen publiceer het ook niet in een repository.

De redirect-URI is een veelvoorkomende oorzaak van problemen. Deze moet de openbare Synapse-URL, het exacte /_synapse/client/oidc/callbackpad en hetzelfde schema en dezelfde hostnaam gebruiken als Synapse vanuit de browser ziet. Vermijd een brede wildcard-callback wanneer een exacte URI volstaat. Als u later back-channel logout inschakelt, voeg dan ook het gedocumenteerde back-channel-eindpunt van Synapse toe in Keycloak; dit is optioneel en staat los van de standaard aanmelding.

2. Voeg de Keycloak-provider toe aan Synapse.

Bewerk de actieve homeserver.yaml. Vervang de realm en secret hieronder door uw waarden en bevestig de issuer-URL in het OpenID discovery-document van de realm. De standaard Keycloak realm issuer heeft deze structuur:

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

Voor een implementatie met het standaard discovery-eindpunt en de claims zoals weergegeven in het Keycloak-voorbeeld van Synapse, is de providervermelding als volgt:

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

De uitgever moet overeenkomen met de realm-uitgever van Keycloak, niet alleen met de root van de Keycloak-server. Discovery stelt Synapse in staat om de autorisatie-, token- en gebruikersinformatie-endpoints van die uitgever te verkrijgen. De mapping gebruikt Keycloak preferred_usernameom een ​​Matrix localpart te vormen en nameals weergavenaam; zorg ervoor dat deze claims aanwezig en stabiel zijn voor uw gebruikers. Een Matrix localpart is een account-ID, dus het later wijzigen van de mapping kan leiden tot verwarrende accountmatching of een andere Matrix-ID opleveren.

Behoud de bestaande oidc_providerslijst als er andere identiteitsproviders zijn geconfigureerd; voeg deze vermelding toe in plaats van irrelevante providers te vervangen. Bescherm het clientgeheim als een geheim en stel de bestandsrechten in volgens uw implementatie. Valideer de inspringing van het YAML-bestand en herstart Synapse vervolgens met behulp van de service- of containerprocedure voor uw installatie. Pakketinstallaties bevatten mogelijk al OIDC-afhankelijkheden; voor een virtualenv-installatie beschrijft Synapse de installatieprocedure matrix-synapse[oidc]. Volg de instructies van uw pakketbeheerder voor andere installatiemethoden.

3. Point Element Web op dezelfde thuisserver

Element Web config.jsonmoet de Synapse-server als homeserver identificeren, bijvoorbeeld via default_server_config.mHomeserver.base_url. Gebruik de daadwerkelijke homeserver-URL, niet de Keycloak-uitgever. Element Web is een statische client: herimplementeer of herlaad de configuratie met uw hostingmethode nadat u de homeserver-URL hebt gewijzigd. Plaats het clientgeheim van Keycloak niet in dit bestand, omdat browsers dit kunnen lezen.

In het hypothetische voorbeeld wordt Element Web gehost op https://chat.example.orgen maakt verbinding met https://matrix.example.org. Wanneer een gebruiker de SSO-optie selecteert op het inlogscherm van Element, moet de browser de inlogprocedure van Synapse doorlopen naar de Keycloak-realm en terugkeren naar de callback van Synapse. De exacte tekst op de knop en de lay-out van het inlogscherm kunnen variëren afhankelijk van de Element Web-release en de serverconfiguratie; test het gedrag in plaats van te vertrouwen op een specifiek label.

4. Test met één account voordat u SSO afdwingt.

Open Element Web in een privévenster van uw browser en selecteer de SSO-aanmeldingsoptie. Meld u aan met een testgebruiker van Keycloak, keur de gevraagde toegang goed indien gevraagd en controleer of de browser terugkeert naar de beoogde homeserver en het verwachte Matrix-account opent. Controleer of de resulterende Matrix-ID het juiste lokale gedeelte heeft. Raadpleeg de Synapse- en Keycloak-logboeken als de browser een foutmelding geeft.

Als de redirect mislukt, vergelijk dan de callback-URL in Keycloak teken voor teken met de openbare callback-URL van Synapse. Een "issuer mismatch" wijst op een onjuiste realm-issuer of reverse-proxy hostnaam. Een ontbrekende gebruikersnaam of een mappingfout betekent dat de geconfigureerde claim ontbreekt of ongeschikt is; controleer de claims van de testgebruiker en pas de mapping zorgvuldig aan. Als de browser Keycloak bereikt maar niet terugkeert, controleer dan de TLS-certificaten en proxy-routing voor de Synapse-callback.

Optionele uitlogfunctie: Synapse ondersteunt OIDC-uitloggen via het backchannel. Om dit te gebruiken, stelt u dit backchannel_logout_enabled: truein onder deze provider en configureert u de backchannel-uitlog-URL van Keycloak als https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse beschrijft ook hoe u de optie 'sessie vereist' in Keycloak kunt inschakelen. Dit handelt door de provider geïnitieerde uitlogmeldingen af; het is niet vereist om de initiële SSO-aanmelding te laten werken.

Vóór de uitrol: bepaal of SSO nieuwe Matrix-gebruikers moet aanmaken of alleen accounts moet authenticeren die u afzonderlijk configureert, en bekijk vervolgens de OIDC-opties van Synapse voor uw geïnstalleerde versie. Configuratielabels en de beheerdersinterface van Keycloak kunnen per release verschillen. De stappen hier volgen de OIDC-documentatie van Synapse die beschikbaar is sinds 10 oktober 2026, en gaan uit van een standaard Keycloak-realm en een Synapse-implementatie met behulp van het gedocumenteerde providerformaat. Raadpleeg de Synapse OpenID Connect- en Keycloak-handleiding , de Synapse-configuratiereferentie en de officiële Keycloak-documentatie voordat u versiespecifieke instellingen toepast. Zodra het testaccount correct is ingelogd en u een herstelroute hebt, documenteert u de uiteindelijke callback-, issuer- en claimtoewijzing voor beheerders.

Laat een reactie achter

Matrix Room-beheerdersrechtenfouten oplossen via actie

Traceer M_FORBIDDEN naar het stroomniveau van de ruimte, het lidmaatschap of de Synapse-serverbeheerderstoegang en herstel vervolgens alleen de machtiging die de geblokkeerde actie nodig heeft.

Zorg dat uw Matrix Synapse-server bereikbaar is voor federatie.

Zorg dat uw Matrix Synapse-server bereikbaar is voor federatie.

Configureer Synapse discovery, HTTPS en proxy routing zodat andere Matrix homeservers uw server kunnen vinden en ermee in contact kunnen komen.

Verbind Element Web met Keycloak via Synapse OIDC.

Configureer een Keycloak OIDC-client en een Synapse-provider zodat Element Web-gebruikers zich kunnen aanmelden via uw identiteitsserver zonder clientgeheimen prijs te geven.

Stel Element Key-back-up en kruisondertekening veilig in.

Stel Element Key-back-up en kruisondertekening veilig in.

Sla een herstelsleutel op, verifieer uw Element-sessies en controleer of versleutelde berichtsleutels kunnen worden hersteld zonder de back-up te verwarren met uw accountwachtwoord.

Voorkom dat Matrix Synapse-geheugen vastloopt tijdens clientsynchronisatie.

Diagnoseer geheugenproblemen bij Synapse tijdens synchronisatie, pas de caching veilig aan, identificeer achterstanden in aanvragen en controleer of het geheugengebruik stabiel is.

Los TLS-certificaatfouten van Synapse Federation op.

Traceer Matrix-federatiecertificaatfouten naar de juiste server, herstel de TLS-keten of het CA-vertrouwen en verifieer de oplossing zonder de beveiligingscontroles uit te schakelen.

Plaats een Synapse Matrix-server veilig achter Cloudflare.

Plaats een Synapse Matrix-server veilig achter Cloudflare.

Routeer Matrix-clients en federatie via Cloudflare op HTTPS 443, behoud Synapse-ontdekking en voorkom cachen van API-verkeer of problemen met media-uploads.

Herstel Matrix Synapse veilig met een PostgreSQL-dump.

Maak een back-up van Synapse met pg_dump, bescherm de ondertekeningssleutel en de media, en herstel de back-up in een schone PostgreSQL-database zonder verouderde eenmalige sleutels opnieuw te gebruiken.

Mjölnir als Matrix Room Moderation Bot uitvoeren met Docker

Mjölnir als Matrix Room Moderation Bot uitvoeren met Docker

Configureer Mjölnir met een speciaal Matrix-account, een versleutelde beheerruimte, Docker Compose, een beleidslijst en toegangsrechtencontroles.

Schakel native Matrix Sliding Sync in voor sneller laden op mobiele apparaten.

Schakel native Matrix Sliding Sync in voor sneller laden op mobiele apparaten.

Sla de verouderde proxy over en configureer Synapse's ingebouwde Sliding Sync. Controleer de clientdetectie en meet vervolgens het laadgedrag van de kamerlijst en het herverbindingsgedrag op een compatibele telefoon.