Cum se configurează Keycloak ca IDP pentru ownCloud Infinite Scale

Acest ghid conectează ownCloud Infinite Scale (oCIS) la Keycloak folosind OpenID Connect (OIDC), stratul de identitate construit pe OAuth 2.0. Keycloak autentifică utilizatorii; oCIS are încredere în identitatea semnată și în informațiile de acces pe care Keycloak le pune în dificultate. Conectarea bazată pe browser folosește redirecționări HTTPS, în timp ce oCIS trebuie, de asemenea, să ajungă la punctele finale ale cheilor de descoperire și semnare Keycloak.

Începând cu 6 octombrie 2026, documentația de administrare actuală a ownCloud descrie aceste setări în Infinite Scale 9.0. Exemplul oficial de implementare Keycloak este un punct de plecare util, dar fișierul Compose și exportul realm se pot modifica. Fixați versiunile de imagini compatibile și revizuiți fișierele pe care le implementați în loc să copiați orbește un exemplu neversionat.

Ce aveți nevoie înainte de a configura OIDC

Pregătiți adresa HTTPS publică pentru oCIS, cum ar fi https://cloud.example.com, și adresa HTTPS publică pentru Keycloak, cum ar fi https://sso.example.com. Ambele nume trebuie să fie rezolvate corect din browserele utilizatorilor. Serverul oCIS trebuie să poată accesa metadatele OIDC și cheile publice de semnare ale Keycloak. Dacă un proxy invers se adresează oricăruia dintre servicii, configurați numele său public de gazdă și anteturile redirecționate în mod consecvent.

• O implementare ownCloud Infinite Scale funcțională și acces de administrator la mediul său sau la configurația Compose.
• O zonă Keycloak funcțională și acces de administrator. O zonă este un spațiu de nume Keycloak pentru utilizatori, clienți, roluri și setări de identitate.
• Un certificat TLS în care browserul și serverul care validează certificatul TLS al Keycloak au încredere. Utilizarea în producție nu ar trebui să dezactiveze verificarea certificatului.
• O decizie privind potrivirea conturilor: conectarea utilizatorilor oCIS existenți la revendicări de identitate stabile sau activarea furnizării de conturi la prima conectare cu backend-ul de utilizator cu drepturi de scriere necesare.

1. Găsiți emitentul exact al Keycloak-ului

În Keycloak, emitentul OIDC este în mod normal adresa URL a realm-ului, nu adresa URL a consolei de administrare și nici adresa URL a documentului de descoperire. Pentru un realm numit team, poate arăta astfel https://sso.example.com/realms/team. Instalările sau implementările mai vechi cu un prefix de cale pot diferi, așadar nu construiți valoarea din memorie. Deschideți documentul de descoperire al realm-ului la https://sso.example.com/realms/team/.well-known/openid-configurationși copiați exact valoarea issuerproprietății sale.

De pe un server care poate accesa Keycloak, puteți inspecta documentul cu:

curl -fsS https://sso.example.com/realms/team/.well-known/openid-configuration

Verificați dacă emitentul returnat utilizează aceeași schemă, gazdă, cale și nume de domeniu pe care le veți configura în oCIS. OpenID Connect validează exact identitatea emitentului; o nepotrivire a numelui de gazdă proxy invers sau o bară oblică suplimentară pot întrerupe autentificarea.

2. Înregistrați un client OIDC pentru ownCloud Web

Un client este sistemul de înregistrare a aplicației utilizat de Keycloak pentru a decide ce serviciu poate solicita autentificare. Creați sau adaptați un client OpenID Connect în domeniul utilizat pentru oCIS. Folosiți un ID de client, cum ar fi web, sau o valoare personalizată și asigurați-vă că se potrivește cu WEB_OIDC_CLIENT_IDvaloarea din oCIS. Exemplul oficial ownCloud folosește webca implicit.

Pentru un client bazat pe browser, utilizați fluxul standard al codului de autorizare și o configurație public-client consistentă cu exemplul oficial de domeniu. Introduceți exact modelele de redirecționare HTTPS și de redirecționare post-deconectare necesare implementării dvs. Un model de nume de gazdă restrâns, cum ar fi https://cloud.example.com/*este mai ușor de auditat decât un wildcard larg pe fiecare gazdă. Adăugați doar originile web de care are nevoie implementarea dvs. Nu creați un secret de client pentru un client de browser public și apoi să îl încorporați în configurația frontend.

3. Verificați revendicările și domeniile de aplicare

Revendicările OIDC sunt atribute de identitate transportate într-un token sau returnate de endpoint-ul user-info. Cel puțin, alegeți cu atenție revendicarea numelui de utilizator. Proxy-ul ownCloud are implicit valoarea preferred_usernamepentru rezolvarea unui utilizator, iar exemplul Keycloak configurează clientul web cu domenii de aplicare standard pentru profil și e-mail. Verificați dacă propriul dvs. domeniu returnează de fapt revendicările pe care le utilizați; disponibilitatea revendicărilor depinde de domeniile de aplicare ale clientului și de mapatoarele de protocoale.

Pentru conturile existente, revendicarea configurată trebuie să fie mapată la atributul de utilizator ownCloud stabil corespunzător. Un nume de utilizator sau o adresă de e-mail modificată poate cauza probleme de potrivire a contului dacă o utilizați ca identificator permanent. Revendicarea subeste garantată ca fiind unică și stabilă per furnizor de identitate, dar este posibil să nu corespundă unui nume de utilizator preexistent. Testați maparea contului cu un cont non-administrator înainte de a deschide accesul tuturor utilizatorilor.

