Come configurare il Single Sign-On (SSO) con Keycloak in Element Web

Element Web non si autentica direttamente con Keycloak. Element richiede al suo homeserver Matrix i metodi di accesso supportati; l'homeserver completa la connessione OpenID Connect (OIDC) con Keycloak e restituisce l'utente a Element. Per una distribuzione Synapse che utilizza il supporto OIDC integrato, è necessario configurare un client OIDC riservato in Keycloak, aggiungere tale provider a Synapse e, facoltativamente, modificare le impostazioni di Element Web config.jsonper visualizzare o avviare automaticamente l'SSO.

Questa guida utilizza il provider OIDC integrato di Synapse, che rappresenta una soluzione di implementazione comune. Se il server principale delega l'autenticazione al servizio di autenticazione Matrix (MAS), utilizzare invece la configurazione del callback e del provider MAS descritta di seguito. I due URL di callback sono diversi. Le istruzioni sono state verificate rispetto alla documentazione di configurazione di Element Web, alla guida OIDC di Synapse v1.144, alla guida SSO upstream di MAS corrente e alla guida di amministrazione di Keycloak 26.8.0 il 6 ottobre 2026; il packaging di implementazione e le etichette dell'interfaccia utente possono variare a seconda della versione.

Innanzitutto, identifica quale percorso di autenticazione utilizzi

Prima di creare un client, verifica la configurazione di Synapse e la documentazione di distribuzione. La funzione di callback deve appartenere al componente che comunica con Keycloak; non registrare l'URL del sito web di Element come funzione di callback.

Ciò di cui hai bisogno

• Un URL HTTPS pubblico per Synapse, come ad esempio https://matrix.example.com, e un emittente di realm Keycloak raggiungibile, come ad esempio https://sso.example.com/realms/company.
• Accesso amministrativo al dominio Keycloak e alla configurazione e al servizio Synapse.
• Un backup della configurazione corrente e un modo per utilizzare i log di Synapse o una console del server in caso di errore di accesso.
• Una decisione relativa alla creazione degli account: quali utenti Keycloak possono accedere, quale attestazione li identifica e se gli account Matrix esistenti devono essere mantenuti.

Configurare Keycloak per Synapse OIDC

1. Creare un client OIDC riservato

Nel realm utilizzato per gli account Matrix, crea un client per Synapse utilizzando il protocollo OpenID Connect. Abilita il codice di autorizzazione o il flusso standard e l'autenticazione client in modo che Synapse possa utilizzare un segreto client all'endpoint del token. Imposta l'ID client su un valore che utilizzerai anche in Synapse, ad esempio synapse.

Imposta l'URI di reindirizzamento valido sull'esatta funzione di callback di Synapse:

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

Sostituisci il nome host di esempio con l'URL di base pubblico effettivamente configurato per Synapse. Non utilizzare un carattere jolly generico come *in produzione. Keycloak convalida gli URI di reindirizzamento, quindi una mancata corrispondenza di host, schema, percorso o barra finale può causare un errore "URI di reindirizzamento non consentito".

Salva il client, copia il segreto generato e memorizzalo come segreto lato server. Tienilo al di fuori di Element Web config.json, del controllo di versione, degli screenshot e del codice JavaScript lato client. La console di amministrazione di Keycloak potrebbe etichettare l'autenticazione o le credenziali del client in modo diverso a seconda della versione; verifica che il client risultante sia riservato e possa utilizzare il flusso standard del codice di autorizzazione.

2. Confermare l'emittente e le richieste

L'emittente identifica il realm, non la radice del server Keycloak. Per questo esempio, usa https://sso.example.com/realms/company. Verifica che la configurazione OpenID del realm sia raggiungibile all'indirizzo <issuer>/.well-known/openid-configuratione che l'emittente pubblicizzato corrisponda esattamente al valore che fornirai a Synapse.

Synapse necessita di un claim di identità stabile per associare l'account Keycloak a un utente Matrix. Il suo provider OIDC identifica normalmente il soggetto esterno utilizzando il claim del soggetto OIDC; la mappatura del nome utente riportata di seguito utilizza preferred_usernamela parte locale di Matrix. Assicurati che Keycloak restituisca effettivamente tale claim e che i nomi utente siano univoci e stabili in base alla tua policy di account. Se la tua organizzazione consente modifiche al nome utente, scegli e testa una strategia di mappatura prima della produzione; una modifica imprevista della mappatura può influire sull'account Matrix a cui una persona può accedere.

Configura Synapse

3. Aggiungere il provider OIDC

Aggiungi una voce provider alla configurazione principale di Synapse, solitamente homeserver.yaml. Uniscila al file YAML esistente invece di sostituire altre impostazioni. Sostituisci l'emittente del tuo realm e il segreto client effettivo:

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

Gli ambiti richiesti controllano quali informazioni utente Keycloak può restituire; non garantiscono che ogni claim venga popolato. Se non è necessario importare email o nome visualizzato, ridurre gli ambiti e la mappatura di conseguenza. Mantenere il file di configurazione leggibile solo dall'amministratore del servizio e dal processo Synapse, a seconda delle esigenze della propria implementazione. Se si gestisce Synapse tramite container o un chart, inserire le impostazioni del provider nell'origine di configurazione supportata anziché modificare un file generato che verrà sovrascritto.

