Come configurare l'autenticazione a due fattori in ownCloud Infinite Scale

Per richiedere l'autenticazione a due fattori (2FA) per gli accessi a ownCloud Infinite Scale, è necessario configurarla nel provider di identità (IDP) OpenID Connect utilizzato per autenticare gli utenti. Per molte implementazioni, ciò significa abilitare le password monouso basate sul tempo (TOTP) in Keycloak e richiedere agli utenti di registrarsi prima di poter completare l'accesso. Infinite Scale non offre una schermata di registrazione TOTP generica. Il suo IDP integrato è minimale; ownCloud consiglia di utilizzare un provider OpenID Connect esterno per esigenze di identità più ampie e la sua documentazione indica Keycloak come soluzione per la 2FA.

Esempio ipotetico: Northstar Design è un'azienda fittizia di 40 persone con ownCloud Infinite Scale già connesso a un realm Keycloak denominato files. Attualmente il personale accede con una password. L'amministratore desidera che registrino un'app di autenticazione e utilizzino un codice al successivo accesso. Questo esempio è puramente illustrativo e non rappresenta un'installazione o un test reale. I passaggi seguenti presuppongono che Keycloak sia già l'IDP utilizzato da Infinite Scale; in caso contrario, seguire prima le istruzioni ufficiali per la connessione dei due servizi.

Le immagini dell'interfaccia in questa guida sono esempi concettuali e non screenshot di un sistema Northstar o ownCloud in funzione. La terminologia e il layout dei menu possono variare a seconda della versione di Keycloak. Le istruzioni sono state verificate rispetto alla documentazione di ownCloud Infinite Scale 8.2 e alla Guida all'amministrazione del server Keycloak 26.8 il 6 ottobre 2026.

Quali modifiche apporta l'autenticazione a due fattori (2FA) in un'implementazione su scala infinita?

OpenID Connect (OIDC) è il protocollo di accesso che consente a Infinite Scale di affidarsi a un IDP (Identity Provider) anziché autenticare ogni singola password. Keycloak richiede la credenziale principale e, quando il flusso di autenticazione lo richiede, un secondo fattore come il TOTP (Time To Password). Infinite Scale riceve quindi l'autenticazione OIDC risultante. Un TOTP è un codice temporaneo generato da una chiave segreta condivisa e dall'ora corrente; un'app di autenticazione memorizza la chiave segreta quando un utente scansiona il codice QR di registrazione.

Questa separazione è importante. L'impostazione di una policy OTP in Keycloak modifica il modo in cui Keycloak autentica gli utenti. L'impostazione di un'opzione MFA di ownCloud non registra un telefono né crea una credenziale TOTP. In particolare, l' OCIS_MFA_ENABLEDopzione di ownCloud serve per l'autenticazione a più fattori su percorsi protetti specifici quando l'IDP supporta la rivendicazione ACR (Authentication Context Class Reference) di OpenID Connect. Non si tratta di un'opzione che aggiunge una richiesta TOTP universale a ogni accesso.

Prima di cambiare il regno

• Verifica quale IDP e quale realm vengono effettivamente utilizzati dai client Infinite Scale in produzione. Confronta l'ID emittente e l'ID client OIDC con la configurazione di distribuzione, anziché fare supposizioni basandoti sull'indirizzo del browser.
• È necessario disporre di un account amministratore per il realm Keycloak corretto, di un'app di autenticazione supportata per ciascun utente e di una procedura di recupero per gli utenti che smarriscono un dispositivo.
• Verifica che la pagina di accesso di Keycloak e Infinite Scale siano disponibili tramite HTTPS con certificati validi. Mantieni aperta una sessione amministratore esistente mentre apporti modifiche all'autenticazione ed esegui prima un test con un account non amministratore.
• Inventariare tutti i percorsi di accesso. Il flusso del browser controlla l'autenticazione OIDC basata sul browser; le credenziali API, gli account di servizio, le password delle app o altri flussi di autenticazione possono essere gestiti separatamente.

1. Conferma che Infinite Scale utilizza Keycloak

Nell'esempio Northstar, l'amministratore conferma che il client web è già stato reindirizzato al filesrealm all'indirizzo https://login.example.test/realms/files. L'esempio di implementazione di ownCloud utilizza impostazioni come OCIS_OIDC_ISSUER, WEB_OIDC_CLIENT_ID, e, nella sua configurazione Keycloak, PROXY_OIDC_REWRITE_WELLKNOWN. Si tratta di valori di configurazione dell'implementazione, non di campi che gli utenti ordinari modificano nell'interfaccia web di Infinite Scale.

