Come configurare l'autenticazione con chiave segreta JWT di ONLYOFFICE

L'autenticazione JWT di ONLYOFFICE funziona solo quando il Document Server e l'applicazione di integrazione utilizzano la stessa chiave segreta. Nelle attuali implementazioni Docker, la convalida JWT è abilitata per impostazione predefinita. Per un'integrazione stabile, imposta una chiave persistente personalizzata JWT_SECRETanziché affidarti al valore generato automaticamente dal container, quindi configura la stessa chiave segreta in Nextcloud, nel tuo gestore di documenti personalizzato o in qualsiasi connettore che interagisca con ONLYOFFICE Docs.

Questa guida pratica si concentra sulla configurazione di cui probabilmente avrete bisogno: Docker e Docker Compose, integrazioni personalizzate che firmano la configurazione dell'editor, comportamento di intestazione/corpo, verifica, rotazione ed errori comuni. Si basa sulla documentazione ONLYOFFICE aggiornata a ottobre 2026.

Riferimento rapido

A partire dalla versione 7.2 di ONLYOFFICE Docs, le implementazioni Docker abilitano JWT per impostazione predefinita e generano una chiave segreta casuale se non ne viene specificata una. La documentazione ufficiale di Docker avverte che una chiave segreta generata automaticamente può cambiare dopo un riavvio o la ricreazione del container, compromettendo le integrazioni. Impostare una chiave segreta esplicita per qualsiasi implementazione reale. Consultare la sezione "Configurazione di JWT per ONLYOFFICE Docs" e la guida ufficiale all'installazione di Docker .

1. Identificare il contenitore ONLYOFFICE e il metodo di distribuzione

Per un host Docker, inizia con:

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
docker images | grep onlyoffice

Determina se l'istanza è stata avviata con docker runDocker Compose, un pannello di controllo o un altro livello di orchestrazione. Devi modificare la configurazione di origine che crea il container. Modificare un file generato all'interno del container non è una soluzione permanente.

Nello specifico per Docker, ONLYOFFICE consiglia agli amministratori di utilizzare le variabili d'ambiente anziché modificarle manualmente /etc/onlyoffice/documentserver/local.json. Se si modificano i valori JWT direttamente in quel file, il processo di avvio di Docker può ripristinarli o rigenerarli al riavvio del container.

2. Genera un segreto forte e conservalo in modo sicuro

Un comodo comando da shell è:

openssl rand -hex 32

Questo genera 32 byte casuali rappresentati da 64 caratteri esadecimali. ONLYOFFICE non richiede questo formato preciso; il requisito fondamentale è che entrambe le parti condividano lo stesso segreto e che sia difficile da indovinare.

Trattalo JWT_SECRETcome una password o una credenziale API:

• Non caricarlo su un repository Git pubblico.
• Non inserirlo nel codice JavaScript frontend inviato ai browser.
• Limita l'accesso al file di ambiente di Compose o all'archivio segreto che lo contiene.
• Utilizza una chiave segreta diversa per ambienti separati come quello di produzione e quello di staging.

La documentazione sulla firma di ONLYOFFICE avverte esplicitamente che la firma del token deve avvenire sul server perché qualsiasi codice lato browser che contenga il segreto lo espone agli utenti. Gli esempi ufficiali utilizzano HMAC-SHA256 ( HS256). Vedi la documentazione sulla firma JWT di ONLYOFFICE .

3. Configurare JWT in Docker Compose

Un servizio Compose minimo può includere:

services:
  documentserver:
    image: onlyoffice/documentserver:latest
    restart: unless-stopped
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: "${ONLYOFFICE_JWT_SECRET}"
      JWT_HEADER: "Authorization"
      JWT_IN_BODY: "false"
    ports:
      - "8080:80"

Se possibile, conserva il segreto vero e proprio al di fuori del file Compose. Ad esempio, inseriscilo in un .envfile con accesso limitato:

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

Assicurati quindi che il file sia escluso dal controllo di versione e che sia leggibile solo dagli amministratori o dall'account di servizio che ne ha bisogno.

Il repository ufficiale ONLYOFFICE Docker-DocumentServer documenta JWT_ENABLED, JWT_SECRET, JWT_HEADER, e JWT_IN_BODY. Il codice di avvio Docker corrente abilita per impostazione predefinita la convalida JWT, utilizza Authorizationcome intestazione predefinita e genera un segreto casuale quando non ne viene fornito uno esplicito.

4. Ricrea il contenitore in modo che il nuovo ambiente venga applicato

Per comporre:

docker compose up -d --force-recreate
docker compose ps

Per un container originariamente creato con docker run, la guida ufficiale JWT indica agli amministratori di arrestare e rimuovere il vecchio container, quindi di crearne uno nuovo con le variabili d'ambiente JWT. Non rimuovere volumi persistenti o dati montati tramite bind durante questa operazione.

È anche possibile ispezionare l'ambiente del container in esecuzione senza stampare il segreto stesso:

docker inspect onlyoffice-documentserver \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep '^JWT_' \
  | sed 's/^JWT_SECRET=.*/JWT_SECRET=[REDACTED]/'

