Come configurare Keycloak come IDP per ownCloud Infinite Scale

Questa guida collega ownCloud Infinite Scale (oCIS) a Keycloak utilizzando OpenID Connect (OIDC), il livello di identità basato su OAuth 2.0. Keycloak autentica gli utenti; oCIS si fida dell'identità firmata e delle informazioni di accesso rilasciate da Keycloak. L'accesso tramite browser utilizza reindirizzamenti HTTPS, mentre oCIS deve anche raggiungere gli endpoint di rilevamento e di firma delle chiavi di Keycloak.

Al 6 ottobre 2026, la documentazione di amministrazione di ownCloud descrive queste impostazioni in Infinite Scale 9.0. L'esempio di distribuzione ufficiale di Keycloak è un utile punto di partenza, ma il file Compose e l'esportazione del realm possono cambiare. Assicurati di utilizzare versioni di immagini compatibili e rivedi i file che distribuisci, invece di copiare ciecamente un esempio senza versione.

Cosa serve prima di configurare OIDC

Preparare l'indirizzo HTTPS pubblico per oCIS, ad esempio https://cloud.example.com, e l'indirizzo HTTPS pubblico per Keycloak, ad esempio https://sso.example.com. Entrambi i nomi devono essere risolvibili correttamente dai browser degli utenti. Il server oCIS deve inoltre essere in grado di raggiungere i metadati OIDC e le chiavi di firma pubbliche di Keycloak. Se un proxy inverso funge da front-end per uno dei due servizi, configurare in modo coerente il suo hostname pubblico e le intestazioni inoltrate.

• Un'implementazione ownCloud Infinite Scale funzionante e l'accesso amministrativo al relativo ambiente o alla configurazione Compose.
• Un realm Keycloak funzionante e accesso amministrativo. Un realm è uno spazio dei nomi Keycloak per utenti, client, ruoli e impostazioni di identità.
• Un certificato TLS riconosciuto come attendibile dal browser e dal server che convalida il certificato TLS di Keycloak. In ambiente di produzione, la verifica del certificato non deve essere disabilitata.
• Una decisione relativa all'abbinamento degli account: connettere gli utenti oCIS esistenti a rivendicazioni di identità stabili oppure abilitare il provisioning dell'account al primo accesso con il backend utente con permessi di scrittura necessari.

1. Trova l'esatto emittente di Keycloak

In Keycloak, l'emittente OIDC è normalmente l'URL del realm, non l'URL della console di amministrazione né l'URL del documento di discovery. Per un realm denominato team, potrebbe apparire come https://sso.example.com/realms/team. Le installazioni o le distribuzioni più vecchie con un prefisso di percorso potrebbero essere diverse, quindi non costruire il valore a memoria. Apri il documento di discovery del realm all'indirizzo https://sso.example.com/realms/team/.well-known/openid-configuratione copia esattamente il valore della sua issuerproprietà.

Da un server in grado di raggiungere Keycloak, è possibile esaminare il documento con:

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

Verifica che l'emittente restituito utilizzi lo stesso schema, host, percorso e nome di realm che configurerai in oCIS. OpenID Connect convalida l'identità dell'emittente in modo preciso; una mancata corrispondenza del nome host del proxy inverso o una barra aggiuntiva possono impedire l'accesso.

2. Registra un client OIDC per ownCloud Web

Un client è la registrazione dell'applicazione che Keycloak utilizza per decidere quale servizio può richiedere l'accesso. Crea o adatta un client OpenID Connect nel realm utilizzato per oCIS. Utilizza un ID client come web, o un valore personalizzato, e assicurati che corrisponda al WEB_OIDC_CLIENT_IDvalore in oCIS. L'esempio ufficiale di ownCloud utilizza webcome predefinito.

Per un client basato su browser, utilizzare il flusso standard del codice di autorizzazione e una configurazione client pubblica coerente con il realm di esempio ufficiale. Inserire i modelli di reindirizzamento HTTPS e di reindirizzamento post-logout esatti richiesti dalla propria implementazione. Un modello di nome host specifico, come ad esempio, https://cloud.example.com/*è più facile da controllare rispetto a un carattere jolly generico utilizzato su tutti gli host. Aggiungere solo le origini web necessarie all'implementazione. Non creare un segreto client per un client browser pubblico e poi incorporarlo nella configurazione frontend.

3. Verificare le affermazioni e gli ambiti

Le attestazioni OIDC sono attributi di identità contenuti in un token o restituiti dall'endpoint user-info. Come minimo, scegli attentamente l'attestazione username. Il proxy ownCloud utilizza di default l'impostazione predefinita preferred_usernameper la risoluzione di un utente, e l'esempio di Keycloak configura il client web con ambiti standard di profilo ed email. Verifica che il tuo realm restituisca effettivamente le attestazioni che utilizzi; la disponibilità delle attestazioni dipende dagli ambiti client e dai mapper di protocollo.