4. Configurare facoltativamente il logout tramite canale secondario

Per impostazione predefinita, la disconnessione da un servizio non termina necessariamente la sessione del browser di tutti gli altri servizi. Se desideri che le notifiche di disconnessione di Keycloak terminino la sessione di Synapse, abilita l'opzione backchannel_logout_enabled: truenel provider Keycloak in Synapse e imposta l'URL di disconnessione backchannel di Keycloak su:

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

Questa operazione è facoltativa e dipende dalle tue policy di disconnessione e dalla configurazione del client. Prova entrambe le modalità di disconnessione: disconnessione da Synapse e disconnessione da Keycloak. Non dare per scontato che la sola disconnessione da Element termini anche la sessione di Keycloak.

5. Riavvia e testa Synapse

Convalida il file YAML con i controlli di configurazione della tua distribuzione, quindi riavvia o ricarica Synapse utilizzando il metodo supportato dalla configurazione del tuo pacchetto o container. Esamina i log di Synapse per individuare errori relativi al rilevamento OIDC, all'autenticazione del client, al callback o alla mappatura delle rivendicazioni. Utilizza prima un account di test e verifica che il suo ID matrice e il nome visualizzato corrispondano ai valori previsti.

Configura Elemento Web

6. Mantenere l'SSO facoltativo o reindirizzare automaticamente

Una volta che Synapse pubblicizza l'accesso OIDC, Element Web può presentare la sua opzione di accesso SSO. L'impostazione di Element sso_redirect_optionscontrolla l'esperienza del browser; non configura Keycloak né memorizza il client secret. Aggiungi un'impostazione simile a questa al server di Element Web config.jsonse desideri che i visitatori non autenticati che arrivano alla pagina di benvenuto o di accesso vengano indirizzati al flusso SSO disponibile:

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

Per un'implementazione che richiede effettivamente l'accesso esclusivamente tramite SSO, imposta "immediate": truel'attivazione dell'SSO per tutti gli utenti non autenticati. Ciò potrebbe rendere più difficile l'accesso tramite password o altri metodi di login, quindi testa l'accesso di recupero e di amministratore prima di renderlo obbligatorio. Se gli utenti devono scegliere tra SSO e un altro metodo, lascia disabilitato il reindirizzamento automatico e verifica che l'opzione SSO venga visualizzata nel flusso di accesso.

Se Synapse utilizza il servizio di autenticazione Matrix

MAS è un servizio di autenticazione separato e può fungere da client OIDC per Keycloak. In tale architettura, configurare l'URI di reindirizzamento di Keycloak come https://auth.example.com/upstream/callback/<provider-id>, dove l'ID del provider corrisponde alla configurazione MAS. Configurare il provider in upstream_oauth2.providers; Element utilizza quindi il flusso di autenticazione basato su MAS del server principale. Non utilizzare quello di Synapse /_synapse/client/oidc/callbackper questa connessione upstream. MAS richiede un provider OIDC che supporti il ​​flusso del codice di autorizzazione. Il suo formato di configurazione, l'ID del provider richiesto e i passaggi di migrazione sono distinti da quelli integrati di Synapse oidc_providers.

Errori comuni e relative soluzioni

• "Devo solo modificare la configurazione di Element." Element controlla il flusso del browser, mentre Synapse o MAS gestiscono l'OIDC. Configura prima il provider corretto sul lato homeserver.
• "Un accesso a Keycloak riuscito dimostra che la mappatura dell'account è corretta." L'autenticazione può avere successo anche se è stato selezionato il localpart o il profilo di rivendicazione errato. Eseguire un test con un utente non di produzione e verificare l'ID matrice risultante.
• "L'SSO disabilita automaticamente password e registrazione." Queste policy sono controllate dal server principale e dalla distribuzione. Esamina separatamente le impostazioni di accesso e registrazione di Synapse e conferma la policy approvata.
• "Esci da Element e scomparirò da tutti i dispositivi." Le sessioni del browser possono rimanere attive su Keycloak. Configurare e testare il logout tramite canale secondario se è necessaria la terminazione centralizzata della sessione.

Lista di controllo per la verifica

• Il client Keycloak utilizza il flusso del codice di autorizzazione, l'autenticazione del client e la callback esatta per Synapse o MAS.
• L'URL dell'emittente corrisponde ai metadati di rilevamento del realm e il segreto del client viene memorizzato lato server.
• Synapse o MAS si avviano senza errori di configurazione OIDC ed espongono il metodo di accesso previsto.
• Un utente di prova può accedere da una nuova sessione del browser, ottenere l'account Matrix previsto e completare una normale sessione Element.
• Il comportamento di disconnessione, gli account esistenti, le restrizioni di registrazione e qualsiasi accesso amministratore di riserva devono corrispondere alla tua policy.

Riferimenti ufficiali

• Guida a Synapse v1.144 OpenID Connect, incluse le impostazioni del client Keycloak e del callback.
• Configurazione di Element Web: opzioni di reindirizzamento SSO
• Matrix Authentication Service: configurazione di un provider SSO a monte
• Guida all'amministrazione del server Keycloak 26.8.0