Connetti Element Web a Keycloak tramite Synapse OIDC

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.

Lascia un commento

Risolvi gli errori di autorizzazione amministrativa della stanza Matrix tramite azione

Individuare la causa di M_FORBIDDEN, che può essere ricondotta ai livelli di alimentazione della stanza, all'iscrizione dei membri o all'accesso di amministratore al server Synapse, quindi ripristinare solo l'autorizzazione necessaria per l'azione bloccata.

Rendi il tuo server Matrix Synapse raggiungibile per la federazione

Rendi il tuo server Matrix Synapse raggiungibile per la federazione

Configura il rilevamento Synapse, HTTPS e il routing proxy in modo che gli altri homeserver Matrix possano trovare e contattare il tuo server.

Connetti Element Web a Keycloak tramite Synapse OIDC

Configura un client OIDC Keycloak e un provider Synapse in modo che gli utenti di Element Web possano accedere tramite il tuo server di identità senza esporre le credenziali del client.

Configura in modo sicuro il backup e la firma incrociata delle chiavi Element.

Configura in modo sicuro il backup e la firma incrociata delle chiavi Element.

Salva una chiave di ripristino, verifica le tue sessioni Element e controlla che le chiavi dei messaggi crittografati possano essere ripristinate senza confondere il backup con la password del tuo account.

Rimuovi i crash di memoria di Matrix Synapse durante la sincronizzazione del client

Diagnostica gli errori di memoria insufficiente di Synapse durante la sincronizzazione, regola la cache in modo sicuro, identifica i ritardi nelle richieste e verifica un utilizzo stabile della memoria.

Risolvere gli errori del certificato TLS di Synapse Federation

Individuare gli errori del certificato di federazione Matrix sul server corretto, riparare la catena TLS o la relazione di fiducia con la CA e verificare la correzione senza disabilitare i controlli di sicurezza.

Posizionare un server Synapse Matrix dietro Cloudflare in modo sicuro

Posizionare un server Synapse Matrix dietro Cloudflare in modo sicuro

Instrada i client Matrix e la federazione tramite Cloudflare su HTTPS 443, preserva il rilevamento di Synapse ed evita la memorizzazione nella cache del traffico API o l'interruzione del caricamento dei file multimediali.

Ripristinare Matrix Synapse in modo sicuro con un dump di PostgreSQL

Esegui il backup di Synapse con pg_dump, proteggi la chiave di firma e i supporti di memorizzazione e ripristina il tutto in un database PostgreSQL pulito senza riutilizzare chiavi monouso obsolete.

Esegui Mjölnir come bot di moderazione per le stanze Matrix con Docker

Esegui Mjölnir come bot di moderazione per le stanze Matrix con Docker

Configura Mjölnir con un account Matrix dedicato, una sala di gestione crittografata, Docker Compose, un elenco di policy e controlli di autorizzazione.

Attiva la sincronizzazione nativa dello scorrimento della matrice per un caricamento più rapido sui dispositivi mobili.

Attiva la sincronizzazione nativa dello scorrimento della matrice per un caricamento più rapido sui dispositivi mobili.

Ignora il proxy obsoleto e configura Sliding Sync, la funzione integrata di Synapse. Verifica il rilevamento dei client, quindi misura il caricamento dell'elenco delle stanze e il comportamento di riconnessione su un telefono compatibile.