Risolvi l'errore "Token non valido" nell'integrazione di ONLYOFFICE con Nextcloud.

Il messaggio di ONLYOFFICE "Il token non è valido" di solito significa che i due lati dell'integrazione non stanno convalidando lo stesso JSON Web Token (JWT). In una configurazione Nextcloud, il punto importante è che esistono diversi percorsi per il token: la configurazione dell'editor inviata al browser, le richieste in entrata a ONLYOFFICE Docs e le richieste in uscita, come le callback a Nextcloud. Un errore in uno qualsiasi di questi percorsi può apparire simile dal lato utente.

Prima di iniziare a modificare le impostazioni, è importante tenere presente un dettaglio fondamentale: JWT è abilitato di default in ONLYOFFICE Docs dalla versione 7.2 e il Document Server può generare automaticamente una chiave segreta. Pertanto, un vecchio tutorial che consigliava di "lasciare JWT disabilitato" non è più una soluzione valida per un'installazione moderna. La guida attuale di ONLYOFFICE raccomanda di configurare una chiave segreta personalizzata e di utilizzarla nel connettore. Consultare la guida alla configurazione di JWT di ONLYOFFICE .

Guida rapida: cosa controllare per prima cosa

1. Conferma che il segreto condiviso sia effettivamente lo stesso

La validazione dei JWT dipende da un segreto condiviso. ONLYOFFICE Docs firma i token con tale segreto e il destinatario verifica la firma utilizzando lo stesso valore. Anche una sola differenza di carattere, uno spazio finale, una vecchia variabile d'ambiente o un segreto Docker rigenerato sono sufficienti a far sì che un token apparentemente valido non superi la verifica.

Su Nextcloud, il connettore supporta questa jwt_secretimpostazione. Il connettore ufficiale fornisce anche un'interfaccia occdi configurazione, che consente di verificare il valore effettivamente utilizzato da Nextcloud anziché affidarsi a un file di configurazione che si ritiene attivo. Le impostazioni correnti del connettore sono documentate nel file README ufficiale del connettore ONLYOFFICE per Nextcloud .

sudo -u www-data php occ config:app:get onlyoffice jwt_secret
sudo -u www-data php occ config:app:get onlyoffice jwt_header

Non incollare la chiave segreta nei ticket di supporto, negli screenshot, nella cronologia della shell condivisa con altri o nelle segnalazioni pubbliche di problemi. Confrontala localmente.

Per un'installazione nativa di ONLYOFFICE Docs su Linux, il file di configurazione supportato è:

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE documenta separatamente le impostazioni dei token per browser, posta in arrivo e posta in uscita. I valori segreti utilizzati per la convalida devono essere coerenti con la configurazione del connettore. Non modificare default.json; ONLYOFFICE avverte esplicitamente che le impostazioni predefinite possono essere sovrascritte al riavvio o all'aggiornamento. Utilizzare local.jsonper le installazioni dei pacchetti.

Se esegui ONLYOFFICE Docs in Docker

Utilizza le variabili d'ambiente di Docker anziché modificarle manualmente local.jsonall'interno del container. ONLYOFFICE afferma che Docker può rigenerare la configurazione JWT durante l'avvio; la sua immagine ufficiale supporta JWT_ENABLED, JWT_SECRET, JWT_HEADER, e JWT_IN_BODY. La documentazione attuale dell'immagine Docker elenca Authorizationcome intestazione JWT predefinita. Consulta il repository ufficiale di Docker DocumentServer .

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=replace-with-a-long-random-secret
  - JWT_HEADER=Authorization

Dopo aver modificato le variabili d'ambiente di Docker, è necessario ricreare il container affinché il servizio in esecuzione le riceva. La semplice modifica di un file Compose senza ricreare il container non modifica l'ambiente esistente.

2. Assicurarsi che l'intestazione JWT corrisponda esattamente

Un malinteso comune è che il nome dell'intestazione sia puramente estetico. Non è così. ONLYOFFICE Docs dispone di intestazioni token per la posta in arrivo e in uscita configurabili, e il connettore Nextcloud ha un'impostazione jwt_headerapposita. Devono descrivere lo stesso percorso di richiesta.