Se la tua istanza utilizza ancora l'IDP integrato, pianifica l'integrazione di Keycloak separatamente prima di imporre l'OTP. La connessione di un IDP esterno implica più del semplice inserimento di un URL dell'emittente: la registrazione del client, la configurazione del reindirizzamento e dell'origine web, le richieste di token, HTTPS e i client desktop o mobili in uso devono essere compatibili. Utilizza l'esempio di implementazione di Keycloak gestito da ownCloud come punto di partenza per la tua versione e topologia specifiche.

2. Seleziona una policy OTP basata sul tempo in Keycloak

Apri la sezione File nella Console di amministrazione di Keycloak e vai su Autenticazione , quindi su Criteri e infine su Criteri OTP . Scegli un criterio basato sul tempo (TOTP) per le app di autenticazione. Keycloak supporta anche HOTP basato su contatore, ma TOTP è generalmente più adatto alle app di autenticazione per dispositivi mobili perché i codici cambiano nel tempo.

Prima dell'implementazione, rivedi la policy. Keycloak espone impostazioni quali l'algoritmo di hash, la lunghezza del codice, la finestra di tolleranza alla deriva dell'orologio, il periodo di validità del token e la possibilità di riutilizzare un codice. Inizia con i valori supportati dagli autenticatori utilizzati dai tuoi utenti. Una finestra di tolleranza più ampia può aiutare a compensare la deriva dell'orologio, ma estende anche l'intervallo in cui un codice può essere accettato. Mantieni l'orologio del server sincronizzato ed evita di ampliare tale finestra come sostituto per una corretta sincronizzazione dell'ora.

3. Richiedere la registrazione tramite OTP per i nuovi utenti

In Autenticazione > Azioni richieste , assicurati che Configura OTP sia abilitato e contrassegnalo come azione predefinita. La documentazione di Keycloak afferma che un'azione richiesta predefinita viene applicata quando un nuovo utente effettua l'accesso per la prima volta. Questo crea un requisito di registrazione; l'utente deve comunque completare la configurazione prima che venga generata una credenziale TOTP.

Verifica anche il flusso di autenticazione del browser. Nel flusso standard di Keycloak per browser, il sottoflusso condizionale di autenticazione a due fattori (2FA) richiede l'OTP (One-Time Password) quando l'utente ha già configurato una credenziale OTP. Se agli utenti non è richiesto di configurare l'OTP, possono procedere senza la richiesta di autenticazione a due fattori. Mantieni il normale passaggio di password o di autenticazione a due fattori e testa attentamente il flusso prima di associarne uno personalizzato. Le modifiche al flusso di autenticazione influiscono sull'intero realm e, se configurate in modo errato, possono bloccare l'accesso agli amministratori.

4. Aggiungere il requisito di registrazione agli utenti esistenti

Un'azione predefinita non è retroattiva per gli account già esistenti. Per il personale attuale di Northstar, l'amministratore accede a ciascun utente nel dominio Keycloak e aggiunge "Configura OTP" tra le azioni richieste per quell'utente, quindi salva la modifica. Keycloak documenta anche un'opzione nella scheda Credenziali di un utente per inviare un'e-mail di reimpostazione delle credenziali che indirizza l'utente alla configurazione dell'OTP. Scegli il metodo più adatto al tuo processo di gestione degli account e verifica che gli utenti possano ricevere l'e-mail se lo utilizzi.

Per directory di grandi dimensioni, pianifica un processo di massa controllato utilizzando un'interfaccia amministrativa Keycloak supportata o l'automazione. Non dare per scontato che l'attivazione dell'azione predefinita registri tutti gli utenti. Crea un utente di prova e verifica il comportamento previsto al primo accesso prima di applicare la policy su larga scala.

5. Ogni utente dovrà registrare un autenticatore

Quando Alex, un dipendente immaginario di Northstar, accede nuovamente a ownCloud e viene reindirizzato a Keycloak, Keycloak gli chiede di configurare l'OTP. Alex apre un'app di autenticazione, scansiona il codice QR mostrato da Keycloak e inserisce il codice visualizzato nell'app per confermare la registrazione. Il codice QR contiene il segreto TOTP, quindi gli utenti devono trattarlo come una credenziale: non inviarlo a un amministratore tramite e-mail, non salvarlo in un ticket condiviso e non scansionarlo con un dispositivo non attendibile.

Se l'app non riesce a scansionare il codice, la pagina di configurazione di Keycloak potrebbe offrire la chiave sottostante come inserimento manuale. Gli utenti devono memorizzare tale chiave esclusivamente nell'autenticatore. Devono completare la procedura di verifica prima di chiudere la pagina di configurazione. Un codice che non supera la convalida potrebbe essere obsoleto, digitato in modo errato o generato da un'app con un orologio del dispositivo non corretto.

