Hoe configureer je Single Sign-On (SSO) met Keycloak in Element Web?

Element Web authenticeert niet rechtstreeks via Keycloak. Element vraagt ​​zijn Matrix-homeserver naar ondersteunde inlogmethoden; de homeserver voltooit OpenID Connect (OIDC) met Keycloak en stuurt de gebruiker terug naar Element. Voor een Synapse-implementatie die gebruikmaakt van de ingebouwde OIDC-ondersteuning, configureert u een vertrouwelijke OIDC-client in Keycloak, voegt u die provider toe aan Synapse en past u eventueel de instellingen van Element Web aan config.jsonom SSO weer te geven of automatisch te starten.

Deze handleiding maakt gebruik van de ingebouwde OIDC-provider van Synapse, een veelgebruikte implementatiemethode. Als uw homeserver de authenticatie delegeert aan Matrix Authentication Service (MAS), gebruik dan in plaats daarvan de MAS-callback en providerconfiguratie die hieronder worden beschreven. De twee callback-URL's zijn verschillend. De instructies zijn gecontroleerd aan de hand van de configuratiedocumentatie van Element Web, de Synapse v1.144 OIDC-handleiding, de huidige MAS upstream SSO-handleiding en de Keycloak 26.8.0-beheerhandleiding op 6 oktober 2026; de implementatiepakketten en UI-labels kunnen per versie verschillen.

Identificeer eerst welk authenticatiepad u gebruikt.

Raadpleeg de documentatie voor Synapse-configuratie en -implementatie voordat u een client aanmaakt. De callback moet behoren tot de component die met Keycloak communiceert; registreer niet de website-URL van Element als callback.

Wat je nodig hebt

• Een openbare HTTPS-URL voor Synapse, bijvoorbeeld https://matrix.example.com, en een bereikbare Keycloak-realm-uitgever, bijvoorbeeld https://sso.example.com/realms/company.
• Administratieve toegang tot het Keycloak-domein en de Synapse-configuratie en -service.
• Een back-up van de huidige configuratie en een manier om Synapse-logboeken of een serverconsole te gebruiken als het aanmelden mislukt.
• Een beslissing over accountprovisionering: welke Keycloak-gebruikers mogen inloggen, welke claim hen identificeert en of bestaande Matrix-accounts behouden moeten blijven.

Keycloak configureren voor Synapse OIDC

1. Maak een vertrouwelijke OIDC-client aan.

Maak in het domein dat voor Matrix-accounts wordt gebruikt een client voor Synapse aan met behulp van het OpenID Connect-protocol. Schakel de autorisatiecode of standaardflow en clientauthenticatie in, zodat Synapse een clientgeheim kan gebruiken bij het token-eindpunt. Stel de client-ID in op een waarde die u ook in Synapse zult gebruiken, bijvoorbeeld synapse.

Stel de geldige omleidings-URI in op de exacte Synapse-callback:

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

Vervang de voorbeeldhostnaam door de openbare basis-URL die daadwerkelijk voor Synapse is geconfigureerd. Gebruik geen brede wildcard zoals *in een productieomgeving. Keycloak valideert redirect-URI's, dus een mismatch in host, schema, pad of afsluitende slash kan een foutmelding "redirect-URI is not allowed" veroorzaken.

Sla de client op, kopieer het gegenereerde geheim en bewaar dit als een servergeheim. Houd het buiten het openbare bestand van Element Web config.json, versiebeheer, screenshots en client-side JavaScript. De Keycloak-beheerconsole kan clientauthenticatie of -gegevens in verschillende versies anders labelen; controleer of de resulterende client vertrouwelijk is en de standaard autorisatiecodeflow kan gebruiken.

2. Bevestig de uitgever en de vorderingen

De uitgever identificeert het domein, niet de root van de Keycloak-server. Gebruik in dit voorbeeld https://sso.example.com/realms/company. Controleer of de OpenID-configuratie van het domein bereikbaar is op <issuer>/.well-known/openid-configurationen of de geadverteerde uitgever exact overeenkomt met de waarde die u aan Synapse zult doorgeven.

Synapse heeft een stabiele identiteitsclaim nodig om het Keycloak-account aan een Matrix-gebruiker te koppelen. De OIDC-provider identificeert het externe subject normaal gesproken met behulp van de OIDC-subjectclaim; de onderstaande gebruikersnaamtoewijzing gebruikt preferred_usernameals Matrix localpart. Zorg ervoor dat Keycloak daadwerkelijk die claim retourneert en dat gebruikersnamen uniek en stabiel zijn volgens uw accountbeleid. Als uw organisatie wijzigingen in gebruikersnamen toestaat, kies en test dan een toewijzingsstrategie vóór de implementatie; een onverwachte wijziging in de toewijzing kan van invloed zijn op welk Matrix-account een persoon bereikt.

Synapse configureren

3. Voeg de OIDC-provider toe.

Voeg een providervermelding toe aan de hoofdconfiguratie van Synapse, meestal homeserver.yaml. Voeg deze samen met de bestaande YAML in plaats van andere instellingen te vervangen. Vervang uw realm-uitgever en het echte clientgeheim:

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

De gevraagde scopes bepalen welke gebruikersinformatie Keycloak mag retourneren; ze garanderen niet dat elke claim wordt ingevuld. Als u geen e-mail- of weergavenaamimport nodig hebt, verklein dan de scopes en de bijbehorende mapping. Zorg ervoor dat het configuratiebestand alleen leesbaar is voor de servicebeheerder en het Synapse-proces, afhankelijk van uw implementatie. Als u Synapse beheert via containers of een chart, plaats de providerinstellingen dan in de ondersteunde configuratiebron in plaats van een gegenereerd bestand te bewerken dat toch wordt overschreven.

