Conectați Element Web la Keycloak prin Synapse OIDC

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.

Lasă un comentariu

Rezolvați erorile de permisiune ale administratorului camerei Matrix prin acțiune

Urmăriți M_FORBIDDEN la nivelurile de putere ale camerei, la apartenența la serverul Synapse sau la accesul de administrator, apoi restaurați doar permisiunea de care are nevoie acțiunea blocată.

Faceți serverul dvs. Matrix Synapse accesibil pentru federație

Faceți serverul dvs. Matrix Synapse accesibil pentru federație

Configurați descoperirea sinapselor, HTTPS și rutarea proxy, astfel încât alte servere de acasă Matrix să poată găsi și contacta serverul dvs.

Conectați Element Web la Keycloak prin Synapse OIDC

Configurați un client Keycloak OIDC și un furnizor Synapse, astfel încât utilizatorii Element Web să se poată conecta prin serverul de identitate fără a expune secretele clientului.

Configurați în siguranță backup-ul și semnarea încrucișată a cheilor elementare

Configurați în siguranță backup-ul și semnarea încrucișată a cheilor elementare

Salvați o cheie de recuperare, verificați sesiunile Element și verificați dacă cheile mesajelor criptate pot fi restaurate fără a confunda copia de rezervă cu parola contului.

Memoria Stop Matrix Synapse se blochează în timpul sincronizării clientului

Diagnosticați erorile de memorie insuficientă ale sinapselor în timpul sincronizării, ajustați memoria cache în siguranță, identificați restanțele la solicitări și verificați utilizarea stabilă a memoriei.

Rezolvarea erorilor de certificat TLS Synapse Federation

Urmăriți erorile certificatelor de federație Matrix la serverul corect, reparați lanțul TLS sau încrederea CA și verificați remedierea fără a dezactiva verificările de securitate.

Instalați un server Synapse Matrix în spatele Cloudflare în siguranță

Instalați un server Synapse Matrix în spatele Cloudflare în siguranță

Dirijați clienții Matrix și federația prin Cloudflare pe HTTPS 443, păstrați descoperirea Synapse și evitați stocarea în cache a traficului API sau întreruperea încărcărilor media.

Restaurarea sinapselor matriceale în siguranță cu un dump PostgreSQL

Faceți o copie de rezervă a Synapse cu pg_dump, protejați cheia de semnare și mediul de stocare și restaurați-le într-o bază de date PostgreSQL curată, fără a reutiliza chei de unică folosință învechite.

Rulează Mjölnir ca un bot de moderare a camerei Matrix cu Docker

Rulează Mjölnir ca un bot de moderare a camerei Matrix cu Docker

Configurați Mjölnir cu un cont Matrix dedicat, o cameră de administrare criptată, Docker Compose, o listă de politici și verificări de permisiuni.

Activați sincronizarea glisantă nativă a matricei pentru o încărcare mobilă mai rapidă

Activați sincronizarea glisantă nativă a matricei pentru o încărcare mobilă mai rapidă

Sari peste proxy-ul retras și configurează funcția Sliding Sync încorporată în Synapse. Verifică descoperirea clienților, apoi măsoară comportamentul de încărcare și reconectare a listei de camere pe un telefon compatibil.