Pentru a adăuga autentificarea Keycloak la Element Web, configurați Keycloak ca furnizor OpenID Connect (OIDC) în Synapse, apoi asigurați-vă că Element Web utilizează serverul de bază Synapse respectiv. Synapse gestionează redirecționarea și apelul invers de autentificare; Element Web nu are nevoie de secretul clientului Keycloak.
Scenariu exemplu (ipotetic): o organizație mică rulează Element Web la chat.example.org, Synapse la matrix.example.orgși Keycloak la login.example.org. Aceeași secvență se aplică și altor nume de gazdă, dar fiecare adresă URL trebuie să corespundă configurației dvs. publice reale. Acest exemplu este ilustrativ, nu un raport al unei configurări live.
Ce aveți nevoie înainte de a schimba setările
Folosește adrese URL HTTPS publice pentru Keycloak și Synapse. Documentația OIDC a Synapse necesită o origine securizată pentru furnizorul de identitate, iar apelul său invers trebuie să fie accesibil prin adresa URL publică Synapse. Confirmă numele realm-ului în Keycloak, numele Synapse-ului public_baseurlși adresa URL a serverului principal servită către Element Web. Dacă un proxy invers se află în fața oricăruia dintre servicii, acesta trebuie să transmită cererile către backend-ul corect și să păstreze gazda și schema HTTPS externă.
Configurația actuală a Synapse folosește o oidc_providerslistă. Formularul mai vechi cu un singur furnizor oidc_configeste depreciat. Păstrați un nume de utilizator de administrator funcțional și o copie a configurației actuale în timpul testării. Nu dezactivați conectarea cu parolă sau înregistrarea până când nu ați verificat fluxul SSO și nu ați decis cum vor fi furnizate conturile.
1. Înregistrați Synapse ca și client în Keycloak
În domeniul Keycloak unde locuiesc utilizatorii organizației dvs., creați un client OpenID Connect pentru Synapse. Exemplul oficial Keycloak al Synapse utilizează un client confidențial cu ID client synapse. Setați URI-ul de redirecționare valid la această apelare inversă exactă, înlocuind numele de gazdă Synapse:
https://matrix.example.org/_synapse/client/oidc/callback
Pentru configurarea ipotetică, setați tipul de acces al clientului la confidențial și activați clientul. În fila Acreditări, copiați secretul clientului generat în sistemul dvs. de gestionare a secretelor; nu îl plasați în publicul Element Web config.jsonși nu îl publicați într-un depozit.
URI-ul de redirecționare este o sursă frecventă de eșecuri. Trebuie să utilizeze adresa URL publică Synapse, /_synapse/client/oidc/callbackcalea exactă și aceeași schemă și nume de gazdă pe care Synapse le vede din browser. Evitați o apelare wildcard largă atunci când un URI exact va funcționa. Dacă ulterior activați deconectarea de pe canalul secundar, adăugați și endpoint-ul documentat de pe canalul secundar al Synapse în Keycloak; acest lucru este opțional și separat de autentificarea de bază.
2. Adăugați furnizorul Keycloak la Synapse
Editați codul activ homeserver.yaml. Înlocuiți realmul și secretul de mai jos cu valorile dvs. și confirmați adresa URL a emitentului din documentul de descoperire OpenID al realmului. Emitentul standard al realmului Keycloak are această formă:
https://login.example.org/realms/your-realm
Pentru o implementare care utilizează endpoint-ul standard de descoperire și revendicările prezentate în exemplul Keycloak al Synapse, intrarea furnizorului este:
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 }}"
Emitentul trebuie să corespundă cu emitentul realm-ului Keycloak, nu doar cu rădăcina serverului Keycloak. Discovery permite Synapse să obțină endpoint-urile de autorizare, token și informații despre utilizator de la emitentul respectiv. Maparea folosește Keycloak-urile preferred_usernamepentru a forma o localpart Matrix și nameca nume afișat; asigurați-vă că aceste revendicări sunt prezente și stabile pentru utilizatorii dvs. O localpart Matrix este un identificator de cont, așadar modificarea ulterioară a mapării poate face ca potrivirea contului să fie confuză sau poate produce un ID Matrix diferit.
Păstrați lista existentă oidc_providersdacă sunt configurați alți furnizori de identitate; adăugați această intrare în loc să înlocuiți furnizorii fără legătură. Protejați secretul clientului ca secret și setați permisiunile fișierului în funcție de implementarea dvs. Validați indentarea YAML, apoi reporniți Synapse utilizând procedura de serviciu sau container pentru instalarea dvs. Instalările pachet pot include deja dependențe OIDC; pentru o instalare virtualenv, Synapse documentează instalarea matrix-synapse[oidc]. Urmați instrucțiunile administratorului pachetului pentru alte metode de instalare.
3. Conectați Element Web la același server de acasă
Element Web config.jsonar trebui să identifice serverul Synapse ca server de domiciliu, de exemplu prin default_server_config.mHomeserver.base_url. Folosește adresa URL reală a serverului de domiciliu, nu emitentul Keycloak. Element Web este un client static: redistribuie sau reîncarcă configurația sa folosind metoda de găzduire după modificarea adresei URL a serverului de domiciliu. Nu pune secretul clientului Keycloak în acest fișier, deoarece browserele îl pot citi.
Pentru exemplul ipotetic, Element Web este găzduit la https://chat.example.orgși se conectează la https://matrix.example.org. Când un utilizator selectează opțiunea SSO pe ecranul de conectare Element, browserul ar trebui să parcurgă fluxul de conectare Synapse către realmul Keycloak și să revină la apelul invers Synapse. Formularea exactă a butoanelor și aspectul ecranului de conectare pot varia în funcție de versiunea Element Web și de configurația serverului; testați comportamentul în loc să vă bazați pe o anumită etichetă.
4. Testați cu un singur cont înainte de a aplica SSO
Deschideți Element Web într-o fereastră privată a browserului și selectați opțiunea de conectare SSO. Conectați-vă cu un utilizator Keycloak de test, aprobați accesul solicitat dacă vi se solicită și confirmați că browserul revine la serverul principal dorit și deschide contul Matrix așteptat. Verificați dacă ID-ul Matrix rezultat conține localpart-ul dorit. Examinați jurnalele Synapse și Keycloak dacă browserul returnează o eroare.
Dacă redirecționarea eșuează, comparați adresa URL de apel invers, în Keycloak caracter cu caracter, cu adresa URL publică de apel invers al Synapse. O „nepotrivire a emitentului” indică un nume de gazdă greșit pentru emitentul realmului sau pentru proxy invers. Lipsa unui nume de utilizator sau o eroare de mapare înseamnă că revendicarea configurată este absentă sau nepotrivită; inspectați revendicările utilizatorului de test și ajustați maparea în mod deliberat. Dacă browserul ajunge la Keycloak, dar nu returnează, verificați certificatele TLS și rutarea proxy pentru apelul invers Synapse.
Deconectare opțională: Synapse acceptă deconectarea prin back-channel OIDC. Pentru a o utiliza, setați backchannel_logout_enabled: truesub acest furnizor și configurați adresa URL de deconectare prin back-channel a Keycloak ca https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse documentează, de asemenea, activarea opțiunii sesiunii necesare în Keycloak. Aceasta gestionează notificările de deconectare inițiate de furnizor; nu este necesară pentru ca autentificarea SSO inițială să funcționeze.
Înainte de lansare: decideți dacă SSO ar trebui să creeze utilizatori Matrix noi sau să autentifice doar conturile pe care le furnizați separat, apoi examinați opțiunile OIDC ale Synapse pentru versiunea instalată. Etichetele de configurare și interfața de administrare Keycloak se pot modifica între versiuni. Pașii de aici respectă documentația OIDC a Synapse disponibilă pe 10 octombrie 2026 și presupun o zonă Keycloak standard și o implementare Synapse utilizând formatul furnizorului documentat. Consultați ghidul Synapse OpenID Connect și Keycloak , referința de configurare Synapse și documentația oficială Keycloak înainte de a aplica setările specifice versiunii. După ce contul de test se conectează corect și aveți o rută de recuperare, documentați maparea finală a apelului invers, a emitentului și a revendicărilor pentru administratori.