Risolvere l'errore "Token non valido" di ONLYOFFICE in Nextcloud

Se Nextcloud segnala "Token non valido" durante la connessione a ONLYOFFICE Docs, assicurati che il segreto JWT del connettore corrisponda al segreto effettivamente utilizzato da Document Server. In ONLYOFFICE Docs 7.2 e versioni successive, la convalida JWT è attiva per impostazione predefinita e un segreto viene generato automaticamente; la modifica della sola impostazione di Nextcloud o la modifica del file di configurazione generato da un container Docker può causare la mancata sincronizzazione tra i due sistemi.

Mantieni JWT abilitato. Innanzitutto, identifica il segreto attivo e il tipo di distribuzione, aggiorna la configurazione corretta, quindi esegui il controllo della connessione del connettore. Il controllo dovrebbe segnalare una connessione riuscita; la semplice apertura di un editor del browser non dimostra che il download dei documenti e le callback funzionino correttamente.

Cosa ti dice l'errore?

JWT (JSON Web Token) è un token firmato utilizzato per verificare che una richiesta tra Nextcloud e ONLYOFFICE Docs sia attendibile. Il connettore firma le richieste con la sua chiave segreta configurata, mentre Document Server le convalida utilizzando la propria chiave segreta configurata. Se le chiavi segrete di firma differiscono, la firma del token non può essere convalidata e la richiesta viene rifiutata.

Le cause più comuni sono un segreto copiato da una vecchia installazione, un segreto generato automaticamente che non è mai stato inserito in Nextcloud, una variabile d'ambiente Docker modificata che non è stata applicata ricreando il container o valori di segreto incoerenti nella configurazione del Document Server. Anche un'intestazione JWT personalizzata può causare una mancata corrispondenza se il connettore e il Document Server non utilizzano lo stesso nome di intestazione.

Questo articolo tratta il problema della mancata corrispondenza JWT. Se l'errore indica invece che il server non è raggiungibile, che il certificato non è valido o che non è possibile scaricare un documento, è necessario esaminare separatamente gli indirizzi del server, il certificato TLS e il percorso di rete da Nextcloud al server dei documenti. La correzione del JWT non risolverà questi problemi.

1. Trova il segreto attivo del Document Server

Utilizza la configurazione del Document Server in esecuzione. Non dare per scontato che un segreto memorizzato da un container o server precedente sia ancora attivo.

• Linux: ispeziona /etc/onlyoffice/documentserver/local.json.
• Windows: ispeziona %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json.
• Docker: legge il segreto dal container in esecuzione. L'immagine ufficiale supporta anche la lettura del segreto di sessione con questo comando:

sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

Sostituisci <containerID>con il nome o l'ID effettivo del contenitore. Tratta il valore restituito come una credenziale: non incollarlo nei forum di supporto, negli screenshot o nei log pubblici.

In local.json, confronta i valori in services.CoAuthoring.secret.inbox.string, services.CoAuthoring.secret.outbox.string, e services.CoAuthoring.secret.session.string. Dovrebbero essere tutti identici per questa configurazione standard. Verifica inoltre che la convalida del token sia abilitata per browser, casella di posta in arrivo e casella di posta in uscita. Le versioni di Docs precedenti alla 7.2 richiedono che la convalida del token sia abilitata esplicitamente; le versioni successive la abilitano per impostazione predefinita.

2. Aggiorna il connettore ONLYOFFICE di Nextcloud

1. Accedi come amministratore di Nextcloud e apri Impostazioni > Amministrazione > ONLYOFFICE .
2. Nelle impostazioni del server, inserisci la chiave segreta esatta che trovi sul Document Server in esecuzione nel campo Chiave segreta . Evita spazi iniziali o finali e non aggiungere virgolette a meno che non facciano parte della chiave segreta stessa.
3. Se la tua implementazione utilizza un'intestazione personalizzata, verifica l'impostazione dell'intestazione JWT. L' jwt_headerimpostazione del connettore e l'intestazione del token configurata nel Document Server devono corrispondere. Se non hai personalizzato intenzionalmente l'intestazione, non modificarla durante questa procedura di riparazione.
4. Salva le impostazioni. Mantieni JWT abilitato su entrambi i lati.

L'impostazione del connettore documentata può essere modificata anche tramite occil comando di Nextcloud dalla directory di installazione di Nextcloud:

sudo -u www-data php occ config:app:set onlyoffice jwt_secret --value='YOUR_SECRET'