La documentazione API di ONLYOFFICE attualmente disponibile elenca Authorizationcome predefinito il Document Server per le richieste JWT in entrata, e anche la documentazione ufficiale sull'integrazione con Nextcloud lo identifica Authorizationcome predefinito per il connettore. Esempi meno recenti e installazioni esistenti potrebbero utilizzare AuthorizationJWTo un altro valore configurato esplicitamente. La regola generale non è quindi "usare sempre una stringa specifica", bensì assicurarsi che la configurazione attiva corrisponda su entrambi i lati .

Anche il formato della richiesta è importante. La documentazione API di ONLYOFFICE mostra i token di intestazione inviati utilizzando lo schema Bearer. Per i dettagli del protocollo sottostante, consultare la documentazione di ONLYOFFICE relativa ai token nell'intestazione .

Se si utilizza intenzionalmente un'intestazione personalizzata, è necessario configurare lo stesso valore in entrambi i prodotti. Se non vi è alcun motivo per personalizzarla, l'utilizzo del valore predefinito corrente Authorizationriduce il numero di elementi da gestire.

3. Verificare se un proxy inverso sta modificando il percorso del token

Se le impostazioni di Nextcloud e ONLYOFFICE corrispondono ma l'errore persiste, esamina il percorso tra di essi. Un reverse proxy, un gateway di autenticazione, un WAF o un controller di ingresso possono influire sulle intestazioni di autorizzazione. Questo dipende dalla tua infrastruttura, quindi non dare per scontato che il proxy sia il responsabile senza prove.

Utilizza questa sequenza di test pratici:

• Verificare che l'URL pubblico del Document Server sia raggiungibile dall'host Nextcloud.
• Verificare che l'URL interno del Document Server, se configurato, sia risolvibile dal server o dal container Nextcloud.
• Verificare che l'URL interno di Nextcloud/storage sia risolvibile dall'host o dal container di ONLYOFFICE Docs.
• Esamina i log di accesso/errore del proxy durante l'esecuzione del controllo del connettore.
• Se il tuo proxy ha regole esplicite per Authorization, verifica che inoltri l'intestazione anziché sostituirla o rimuoverla.

Non disabilitare JWT solo per far scomparire l'errore. In questo modo si rimuove il meccanismo di validazione anziché ripararlo. Inoltre, non disabilitare la verifica TLS come soluzione al problema JWT: la verifica del certificato e la validazione della firma JWT sono controlli separati. In caso di problemi con il certificato, correggi la catena di certificati o la configurazione di attendibilità separatamente.

4. Utilizzare il controllo di integrità del connettore stesso

Il connettore ufficiale ONLYOFFICE include un comando diagnostico appositamente creato:

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

La documentazione del connettore afferma che questo controllo segnala se la connessione è andata a buon fine o la causa di un errore. È più utile rispetto al semplice test della pagina di destinazione del Document Server perché verifica l'integrazione dal punto di vista di Nextcloud.

Se il controllo indica che il Document Server è raggiungibile ma la convalida del token fallisce, tornare al segreto e all'intestazione. Se non è possibile raggiungere il server, risolvere i problemi relativi a DNS, routing, firewall, TLS o URL interni prima di dedicare altro tempo al JWT.

5. Verificare l'ora solo quando le prove lo indicano

I JWT possono includere informazioni relative al tempo e il connettore Nextcloud espone jwt_leewaye jwt_expirationimposta. Ciò non significa che si debba prima aumentare il margine di tolleranza. Un orologio sostanzialmente errato può causare il fallimento di token altrimenti corretti; aumentare il margine di tolleranza può nascondere il problema dell'infrastruttura.

Confronta l'ora UTC sugli host o sui container di Nextcloud e ONLYOFFICE:

date -u
timedatectl status

Assicurati che entrambi i sistemi sincronizzino l'ora in modo affidabile. Solo dopo aver verificato una piccola e legittima differenza di orario, dovresti considerare un margine di tolleranza ristretto. Le impostazioni JWT supportate dal connettore sono elencate nel manuale di configurazione ufficiale del connettore .