Se il nome del contenitore è diverso, sostituirlo onlyoffice-documentserverdi conseguenza.

5. Configura lo stesso segreto nell'integrazione

Questa è la parte che più spesso viene trascurata. Abilitare JWT su ONLYOFFICE Docs senza configurare la gestione dei documenti causa il rifiuto delle richieste dell'editor. Il connettore o l'applicazione personalizzata devono firmare le richieste con esattamente lo stesso segreto.

Esempio di Nextcloud

Nelle impostazioni di ONLYOFFICE per Nextcloud, inserisci la stessa chiave segreta utilizzata dal Document Server. Anche il nome dell'intestazione deve corrispondere. La documentazione attuale di ONLYOFFICE sull'integrazione con Nextcloud elenca jwt_secrete jwt_headercome impostazioni del connettore, con Authorizationcome intestazione predefinita. Consulta la documentazione ufficiale del connettore Nextcloud .

Se il connettore dispone di un campo etichettato "Chiave segreta", "Segreto JWT" o simile, non generare un secondo segreto indipendente in quel campo. Copia lo stesso valore del segreto.

6. Per un'integrazione personalizzata, firmare la configurazione completa dell'editor sul server.

Per un'applicazione personalizzata, crea prima la configurazione dell'editor, firma tale configurazione sul backend, quindi assegna il JWT risultante alla tokenproprietà di livello superiore.

Esempio con Node.js:

import jwt from "jsonwebtoken";

const config = {
  documentType: "word",
  document: {
    fileType: "docx",
    key: "document-2026-001",
    title: "Project Plan.docx",
    url: "https://files.example.com/project-plan.docx"
  },
  editorConfig: {
    callbackUrl: "https://app.example.com/onlyoffice/callback"
  }
};

config.token = jwt.sign(config, process.env.ONLYOFFICE_JWT_SECRET, {
  algorithm: "HS256"
});

La documentazione di ONLYOFFICE relativa alla firma del browser afferma che il payload del token per l'apertura di un file deve avere la stessa struttura della configurazione dell'editor. Dalla versione 7.1, l'insieme dei parametri coinvolti nella convalida è rigorosamente regolamentato per questa operazione, pertanto la firma di una struttura obsoleta o parziale è una causa comune di errori. Vedere Firma del token del browser .

La configurazione risultante passata DocsAPI.DocEditorcontiene il token:

new DocsAPI.DocEditor("placeholder", config);

La documentazione ufficiale dell'API definisce config.tokenla firma crittografata utilizzata da ONLYOFFICE Docs per convalidare la configurazione dell'editor.

7. Comprendere la differenza tra i token di intestazione e quelli del corpo della pagina.

In ONLYOFFICE, JWT non si limita alla configurazione dell'editor del browser. Viene utilizzato anche per le richieste da servizio a servizio, come il traffico di comandi, conversioni e callback.

ONLYOFFICE supporta i token di richiesta sia nel corpo che nell'intestazione. Le sue FAQ sulla sicurezza indicano che le intestazioni possono raggiungere i limiti di lunghezza specifici del server e pertanto raccomandano l'utilizzo di token nel corpo per le richieste in entrata applicabili. A partire dalla versione 7.1 della documentazione, un token nel corpo in entrata ha la precedenza se presente; in caso contrario, viene utilizzato il token nell'intestazione. Il lato in uscita può inviare entrambi. Consultare la documentazione sui token di richiesta di ONLYOFFICE .

La variabile Docker JWT_IN_BODYha un valore predefinito di false, quindi non abilitarla solo perché esiste. Modificala solo se la tua integrazione è progettata per inviare e convalidare i token del corpo in modo coerente.

8. Esegui un test con una richiesta reale dell'editor.

Una sequenza di validazione utile è:

1. Apri un documento tramite la tua integrazione reale.
2. Verifica che l'editor si carichi senza errori di token.
3. Apporta una piccola modifica.
4. Chiudi l'editor o avvia il normale processo di salvataggio.
5. Verificare che l'applicazione di archiviazione riceva e accetti la callback.

Una pagina di benvenuto del Document Server visualizzata correttamente non garantisce che JWT sia configurato correttamente tra due applicazioni. Gli errori JWT spesso si verificano solo quando l'integrazione invia la configurazione dell'editor, il comando, la richiesta di conversione o la callback.

La panoramica ufficiale sulla sicurezza spiega il comportamento previsto: ONLYOFFICE convalida un token e utilizza i valori del payload firmato; se il token è mancante o non valido quando è richiesta la convalida, la richiesta viene rifiutata. Consultare la panoramica sulla sicurezza nella documentazione di ONLYOFFICE .

9. Controlla lo stato e i log del JWT quando l'autenticazione fallisce

Il codice di avvio Docker corrente indirizza gli amministratori all'helper di stato JWT. Con il nome del container corretto, eseguire:

docker exec onlyoffice-documentserver \
  sudo documentserver-jwt-status.sh

È inoltre possibile consultare i registri:

docker logs --tail 200 onlyoffice-documentserver
docker exec onlyoffice-documentserver \
  find /var/log/onlyoffice/documentserver -type f -maxdepth 3 -print