4. Configureer optioneel de back-channel logout.

Standaard wordt bij het uitloggen uit één service niet automatisch de browsersessie van alle andere services beëindigd. Als u wilt dat Keycloak-uitlogmeldingen de Synapse-sessie beëindigen, schakelt u dit in backchannel_logout_enabled: trueonder de Keycloak-provider in Synapse en stelt u de Backchannel Logout URL van Keycloak in op:

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

Dit is optioneel en hangt af van uw uitlogbeleid en clientinstellingen. Test beide uitlogrichtingen: uitloggen bij Synapse en uitloggen bij Keycloak. Ga er niet van uit dat uitloggen bij Element alleen de Keycloak-sessie beëindigt.

5. Herstart en test Synapse

Valideer het YAML-bestand met de configuratiecontroles van uw implementatie en herstart of herlaad Synapse vervolgens met behulp van de methode die wordt ondersteund door uw pakket- of containerconfiguratie. Controleer de Synapse-logboeken op fouten met betrekking tot OIDC-detectie, clientauthenticatie, callbacks of claimtoewijzing. Gebruik eerst een testaccount en controleer of de Matrix ID en weergavenaam de verwachte waarden hebben.

Element Web configureren

6. Houd SSO optioneel of verwijs automatisch door.

Zodra Synapse OIDC-aanmelding ondersteunt, kan Element Web de SSO-aanmeldingsoptie presenteren. sso_redirect_optionsDe instellingen van Element bepalen de gebruikerservaring; ze configureren Keycloak niet en slaan het clientgeheim niet op. Voeg een instelling zoals deze toe aan de `served`-configuratie van Element Web config.jsonals u wilt dat niet-geauthenticeerde bezoekers die op de welkomst- of inlogpagina terechtkomen, worden doorverwezen naar de beschikbare SSO-flow:

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

Voor een implementatie die echt alleen SSO-aanmelding vereist, stelt u in "immediate": truedat SSO wordt gestart voor alle niet-geauthenticeerde gebruikers. Dit kan het lastiger maken om toegang te krijgen tot wachtwoorden of andere inlogopties, dus test herstel en beheerdersrechten voordat u dit afdwingt. Als gebruikers moeten kunnen kiezen tussen SSO en een andere methode, laat u automatische omleiding uitgeschakeld en controleert u of de SSO-optie in het inlogproces verschijnt.

Als Synapse gebruikmaakt van de Matrix Authentication Service.

MAS is een aparte authenticatieservice en kan fungeren als OIDC-client voor Keycloak. Configureer in die architectuur de redirect-URI van Keycloak als https://auth.example.com/upstream/callback/<provider-id>, waarbij de provider-ID overeenkomt met de MAS-configuratie. Configureer de provider onder MAS's upstream_oauth2.providers; Het element gebruikt vervolgens de op MAS gebaseerde authenticatiestroom van de homeserver. Gebruik Synapse's niet /_synapse/client/oidc/callbackvoor deze upstream-verbinding. MAS vereist een OIDC-provider die de autorisatiecodestroom ondersteunt. Het configuratieformaat, de vereiste provider-ID en de migratiestappen verschillen van Synapse's ingebouwde oidc_providers.

Veelvoorkomende misverstanden en oplossingen

• “Ik hoef alleen de configuratie van Element aan te passen.” Element regelt de browserflow, terwijl Synapse of MAS de OIDC-communicatie afhandelt. Configureer eerst de juiste provider aan de serverzijde.
• "Een succesvolle Keycloak-login bewijst dat de accounttoewijzing correct is." Authenticatie kan slagen, zelfs als de verkeerde localpart of profielclaim is geselecteerd. Test met een niet-productiegebruiker en controleer de resulterende Matrix ID.
• "SSO schakelt wachtwoorden en registratie automatisch uit." Deze beleidsregels worden beheerd door de homeserver en de implementatie. Controleer de inlog- en registratie-instellingen van Synapse afzonderlijk en bevestig het goedgekeurde beleid.
• “Als ik uitlog bij Element, word ik overal uitgelogd.” Browsersessies kunnen actief blijven bij Keycloak. Configureer en test de back-channel logout als centrale sessiebeëindiging vereist is.

Controlelijst voor verificatie

• De Keycloak-client maakt gebruik van de autorisatiecodeflow, clientauthenticatie en de exacte callback voor Synapse of MAS.
• De URL van de uitgever komt overeen met de ontdekkingsmetadata van het domein, en het clientgeheim wordt aan de serverzijde opgeslagen.
• Synapse of MAS start zonder OIDC-configuratiefouten en toont de beoogde inlogmethode.
• Een testgebruiker kan inloggen vanuit een nieuwe browsersessie, komt terecht in het verwachte Matrix-account en kan een normale Element-sessie voltooien.
• Het uitloggedrag, bestaande accounts, registratiebeperkingen en eventuele alternatieve beheerdersrechten moeten overeenkomen met uw beleid.

Officiële referenties

• Handleiding voor Synapse v1.144 OpenID Connect, inclusief Keycloak-client- en callback-instellingen.
• Element Web-configuratie: SSO-omleidingsopties
• Matrix Authentication Service: een upstream SSO-provider configureren
• Keycloak 26.8.0 Serverbeheerhandleiding