Cum se configurează autentificarea unică (SSO) cu Keycloak în Element Web

Element Web nu se autentifică direct împotriva Keycloak. Element solicită serverului său de acasă Matrix metodele de conectare acceptate; serverul de acasă finalizează OpenID Connect (OIDC) cu Keycloak și returnează utilizatorul la Element. Pentru o implementare Synapse care utilizează suportul OIDC încorporat, configurați un client OIDC confidențial în Keycloak, adăugați furnizorul respectiv la Synapse și, opțional, ajustați opțiunile Element Web config.jsonpentru a afișa sau a porni automat SSO.

Acest ghid utilizează furnizorul OIDC încorporat în Synapse, care este o cale de implementare comună. Dacă serverul dvs. principal deleagă autentificarea către Matrix Authentication Service (MAS), utilizați configurația callback-ului MAS și a furnizorului descrise mai jos. Cele două adrese URL de callback sunt diferite. Instrucțiunile au fost verificate în raport cu documentația de configurare Element Web, ghidul OIDC Synapse v1.144, ghidul SSO MAS upstream actual și ghidul de administrare Keycloak 26.8.0 pe 6 octombrie 2026; pachetul de implementare și etichetele UI pot varia în funcție de versiune.

Mai întâi, identifică ce cale de autentificare folosești

Verificați documentația de configurare și implementare Synapse înainte de a crea un client. Callback-ul trebuie să aparțină componentei care comunică cu Keycloak; nu înregistrați adresa URL a site-ului web al Element ca callback.

Ceea ce ai nevoie

• O adresă URL HTTPS publică pentru Synapse, cum ar fi https://matrix.example.com, și un emitent de realm Keycloak accesibil, cum ar fi https://sso.example.com/realms/company.
• Acces administrativ la domeniul Keycloak și la configurația și serviciul Synapse.
• O copie de rezervă a configurației curente și o modalitate de a utiliza jurnalele Synapse sau o consolă de server dacă conectarea eșuează.
• O decizie privind furnizarea conturilor: ce utilizatori Keycloak se pot conecta, ce revendicare îi identifică și dacă trebuie păstrate conturile Matrix existente.

Configurați Keycloak pentru Synapse OIDC

1. Creați un client OIDC confidențial

În domeniul utilizat pentru conturile Matrix, creați un client pentru Synapse utilizând protocolul OpenID Connect. Activați codul de autorizare sau fluxul standard și autentificarea clientului, astfel încât Synapse să poată utiliza un secret client la punctul final al token-ului. Setați ID-ul clientului la o valoare pe care o veți utiliza și în Synapse, de exemplu synapse.

Setați URI-ul de redirecționare valid la apelul invers Synapse exact:

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

Înlocuiți numele de gazdă exemplu cu adresa URL publică de bază configurată efectiv pentru Synapse. Nu utilizați un wildcard larg, cum ar fi *în producție. Keycloak validează URI-urile de redirecționare, astfel încât o nepotrivire de gazdă, schemă, cale sau bară oblică finală poate cauza o eroare de tipul „URI-ul de redirecționare nu este permis”.

Salvați clientul, copiați secretul generat și stocați-l ca secret pe server. Nu îl puteți accesa în elementele public config.json, controlul sursei, capturile de ecran și JavaScript-ul pe client ale Element Web. Consola de administrare Keycloak poate eticheta autentificarea sau acreditările clientului diferit în funcție de versiune; verificați dacă clientul rezultat este confidențial și poate utiliza fluxul standard al codului de autorizare.

2. Confirmați emitentul și revendicările

Emitentul identifică realmul, nu adresa rădăcină a serverului Keycloak. Pentru acest exemplu, utilizați https://sso.example.com/realms/company. Confirmați că configurația OpenID a realmului este accesibilă la <issuer>/.well-known/openid-configurationși că emitentul său anunțat corespunde exact cu valoarea pe care o veți da pentru Synapse.

Synapse are nevoie de o revendicare de identitate stabilă pentru a asocia contul Keycloak cu un utilizator Matrix. Furnizorul său OIDC identifică în mod normal subiectul extern folosind revendicarea subiectului OIDC; maparea numelui de utilizator de mai jos o folosește preferred_usernameca parte locală Matrix. Asigurați-vă că Keycloak returnează efectiv această revendicare și că numele de utilizator sunt unice și stabile conform politicii contului dvs. Dacă organizația dvs. permite modificări ale numelui de utilizator, alegeți și testați o strategie de mapare înainte de producție; o modificare neașteptată a mapării poate afecta contul Matrix pe care o persoană îl accesează.

Configurați Sinapsa

3. Adăugați furnizorul OIDC

Adăugați o intrare de furnizor la configurația principală a Synapse, de obicei homeserver.yaml. Îmbinați-o cu YAML-ul existent în loc să înlocuiți alte setări. Înlocuiți emitentul realm-ului și secretul clientului real:

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

Domeniile de aplicare solicitate controlează ce informații despre utilizator poate returna Keycloak; acestea nu garantează că fiecare solicitare este populată. Dacă nu aveți nevoie de importul adresei de e-mail sau al numelui afișat, reduceți domeniile de aplicare și maparea în mod corespunzător. Păstrați fișierul de configurare lizibil doar de către administratorul serviciului și procesul Synapse, după cum este necesar pentru implementarea dvs. Dacă gestionați Synapse prin containere sau o diagramă, plasați setările furnizorului în sursa de configurare acceptată, în loc să editați un fișier generat care va fi suprascris.