Per gli account esistenti, la rivendicazione configurata deve corrispondere all'attributo utente stabile di ownCloud corrispondente. Un nome utente o un indirizzo email modificati possono causare problemi di corrispondenza dell'account se vengono utilizzati come identificativo permanente. La subrivendicazione è garantita come univoca e stabile per ciascun provider di identità, ma potrebbe non corrispondere a un nome utente preesistente. Prima di consentire l'accesso a tutti gli utenti, testare la mappatura dell'account con un account non amministratore.

4. Puntare Scala Infinita a Keycloak

Imposta i seguenti valori nell'ambiente per la distribuzione oCIS. L'esempio presuppone HTTPS e un realm Keycloak all'indirizzo /realms/team. Utilizza i tuoi URL. Questo blocco in stile YAML è a scopo illustrativo; Docker Compose, Kubernetes, systemd e altri metodi di distribuzione esprimono le variabili d'ambiente in modo diverso.

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_ISSUERSeleziona il provider di identità esterno. PROXY_OIDC_REWRITE_WELLKNOWN=trueFa sì che il proxy riscriva l'endpoint di rilevamento OpenID Connect all'emittente configurato; ownCloud documenta questo come necessario affinché i suoi client desktop e mobili possano rilevare il provider. WEB_OIDC_CLIENT_IDDeve corrispondere al client Keycloak. L'esclusione idpsegue l'esempio Keycloak di ownCloud in modo che il provider incorporato non venga avviato come provider di accesso attivo.

Se si desidera che oCIS crei account al primo accesso riuscito, impostare PROXY_AUTOPROVISION_ACCOUNTS=truee configurare il servizio Graph con un backend utente abilitato alla scrittura. Impostare PROXY_USER_OIDC_CLAIMe PROXY_AUTOPROVISION_CLAIM_USERNAMEsullo stesso claim; per l'attributo username, ownCloud documenta PROXY_USER_CS3_CLAIM=usernameper questo flusso. Il provisioning automatico è facoltativo e dovrebbe essere testato separatamente dall'autenticazione. Non attivarlo a meno che i claim in entrata non siano univoci e mappati come previsto.

5. Consentire il provider di identità nella policy di sicurezza dei contenuti

Infinite Scale utilizza una Content Security Policy (CSP) per controllare quali origini esterne il suo client web può contattare. La documentazione di ownCloud afferma che un provider di identità esterno come Keycloak richiede una definizione CSP appropriata. Se il pulsante di accesso viene visualizzato ma il browser blocca la richiesta, controlla la console del browser per eventuali errori CSP. Configura la policy PROXY_CSP_CONFIG_FILE_LOCATIONe consenti solo l'origine Keycloak e le direttive necessarie per la tua implementazione. Riavvia il proxy o l'implementazione dopo aver modificato il file. Non risolvere un problema di connessione consentendo tutte le origini.

6. Riavviare e verificare il flusso completo

Applica le modifiche all'ambiente e riavvia il deployment oCIS utilizzando il metodo che già usi per gestirlo. Non esiste un comando di riavvio universale: un progetto Compose, un carico di lavoro Kubernetes e un servizio systemd hanno controlli diversi. Quindi controlla ogni anello della catena:

1. Apri l'URL di rilevamento di Keycloak e verifica che restituisca un JSON con un issuer, authorization_endpoint, token_endpoint, e jwks_uri.
2. Apri l'URL web di ownCloud in una finestra di navigazione in incognito. Verifica che il browser venga reindirizzato al realm di Keycloak previsto.
3. Accedi con un account di prova e verifica che il browser restituisca lo stesso hostname di ownCloud senza un loop di reindirizzamento.
4. Verifica che l'utente previsto, e non un duplicato appena creato, sia presente in Infinite Scale e che possa accedere solo alle risorse previste.
5. Esegui un test di disconnessione, quindi ripeti l'operazione con un secondo account. Se sono inclusi client desktop o mobili, testa separatamente la loro individuazione e l'accesso.

Guasti comuni e il loro significato di solito

Lista di controllo della produzione

• Sono state testate le versioni di ownCloud e Keycloak anziché affidarsi a un latesttag fluttuante.
• Utilizza HTTPS sia per i servizi pubblici che per la verifica dei certificati. La documentazione di ownCloud indica che l'override TLS non sicuro non è adatto agli ambienti di produzione.
• Proteggi le credenziali di amministratore di Keycloak, esegui il backup del database e della configurazione del realm di Keycloak e limita l'accesso amministrativo a Keycloak.
• Limitare gli URI di reindirizzamento e le origini web ai nomi host effettivi di ownCloud.
• Documentare l'identificativo scelto e le conseguenze della modifica di nomi utente, nomi di dominio, URL dell'emittente o ID client.
• Prima di passare a un'istanza di produzione, verifica l'accesso di ripristino e mantieni un piano di ripristino della configurazione precedente.

Riferimenti ufficiali

• Configurazione del servizio proxy di ownCloud Infinite Scale 9.0
• Esempio di guida per la distribuzione di Keycloak su ownCloud
• File di distribuzione ufficiali di ownCloud ocis_keycloak
• Guida all'amministrazione del server Keycloak 26.8
• Aspetti di sicurezza di ownCloud Infinite Scale.