Se l'integrazione fallisce immediatamente dopo la modifica del segreto, confronta questi elementi in ordine:

• È JWT_ENABLEDeffettivamente abilitato nel container ricreato?
• L'integrazione utilizza esattamente lo stesso segreto, comprese le maiuscole e la punteggiatura?
• Il connettore utilizza lo stesso nome dell'intestazione JWT?
• Nel caso di un editor personalizzato, stai firmando lo stesso oggetto di configurazione che invii al browser?
• Anche le callback e le richieste di comando vengono firmate e validate come richiesto?
• Un segreto memorizzato in un file di shell o Compose è stato troncato, interpretato o sostituito dall'espansione di una variabile d'ambiente?

Schemi di guasto comuni

“Token non valido” o “Firma non valida”

La causa più probabile è una mancata corrispondenza della chiave segreta o un token firmato su un payload diverso da quello della richiesta in fase di convalida. Rigenerare il token dopo ogni modifica rilevante alla configurazione. Non riutilizzare i token di esempio presenti nella documentazione; tali esempi sono firmati con chiavi segrete dimostrative e non sono validi per il proprio server.

Funziona finché Docker non si riavvia

Questo di solito significa che il deployment si basava sul segreto JWT generato automaticamente. ONLYOFFICE avverte esplicitamente che un segreto casuale può essere rigenerato dopo il riavvio o la ricreazione del container. Impostalo JWT_SECRETmanualmente e inserisci lo stesso valore nell'integrazione.

Nextcloud mostra un errore di connessione o del token

Innanzitutto, controlla il segreto e l'intestazione su entrambi i lati. La documentazione Nextcloud di ONLYOFFICE richiede che il connettore jwt_headercorrisponda all'intestazione configurata in Document Server. Il valore predefinito corrente è Authorization.

Una richiesta firmata di grandi dimensioni restituisce un errore HTTP

Verifica se il JWT viene inviato in un'intestazione che supera il limite di dimensione dell'intestazione del proxy o del server web. Le FAQ sulla sicurezza di ONLYOFFICE spiegano che questo è uno dei motivi per cui i token nel corpo della richiesta sono preferibili per le richieste POST applicabili.

Rotazione sicura del segreto JWT

La rotazione dei segreti JWT deve essere coordinata. Non c'è alcun vantaggio nel cambiare solo il Document Server mentre il connettore continua a firmare con il vecchio segreto.

Per una semplice implementazione a istanza singola:

1. Genera il nuovo segreto e memorizzalo in modo sicuro.
2. Pianifica una breve finestra di manutenzione se gli editor attivi potrebbero essere interessati.
3. Aggiorna il segreto dell'integrazione e quello del server dei documenti JWT_SECRETcome un'unica modifica coordinata.
4. Ricreare il contenitore del server dei documenti.
5. Apri, modifica e salva un documento di prova.
6. Prima di ripristinare il normale utilizzo del servizio, verificare che le callback funzionino correttamente.

Per più istanze di Document Server dietro un bilanciatore di carico, tutte le istanze che gestiscono la stessa integrazione necessitano di una configurazione JWT compatibile durante la modifica. Pianifica l'implementazione anziché ruotare un nodo ad hoc.

Lista di controllo della produzione

• Segreto persistente: impostalo JWT_SECRETesplicitamente; non fare affidamento sul valore generato casualmente.
• Lo stesso segreto ovunque: il Document Server e l'integrazione devono condividere lo stesso valore.
• Firma lato server: non esporre mai il segreto nel codice del frontend/browser.
• HS256: utilizzare l'approccio HMAC-SHA256 mostrato negli esempi di codice ufficiali di ONLYOFFICE.
• Accordo sull'intestazione: se un connettore invia JWT tramite un'intestazione denominata, tale nome deve corrispondere a quello del Document Server.
• Ricreazione del container: le modifiche all'ambiente Docker richiedono la ricreazione del container.
• Test di integrazione reale: apertura, modifica, salvataggio e verifica del comportamento della funzione di callback.
• Archiviazione segreta: tieni il segreto lontano da repository e registri pubblici.
• Rotazione controllata: aggiornare entrambi i lati contemporaneamente e verificare prima di terminare la manutenzione.

In conclusione

Per un'installazione ONLYOFFICE basata su Docker, la configurazione persistente è semplice: generare un segreto robusto, impostarlo JWT_ENABLED=truetramite JWT_SECRETle variabili d'ambiente del container, ricreare il container e configurare esattamente lo stesso segreto nel connettore o nel backend. Le integrazioni personalizzate devono firmare la configurazione dell'editor e le richieste di servizio sul server con HS256, mai nel codice del browser.

Se JWT smette improvvisamente di funzionare dopo un riavvio, verifica se il segreto è mai stato reso persistente. Se il problema si verifica immediatamente dopo una modifica della configurazione, confronta il segreto, l'intestazione e il payload firmato prima di cercare altrove. Questi tre controlli risolvono la maggior parte degli errori di configurazione di JWT senza compromettere l'autenticazione.