4. Opțional, configurați deconectarea de pe canalul din spate

În mod implicit, deconectarea de la un serviciu nu încheie neapărat sesiunea de browser a tuturor celorlalte servicii. Dacă doriți ca notificările de deconectare Keycloak să încheie sesiunea Synapse, activați-o backchannel_logout_enabled: truesub furnizorul Keycloak din Synapse și setați adresa URL de deconectare Backchannel a Keycloak la:

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

Acest lucru este opțional și depinde de politica de deconectare și de configurarea clientului. Testați ambele direcții de deconectare: deconectare Synapse și deconectare Keycloak. Nu presupuneți că deconectarea din Element încheie sesiunea Keycloak.

5. Reporniți și testați Synapse

Validați YAML-ul cu verificările de configurare ale implementării, apoi reporniți sau reîncărcați Synapse folosind metoda acceptată de configurația pachetului sau containerului. Examinați jurnalele Synapse pentru erori de descoperire OIDC, autentificare client, apel invers sau mapare a revendicărilor. Folosiți mai întâi un cont de testare și confirmați că ID-ul matricei și numele afișat sunt valorile așteptate.

Configurați Element Web

6. Păstrați SSO-ul opțional sau redirecționați automat

Odată ce Synapse anunță autentificarea OIDC, Element Web poate prezenta opțiunea de autentificare SSO. Setarea Element sso_redirect_optionscontrolează experiența browserului; nu configurează Keycloak și nu stochează secretul clientului. Adăugați o setare ca aceasta la setările oferite de Element Web config.jsondacă doriți ca vizitatorii neautentificați care sosesc pe pagina de bun venit sau de autentificare să fie direcționați către fluxul SSO disponibil:

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

Pentru o implementare care necesită cu adevărat conectare doar prin SSO, setați "immediate": truesă porniți SSO pentru toți utilizatorii neautentificați. Acest lucru poate face ca parola sau alte opțiuni de conectare să fie mai greu de accesat, așadar testați recuperarea și accesul de administrator înainte de a le impune. Dacă utilizatorii trebuie să aleagă între SSO și o altă metodă, lăsați redirecționarea automată dezactivată și testați dacă opțiunea SSO apare în fluxul de conectare.

Dacă Synapse utilizează serviciul de autentificare Matrix

MAS este un serviciu de autentificare separat și poate acționa ca și client OIDC pentru Keycloak. În această arhitectură, configurați URI-ul de redirecționare al Keycloak ca https://auth.example.com/upstream/callback/<provider-id>, unde ID-ul furnizorului se potrivește cu configurația MAS. Configurați furnizorul sub upstream_oauth2.providerselementul ; al MAS utilizează apoi fluxul de autentificare bazat pe MAS al serverului de domiciliu. Nu utilizați Synapse /_synapse/client/oidc/callbackpentru această conexiune în amonte. MAS necesită un furnizor OIDC care să accepte fluxul codului de autorizare. Formatul său de configurare, ID-ul furnizorului necesar și pașii de migrare sunt diferiți de . încorporat în Synapse oidc_providers.

Neînțelegeri frecvente și remedieri

• „Trebuie doar să schimb configurația Element.” Element controlează fluxul browserului, în timp ce Synapse sau MAS se ocupă de OIDC. Configurați mai întâi furnizorul corect de pe partea de server principal.
• „O autentificare Keycloak reușită dovedește că maparea contului este corectă.” Autentificarea poate reuși chiar dacă este selectată o revendicare localpart sau de profil greșită. Testați cu un utilizator care nu este de producție și verificați ID-ul matricei rezultat.
• „SSO dezactivează automat parolele și înregistrarea.” Aceste politici sunt controlate de serverul principal și de implementare. Examinați separat setările de conectare și înregistrare ale Synapse și confirmați politica aprobată.
• „Deconectarea de la Element mă deconectează de peste tot.” Sesiunile de browser pot rămâne active la Keycloak. Configurați și testați deconectarea prin back-channel dacă este necesară terminarea centralizată a sesiunii.

Listă de verificare

• Clientul Keycloak folosește fluxul de cod de autorizare, autentificarea clientului și apelul invers exact pentru Synapse sau MAS.
• Adresa URL a emitentului se potrivește cu metadatele de descoperire ale realm-ului, iar secretul clientului este stocat pe server.
• Synapse sau MAS pornește fără erori de configurare OIDC și expune metoda de conectare dorită.
• Un utilizator de test se poate conecta dintr-o sesiune nouă de browser, ajunge în contul Matrix așteptat și poate finaliza o sesiune Element normală.
• Comportamentul la deconectare, conturile existente, restricțiile de înregistrare și orice acces de administrator de rezervă corespund politicii dvs.

Referințe oficiale

• Ghidul OpenID Connect pentru Synapse v1.144, inclusiv clientul Keycloak și setările de apel invers
• Configurarea Element Web: Opțiuni de redirecționare SSO
• Serviciul de autentificare Matrix: configurarea unui furnizor SSO în amonte
• Ghid de administrare a serverului Keycloak 26.8.0