Per il single sign-on Nextcloud offre due app: SSO & SAML authentication (user_saml) per SAML 2.0 e OpenID Connect user backend (user_oidc) per OIDC. Entrambe funzionano bene — a patto che Nextcloud, reverse proxy e identity provider abbiano la stessa visione di URL, ora e ID utente. Quasi ogni ticket SSO si riconduce a uno di questi tre punti.
Prima di tutto: conoscere l'uscita di emergenza
Prima di toccare la configurazione SSO, bisogna sapere come entrare senza SSO. Con https://cloud.example.com/login?direct=1 Nextcloud mostra il classico modulo di login, così un admin locale può accedere anche quando l'identity provider non risponde. Provarlo prima evita molto stress nel momento critico.
1. Loop di redirect dietro il reverse proxy
Sintomo: dopo il login sull'IdP il browser rimbalza all'infinito tra Nextcloud e IdP, oppure l'IdP segnala un URL di ritorno non valido.
Causa: Nextcloud gira dietro un proxy che termina TLS e quindi genera URL http:// o un hostname sbagliato. L'Assertion Consumer Service URL (SAML) o il redirect URI (OIDC) non corrisponde più a quello registrato sull'IdP.
Soluzione: nel config.php impostare overwriteprotocol su https, overwrite.cli.url sull'URL pubblico e inserire il proxy in trusted_proxies. Poi verificare gli endpoint attesi: per SAML /apps/user_saml/saml/acs (metadati su /apps/user_saml/saml/metadata), per OIDC /apps/user_oidc/code.
2. Orologi sfasati
Sintomo: errori “assertion expired” o “not yet valid”, sporadici o continui, anche se la configurazione è giusta.
Causa: le assertion SAML e i token OIDC hanno finestre di validità strette. Bastano pochi minuti di differenza tra server Nextcloud e IdP.
Soluzione: attivare NTP su entrambi i lati e controllare con timedatectl. Nei container conta l'orologio dell'host.
3. Certificato dell'IdP rinnovato
Sintomo: da un giorno all'altro ogni login fallisce con un errore di firma.
Causa: l'IdP ha cambiato il certificato di firma, ma in Nextcloud c'è ancora il vecchio certificato X.509.
Soluzione: copiare il certificato attuale dai metadati dell'IdP. Molti IdP pubblicano il nuovo certificato prima del cambio: chi conosce le due date pianifica la sostituzione invece di scoprirla.
4. UID mappato sull'attributo sbagliato
Sintomo: dopo un cambio di nome o di e-mail un utente accede e trova un account nuovo e vuoto.
Causa: come ID univoco è stato mappato un attributo che può cambiare, per esempio l'indirizzo e-mail. Quando cambia, Nextcloud crea un nuovo account.
Soluzione: usare fin dall'inizio un attributo immutabile — il claim sub per OIDC, un ID fisso come l'object ID della directory per SAML. Cambiare il mapping in seguito è una migrazione, non un'impostazione: prima mettere al sicuro dati e condivisioni degli account coinvolti.
5. Account inesistente — o creato due volte
Sintomo: “Account not provisioned”, oppure un login senza accesso ai dati esistenti, quando sono in gioco anche LDAP o account locali.
Causa: non è chiaro quale backend fornisce gli utenti. Con SAML Nextcloud può creare gli account da sé oppure accettare solo utenti già presenti in un altro backend (es. LDAP).
Soluzione: stabilire un'unica fonte di verità e impostare consapevolmente l'opzione “consenti solo account esistenti”. L'UID mappato deve corrispondere esattamente all'UID dell'altro backend — maiuscole e minuscole comprese.
6. OIDC: provider non raggiungibile
Sintomo: errore nel recupero dell'URL di discovery quando si crea il provider o durante il login.
Causa: è il server Nextcloud stesso a dover raggiungere /.well-known/openid-configuration dell'IdP. Per impostazione predefinita Nextcloud blocca gli IdP interni con IP privati, e firewall o proxy senza eccezioni fanno il resto.
Soluzione: testare dal server con curl. Per un IdP in rete interna impostare 'allow_local_remote_servers' => true nel config.php — in modo mirato e documentato, perché l'opzione riguarda anche altre funzioni. I provider si gestiscono anche da script con occ user_oidc:provider.
7. I gruppi non arrivano
Sintomo: il login funziona, ma mancano le condivisioni di gruppo o i diritti di amministratore.
Causa: l'IdP non invia un claim o un attributo dei gruppi, oppure il nome nel mapping è sbagliato.
Soluzione: con un add-on del browser come SAML-tracer (o con l'ID token decodificato per OIDC) vedere cosa arriva davvero e adattare il mapping a quello — non il contrario.
8. Il logout non esce ovunque
Sintomo: dopo il logout da Nextcloud, al clic successivo si è subito di nuovo dentro.
Causa: è terminata solo la sessione di Nextcloud, quella sull'IdP è ancora attiva. È il comportamento normale del SSO, ma viene spesso segnalato come bug.
Soluzione: configurare il single logout o l'URL di logout dell'IdP se serve un'uscita completa — e spiegare agli utenti cosa significa “esci” in un ambiente SSO.
Checklist per il prossimo ticket SSO
- Login di emergenza con
/login?direct=1provato? - URL pubblico,
overwriteprotocoletrusted_proxiescorretti? - ACS URL o redirect URI sull'IdP identico a quello di Nextcloud?
- Ora sincronizzata su Nextcloud e IdP?
- Certificato attuale dell'IdP inserito?
- UID mappato su un attributo immutabile?
- Attributi/claim reali verificati con SAML-tracer o un decoder di token?
- Per l'analisi,
loglevel0 temporaneo e lettura dinextcloud.log— poi ripristinare.
La maggior parte dei problemi SSO non sono bug, ma due sistemi che non si accordano su un dettaglio. Chi controlla con metodo URL, ora e ID trova la causa in minuti invece che in ore.