Per aggiungere l'accesso tramite Keycloak a Element Web, configura Keycloak come provider OpenID Connect (OIDC) in Synapse e assicurati che Element Web utilizzi tale homeserver di Synapse. Synapse gestisce il reindirizzamento e la callback di autenticazione; Element Web non necessita del client secret di Keycloak.
Scenario di esempio (ipotetico): una piccola organizzazione utilizza Element Web all'indirizzo chat.example.org, Synapse all'indirizzo matrix.example.orge Keycloak all'indirizzo login.example.org. La stessa sequenza si applica agli altri hostname, ma ogni URL deve corrispondere alla configurazione pubblica effettiva. Questo esempio è puramente illustrativo e non rappresenta una configurazione reale.
Cosa ti serve prima di modificare le impostazioni
Utilizzare URL HTTPS pubblici per Keycloak e Synapse. La documentazione OIDC di Synapse richiede un'origine sicura per il provider di identità e il suo callback deve essere raggiungibile tramite l'URL pubblico di Synapse. Verificare il nome del realm in Keycloak, in Synapse public_baseurle l'URL del server principale fornito a Element Web. Se un proxy inverso si trova davanti a uno dei due servizi, deve inoltrare le richieste al backend corretto e preservare l'host e lo schema HTTPS esterni.
La configurazione attuale di Synapse utilizza un oidc_providerselenco. Il vecchio formato a singolo provider oidc_configè obsoleto. Durante la fase di test, mantieni un login amministratore funzionante e una copia della configurazione corrente. Non disabilitare l'accesso tramite password o la registrazione finché non avrai verificato il flusso SSO e deciso come verranno creati gli account.
1. Registra Synapse come client in Keycloak
Nel realm Keycloak in cui risiedono gli utenti della tua organizzazione, crea un client OpenID Connect per Synapse. L'esempio ufficiale di Synapse per Keycloak utilizza un client riservato con ID client synapse. Imposta l'URI di reindirizzamento valido su questo callback, sostituendo il nome host di Synapse con il tuo:
https://matrix.example.org/_synapse/client/oidc/callback
Per la configurazione ipotetica, imposta il tipo di accesso client su riservato e abilita il client. Nella scheda Credenziali, copia il segreto client generato nel tuo sistema di gestione dei segreti; non inserirlo nella sezione pubblica di Element Web config.jsonné pubblicarlo in un repository.
L'URI di reindirizzamento è una frequente causa di errore. Deve utilizzare l'URL pubblico di Synapse, il /_synapse/client/oidc/callbackpercorso esatto e lo stesso schema e nome host che Synapse vede dal browser. Evita di utilizzare un callback con caratteri jolly generici quando un URI esatto è sufficiente. Se in seguito abiliti il logout tramite back-channel, aggiungi anche l'endpoint back-channel documentato di Synapse in Keycloak; questa operazione è facoltativa e separata dall'accesso di base.
2. Aggiungi il provider Keycloak a Synapse
Modifica l'oggetto attivo homeserver.yaml. Sostituisci il realm e il secret qui sotto con i tuoi valori e conferma l'URL dell'emittente dal documento di rilevamento OpenID del realm. L'emittente del realm standard di Keycloak ha questa struttura:
https://login.example.org/realms/your-realm
Per una distribuzione che utilizza l'endpoint di rilevamento standard e le attestazioni mostrate nell'esempio Keycloak di Synapse, la voce del provider è:
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 }}"
L'emittente deve corrispondere all'emittente del realm di Keycloak, non solo alla root del server Keycloak. La funzionalità Discovery consente a Synapse di ottenere gli endpoint di autorizzazione, token e informazioni utente da tale emittente. La mappatura utilizza l'ID locale di Keycloak preferred_usernameper formare un ID locale Matrix e namecome nome visualizzato; assicurati che queste attestazioni siano presenti e stabili per i tuoi utenti. Un ID locale Matrix è un identificatore di account, quindi la modifica della mappatura in un secondo momento potrebbe rendere confusa la corrispondenza degli account o produrre un ID Matrix diverso.
Mantieni l'elenco esistente oidc_providersse sono configurati altri provider di identità; aggiungi questa voce anziché sostituire i provider non correlati. Proteggi il segreto del client come segreto e imposta i permessi dei file in base alla tua distribuzione. Convalida l'indentazione YAML, quindi riavvia Synapse utilizzando la procedura di servizio o container per la tua installazione. Le installazioni pacchettizzate potrebbero già includere le dipendenze OIDC; per un'installazione in virtualenv, consulta la documentazione di Synapse sull'installazione matrix-synapse[oidc]. Segui le indicazioni del manutentore del pacchetto per altri metodi di installazione.
3. Puntare Element Web sullo stesso homeserver
Element Web config.jsondovrebbe identificare il server Synapse come homeserver, ad esempio tramite default_server_config.mHomeserver.base_url. Utilizzare l'URL effettivo dell'homeserver, non quello dell'emittente Keycloak. Element Web è un client statico: ridistribuire o ricaricare la sua configurazione utilizzando il metodo di hosting dopo aver modificato l'URL dell'homeserver. Non inserire il client secret di Keycloak in questo file perché i browser possono leggerlo.
Per l'esempio ipotetico, Element Web è ospitato su https://chat.example.orge si connette a https://matrix.example.org. Quando un utente seleziona l'opzione SSO nella schermata di accesso di Element, il browser dovrebbe passare attraverso il flusso di accesso di Synapse al realm di Keycloak e tornare alla funzione di callback di Synapse. La dicitura esatta del pulsante e il layout della schermata di accesso possono variare a seconda della versione di Element Web e della configurazione del server; testare il comportamento anziché affidarsi a un'etichetta specifica.
4. Esegui un test con un account prima di imporre l'SSO.
Apri Element Web in una finestra di navigazione privata e seleziona l'opzione di accesso SSO. Accedi con un utente Keycloak di prova, approva l'accesso richiesto se richiesto e verifica che il browser torni al server principale previsto e apra l'account Matrix atteso. Controlla che l'ID Matrix risultante abbia la parte locale corretta. Se il browser restituisce un errore, consulta i log di Synapse e Keycloak.
Se il reindirizzamento non riesce, confronta l'URL di callback in Keycloak carattere per carattere con l'URL di callback pubblico di Synapse. Un "errore di incompatibilità dell'emittente" indica un emittente del realm errato o un nome host del proxy inverso errato. Un nome utente mancante o un errore di mappatura significa che la rivendicazione configurata è assente o non idonea; esamina le rivendicazioni dell'utente di test e modifica la mappatura in modo mirato. Se il browser raggiunge Keycloak ma non restituisce alcun risultato, controlla i certificati TLS e il routing del proxy per la callback di Synapse.
Disconnessione facoltativa: Synapse supporta la disconnessione tramite canale secondario OIDC. Per utilizzarla, impostarla backchannel_logout_enabled: truein questo provider e configurare l'URL di disconnessione tramite canale secondario di Keycloak come https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse documenta anche l'abilitazione dell'opzione session-required in Keycloak. Questa gestisce le notifiche di disconnessione avviate dal provider; non è necessaria per il funzionamento dell'accesso SSO iniziale.
Prima del rollout: decidi se l'SSO deve creare nuovi utenti Matrix o autenticare solo gli account che gestisci separatamente, quindi esamina le opzioni OIDC di Synapse per la versione installata. Le etichette di configurazione e l'interfaccia utente di amministrazione di Keycloak possono cambiare tra le diverse versioni. I passaggi qui descritti seguono la documentazione OIDC di Synapse disponibile il 10 ottobre 2026 e presuppongono un realm Keycloak standard e un'implementazione di Synapse che utilizza il formato del provider documentato. Consulta la guida Synapse OpenID Connect e Keycloak , il riferimento di configurazione di Synapse e la documentazione ufficiale di Keycloak prima di applicare le impostazioni specifiche della versione. Una volta che l'account di test ha effettuato l'accesso correttamente e hai una route di ripristino, documenta la mappatura finale di callback, emittente e claim per gli amministratori.