Come funziona la convalida JWT in questa integrazione

ONLYOFFICE Docs utilizza JWT per proteggere l'inizializzazione dell'editor e le richieste da server a server. La sua API separa i token del browser dai token delle richieste HTTP in entrata e in uscita. Per le richieste in entrata, il token può essere incluso in un'intestazione o, per le richieste POST supportate, nel corpo della richiesta. Per le richieste GET, ONLYOFFICE documenta la gestione dei token basata sull'intestazione. Consultare la documentazione ufficiale sulla firma delle richieste .

Questo spiega perché un'operazione può funzionare mentre un'altra fallisce. Ad esempio, l'apertura dell'editor può avere successo mentre una successiva richiesta di callback o di download fallisce se solo una delle due operazioni ha le impostazioni del token corrette.

Idee sbagliate comuni

"Se /healthcheck restituisce true, il JWT deve essere corretto."

No. Un endpoint di integrità dimostra che il servizio sta rispondendo; non dimostra che il connettore Nextcloud e il Document Server condividono lo stesso segreto JWT e la stessa intestazione. Azione: eseguire occ onlyoffice:documentserver --checke verificare le impostazioni effettive del connettore.

"Posso modificare il file local.json all'interno di un container Docker e il gioco è fatto."

Questa soluzione è fragile per le implementazioni Docker. ONLYOFFICE consiglia di impostare il JWT tramite le variabili d'ambiente Docker perché l'avvio può rigenerare la configurazione. Azione: definire JWT_ENABLED, JWT_SECRET, e, quando necessario, JWT_HEADERnella configurazione del container e ricreare il container.

"L'intestazione AuthorizationJWT è sempre obbligatoria."

No. La configurazione ufficiale corrente di Document Server elenca Authorizationcome intestazione predefinita, sebbene le implementazioni esistenti e gli esempi più vecchi possano utilizzare un'altra intestazione configurata esplicitamente. Azione: leggere entrambe le configurazioni attive e renderle identiche.

"Disattivare JWT è la soluzione più rapida."

Potrebbe eliminare l'errore di convalida immediato, ma rimuove anche un controllo di sicurezza e può mascherare la discrepanza sottostante. Azione: correggere il segreto/intestazione condiviso a meno che non si disponga di un motivo specifico e documentato per operare senza JWT.

Lista di controllo per la convalida finale

• Lo stesso segreto JWT è configurato sia in Nextcloud che nella documentazione di ONLYOFFICE.
• Il nome dell'intestazione JWT corrisponde su entrambi i lati.
• Le implementazioni Docker utilizzano variabili d'ambiente persistenti, non modifiche ad hoc all'interno del container.
• Gli URL del server, sia pubblici che interni, sono raggiungibili nella direzione in cui vengono utilizzati.
• Nessuna regola proxy rimuove o riscrive inaspettatamente l'intestazione JWT.
• I sistemi Nextcloud e ONLYOFFICE hanno orologi sincronizzati.
• occ onlyoffice:documentserver --checkha successo.
• Un documento reale si apre, si modifica, salva automaticamente, si chiude e si riapre con le modifiche salvate.

Quando l'errore del token persiste

Se i segreti e le intestazioni corrispondono, gli orologi sono sincronizzati e il controllo del connettore ha esito positivo, ma un'operazione specifica segnala comunque un token non valido, è necessario acquisire l'esatta direzione della richiesta non riuscita e i relativi log prima di modificare ulteriori impostazioni. ONLYOFFICE distingue la convalida del browser, della posta in arrivo e della posta in uscita, quindi la domanda successiva è se l'errore si verifica durante l'inizializzazione dell'editor, un comando inviato al Document Server o una callback/download inviata a Nextcloud.

Utilizza i log del Document Server insieme ai log di Nextcloud e ai log del proxy per lo stesso timestamp. Evita di pubblicare JWT o segreti completi pubblicamente. Se devi confrontare la struttura del token, oscura la firma e le informazioni sensibili. Il comportamento di riferimento per la firma e la convalida è descritto nella documentazione sulle firme di ONLYOFFICE .