Sostituisci YOUR_SECRETcon il valore effettivo. Le virgolette nella shell aiutano a preservare la punteggiatura, ma i segreti che contengono un singolo apice richiedono un metodo più sicuro rispetto all'inserimento diretto nella riga di comando. Gli argomenti della riga di comando potrebbero inoltre essere visibili all'ispezione dei processi privilegiati o alla cronologia della shell. Se possibile, è preferibile utilizzare l'interfaccia di amministrazione, quindi verificare il valore memorizzato senza esporlo.

3. Applica la modifica nel modo corretto per la tua installazione

Docker o Docker Compose

Per le implementazioni Docker, configura JWT tramite l'ambiente del container anziché modificare manualmente il file generato automaticamente local.json. Imposta lo stesso segreto nella definizione del servizio Document Server:

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

Dopo aver modificato il file Compose, ricrea il contenitore del Document Server affinché le modifiche all'ambiente abbiano effetto. Ad esempio, dalla directory contenente il file Compose:

docker compose up -d --force-recreate <documentserver-service>

Sostituisci il nome del servizio con quello presente nel tuo file Compose. Un semplice riavvio non applica un valore di ambiente modificato a un container esistente. Se utilizzi docker run, ricrea il container con i valori JWT_ENABLEDe aggiornati JWT_SECRET, preservando le porte, i volumi e le altre opzioni necessarie esistenti. Non eliminare un container di produzione finché non hai confermato tali impostazioni e i mount dei dati persistenti.

Quando il container si avvia, rileggi il suo segreto attivo con il comando sopra indicato e assicurati che il valore corrisponda ancora a Nextcloud. Evita di inserire un segreto di produzione in un file Compose o in un repository di codice sorgente condivisi pubblicamente.

Pacchetto Linux o installazione Windows

Se si imposta intenzionalmente un segreto personalizzato in local.json, assicurarsi che i tre campi del segreto corrispondano e che i valori di convalida del token richiesti siano abilitati. Applicare la modifica riavviando i servizi del Document Server pertinenti. Le istruzioni ONLYOFFICE correnti elencano ds-converter, ds-docservice, e ds-metricssu Linux; le installazioni gestite da un supervisore dei servizi diverso potrebbero richiedere il metodo di riavvio appropriato a tale configurazione. Su Windows, riavviare i servizi ONLYOFFICE dopo aver salvato la configurazione.

Un'incongruenza che si ripresenta dopo il riavvio di solito significa che una configurazione generata o un ambiente di distribuzione stanno sovrascrivendo il file modificato. Per Docker, sposta la correzione nelle variabili d'ambiente e ricrea il container. Per le distribuzioni pacchettizzate, controlla la configurazione attiva e la configurazione di avvio del servizio prima di modificare ulteriori impostazioni.

Verifica la riparazione

1. Nella directory di installazione di Nextcloud, eseguire il controllo ufficiale del connettore:

sudo -u www-data php occ onlyoffice:documentserver --check

Se non è già presente, utilizza l'account del server web appropriato per la tua installazione www-data. Il comando dovrebbe segnalare una connessione riuscita. Se continua a segnalare un token non valido, verifica nuovamente che il segreto attivo del Document Server in esecuzione corrisponda esattamente a Nextcloud e che qualsiasi intestazione JWT personalizzata sia corretta.

2. Apri un piccolo documento di prova da Nextcloud con ONLYOFFICE. Verifica che l'editor si carichi, apporta una piccola modifica, salva, chiudi l'editor e riapri il file per confermare che la modifica sia stata salvata.
3. Se il controllo ora segnala un errore di rete o di certificato, interrompi la modifica dei valori JWT. Verifica che Nextcloud possa raggiungere l'indirizzo del Document Server e che il Document Server possa raggiungere l'indirizzo di callback di Nextcloud. Utilizza un certificato TLS attendibile, ove possibile; disabilitare la verifica del certificato è una soluzione temporanea non sicura e non risolve il problema di convalida del token.

Questi controlli verificano che la connessione configurata e un percorso di salvataggio di base funzionino correttamente. Non garantiscono la correttezza di ogni percorso di reverse proxy, configurazione di storage esterno o topologia multi-server; se la tua implementazione li utilizza, testa separatamente tali percorsi.

Riferimenti ufficiali

• ONLYOFFICE: Integrazione con Nextcloud e configurazione JWT
• ONLYOFFICE: Configurare JWT per il server dei documenti
• Connettore Nextcloud ONLYOFFICE: opzioni di configurazione e comandi occ

I dettagli di configurazione sono stati verificati rispetto alla documentazione ufficiale di ONLYOFFICE e al repository dei connettori il 9 ottobre 2026. Le etichette dell'interfaccia utente e la gestione dei servizi possono variare a seconda del connettore, del sistema operativo e del metodo di implementazione.