4. Indicați Scala Infinită către Keycloak

Setați următoarele valori în mediu pentru implementarea oCIS. Exemplul presupune HTTPS și o zonă Keycloak la /realms/team. Folosiți propriile adrese URL. Acest bloc în stil YAML este ilustrativ; Docker Compose, Kubernetes, systemd și alte metode de implementare exprimă variabilele de mediu în mod diferit.

OCIS_URL: https://cloud.example.com
OCIS_OIDC_ISSUER: https://sso.example.com/realms/team
PROXY_OIDC_REWRITE_WELLKNOWN: "true"
WEB_OIDC_CLIENT_ID: web
PROXY_USER_OIDC_CLAIM: preferred_username
OCIS_EXCLUDE_RUN_SERVICES: idp

OCIS_OIDC_ISSUERselectează furnizorul de identitate extern. PROXY_OIDC_REWRITE_WELLKNOWN=trueface ca proxy-ul să rescrie endpoint-ul de descoperire OpenID Connect către emitentul configurat; ownCloud documentează acest lucru ca fiind necesar pentru ca clienții săi desktop și mobili să descopere furnizorul. WEB_OIDC_CLIENT_IDtrebuie să se potrivească cu clientul Keycloak. Excluderea idpurmează exemplul Keycloak al ownCloud, astfel încât furnizorul încorporat să nu fie pornit ca furnizor de conectare activ.

Dacă doriți ca oCIS să creeze conturi la prima conectare reușită, setați PROXY_AUTOPROVISION_ACCOUNTS=trueși configurați serviciul Graph cu un backend de utilizator cu acces la scriere. Setați PROXY_USER_OIDC_CLAIMși PROXY_AUTOPROVISION_CLAIM_USERNAMEpentru aceeași revendicare; pentru atributul nume de utilizator, documente ownCloud PROXY_USER_CS3_CLAIM=usernamepentru acest flux. Provisionarea automată este opțională și trebuie testată separat de autentificare. Nu o activați decât dacă revendicările primite sunt unice și mapate conform intenției.

5. Permiteți furnizorul de identitate în politica de securitate a conținutului

Infinite Scale utilizează o Politică de Securitate a Conținutului (CSP) pentru a controla originile externe pe care clientul său web le poate contacta. Documentația ownCloud precizează că un furnizor de identitate extern, cum ar fi Keycloak, necesită o definiție CSP adecvată. Dacă apare butonul de conectare, dar browserul blochează o solicitare, verificați consola browserului pentru erori CSP. Configurați politica prin intermediul acesteia PROXY_CSP_CONFIG_FILE_LOCATIONși permiteți doar originea Keycloak și directivele de care are nevoie implementarea. Reporniți proxy-ul sau implementarea după modificarea fișierului. Nu rezolvați o problemă de conexiune permițând fiecare origine.

6. Reporniți și verificați fluxul complet

Aplicați modificările de mediu și reporniți implementarea oCIS folosind metoda pe care o utilizați deja pentru a o gestiona. Nu există o comandă universală de repornire: un proiect Compose, o sarcină de lucru Kubernetes și un serviciu systemd au controale diferite. Apoi verificați fiecare verigă din lanț:

1. Deschideți adresa URL de descoperire Keycloak și confirmați că returnează JSON cu issuer, authorization_endpoint, token_endpoint, și jwks_uri.
2. Deschideți adresa URL web ownCloud într-o fereastră privată a browserului. Confirmați că browserul este redirecționat către domeniul Keycloak așteptat.
3. Conectați-vă cu un cont de test și confirmați că browserul returnează același nume de gazdă ownCloud fără o buclă de redirecționare.
4. Verificați dacă utilizatorul vizat — nu un duplicat nou creat — apare în Infinite Scale și poate accesa doar resursele așteptate.
5. Testați deconectarea, apoi repetați cu un al doilea cont. Dacă se află în domeniul de aplicare al programului, testați separat detectarea și conectarea acestora.

Eșecuri comune și ce înseamnă acestea de obicei

Listă de verificare a producției

• Versiunile ownCloud și Keycloak testate cu pin-uri în loc să se bazeze pe o latestetichetă flotantă.
• Folosește HTTPS atât pentru serviciile publice, cât și pentru verificarea certificatelor. ownCloud documentează suprascrierea nesigură a TLS ca fiind nepotrivită pentru producție.
• Protejați acreditările de administrator Keycloak, faceți copii de rezervă ale bazei de date și ale configurației realmului Keycloak și restricționați accesul administratorului Keycloak.
• Păstrați URI-urile de redirecționare și originile web limitate la numele de gazdă ownCloud reale.
• Documentați revendicarea identificatorului ales și consecințele schimbării numelor de utilizator, a numelor de domeniu, a adreselor URL ale emitenților sau a ID-urilor de client.
• Testați accesul la recuperare înainte de a schimba o instanță de producție și păstrați o revenire planificată a configurației anterioare.

Referințe oficiale

• Configurarea serviciului proxy ownCloud Infinite Scale 9.0
• Ghid de implementare exemplu ownCloud Keycloak
• Fișiere oficiale de implementare ownCloud ocis_keycloak
• Ghid de administrare a serverului Keycloak 26.8
• Aspecte de securitate la scalare infinită ale ownCloud