6. Preparare il ripristino prima di applicare la politica

Gli utenti hanno bisogno di un modo per recuperare l'accesso in caso di smarrimento, sostituzione o formattazione del telefono. Keycloak 26.8 documenta i codici di autenticazione di recupero come credenziale aggiuntiva che può essere abilitata e aggiunta come alternativa nel flusso del browser. Se la versione di Keycloak e il realm in uso supportano questa funzionalità, abilitatela e testatela attentamente. Gli utenti devono conservare i codici di recupero in un gestore di password approvato o in un'altra posizione offline protetta e trattare ciascun codice come riservato. Non memorizzarli nella stessa app del telefono che contiene il codice TOTP.

Se i codici di ripristino non sono abilitati nel tuo dominio, documenta una procedura di ripristino guidata dall'amministratore. Richiedi la verifica dell'identità prima di reimpostare o rimuovere una credenziale OTP. Mantieni un account amministratore di emergenza con una procedura separata e rigorosamente controllata, in modo che un problema di registrazione utente non si trasformi in un blocco dell'intero dominio.

7. Verifica il percorso di accesso completo a ownCloud

Dopo la registrazione, disconnettiti dall'account di prova e accedi nuovamente all'indirizzo Infinite Scale standard. Verifica che il browser raggiunga il realm Keycloak previsto, accetti la password dell'account, richieda il codice temporaneo e reindirizzi l'utente a ownCloud dopo l'autenticazione. Dopodiché, testa i client desktop e mobile supportati, i link condivisi e tutti gli strumenti operativi che si basano sullo stesso provider di identità.

Un test del browser andato a buon fine non dimostra che ogni client o protocollo utilizzi lo stesso flusso. Il flusso del browser di Keycloak potrebbe non coprire un flusso di concessione diretta separato e una sessione Single Sign-On (SSO) di Keycloak esistente può essere utilizzata per un successivo accesso a ownCloud senza mostrare un'ulteriore richiesta di OTP. Questo è un normale riutilizzo della sessione, non la prova che il fattore di autenticazione sia difettoso. Se la policy richiede un nuovo fattore di autenticazione più frequentemente, è opportuno rivedere le impostazioni SSO e del livello di autenticazione di Keycloak nell'ambito di una policy di sessione specifica.

Opzionale: richiedere l'autenticazione a più fattori solo per i percorsi protetti

Alcune implementazioni richiedono un secondo fattore solo quando gli utenti aprono una risorsa sensibile. Infinite Scale supporta l'autenticazione a più fattori a livello di percorso tramite attestazioni OIDC ACR. Nella documentazione 8.2, OCIS_MFA_ENABLEDviene abilitata l'applicazione e OCIS_MFA_AUTH_LEVEL_NAMESspecificato il livello ACR che indica l'autenticazione a più fattori (MFA). L'IDP deve supportare l'autenticazione a più fattori ed emettere il valore ACR corrispondente nel token. Keycloak dispone di una configurazione per il livello di autenticazione e l'ACR per questo modello, ma il suo flusso, il livello richiesto e la mappatura del token devono corrispondere al valore configurato in Infinite Scale.

OCIS_MFA_ENABLED=true
OCIS_MFA_AUTH_LEVEL_NAMES=advanced

Questo esempio è solo un punto di partenza: utilizzarlo advancedsolo se Keycloak è effettivamente configurato per restituire quel valore ACR dopo il fattore richiesto. Se viene richiesta una rotta protetta senza il livello necessario, Infinite Scale può negare l'accesso e restituire una risposta 403 con un'intestazione X-OCIS-MFA-Required. L'autenticazione a livello di rotta è diversa dalla richiesta di TOTP durante ogni nuova autenticazione del browser Keycloak.

Problemi comuni e relative soluzioni

Riferimenti ufficiali

• ownCloud Infinite Scale 8.2 Aspetti di sicurezza — Linee guida OIDC per i provider di identità e raccomandazione di Keycloak.
• Configurazione del servizio proxy di ownCloud Infinite Scale 8.2 : attestazioni OIDC, step-up ACR, variabili MFA e comportamento del percorso protetto.
• Esempio di implementazione di Keycloak di ownCloud : configurazione di esempio aggiornata per la connessione tra Infinite Scale e Keycloak.
• Guida all'amministrazione di Keycloak Server 26.8 — Politiche OTP, azioni richieste, flussi del browser, codici di recupero e livelli di autenticazione.