Configura i segreti JWT di ONLYOFFICE tra server e connettore

Utilizza sempre un unico segreto JWT sicuro: configuralo su ONLYOFFICE Docs, copia lo stesso valore nelle impostazioni di ONLYOFFICE della piattaforma connessa e mantieni la convalida JWT abilitata. Docs 7.2 e versioni successive abilitano JWT per impostazione predefinita e generano automaticamente un segreto; la modifica del segreto implica l'aggiornamento di ogni integrazione. Il metodo esatto lato server dipende dal fatto che Docs venga eseguito come pacchetto Linux o come container Docker.

Cosa deve corrispondere?

JWT (JSON Web Token) consente a ONLYOFFICE Docs di verificare le richieste firmate. La piattaforma documentale e Docs devono utilizzare la stessa chiave segreta e impostazioni di intestazione compatibili. Il server utilizza impostazioni di token separate per la configurazione del browser e per le richieste di servizio in entrata e in uscita; i valori della chiave segreta condivisa proteggono questi scambi. Non inserire la chiave segreta in una pagina web pubblica, in un bundle JavaScript lato client, in un ticket di supporto o in un repository di codice sorgente accessibile pubblicamente.

Prima di apportare modifiche, identifica il tipo di distribuzione e annota l'URL della documentazione utilizzato dal connettore. Genera una password segreta lunga e imprevedibile utilizzando un gestore di password o un generatore crittograficamente sicuro. Trattala come una credenziale e memorizzala in un archivio di configurazione con accesso limitato.

Configurare un'installazione Linux

Per un'installazione Linux basata su pacchetti, modificare /etc/onlyoffice/documentserver/local.json. Conservare le impostazioni esistenti: unire le seguenti chiavi al JSON esistente anziché sostituire l'intero file. L'esempio mostra la struttura di convalida del token e le tre posizioni dei segreti corrispondenti descritte nella guida di configurazione ufficiale:

{
  "services": {
    "CoAuthoring": {
      "token": {
        "enable": {
          "request": {
            "inbox": true,
            "outbox": true
          },
          "browser": true
        }
      },
      "secret": {
        "inbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "outbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "session": { "string": "REPLACE_WITH_YOUR_SECRET" }
      }
    }
  }
}

Sostituisci ogni segnaposto con lo stesso identico valore segreto. Non incollare il segnaposto di esempio. Gli interruttori browser, inbox, e outboxsono separati; abilitandone solo uno non si abilita tutta la convalida della richiesta. La documentazione dalla versione 7.2 in poi ha JWT abilitato per impostazione predefinita, ma controllare esplicitamente queste impostazioni è utile quando si verifica una configurazione esistente o si allinea il comportamento tra i nodi. Per le versioni precedenti alla 7.2, la guida ufficiale consiglia di abilitare tutti e tre gli interruttori.

Prima di riavviare, convalida la sintassi JSON. Quindi riavvia i servizi del server documenti affinché le modifiche vengano caricate.

sudo systemctl restart ds-converter ds-docservice ds-metrics

Eseguire il comando con un account autorizzato a gestire i servizi di sistema. Su Windows, il file di configurazione è %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json; utilizzare le istruzioni di riavvio di Windows presenti nella guida ufficiale anziché il comando Linux.

Configura Docker senza modificare il file di configurazione generato.

Per l'immagine Docker ufficiale di Document Server, impostare il JWT tramite le variabili d'ambiente del container. La guida ufficiale avverte che la modifica manuale del JWT generato local.jsonpuò essere annullata al riavvio del container. Impostare JWT_ENABLED=truee JWT_SECRETnel comando di creazione del container o nel servizio Compose, quindi ricreare il container affinché l'ambiente abbia effetto. Conservare il segreto in un file di ambiente protetto o in un gestore di segreti e limitare le autorizzazioni di tale file; evitare di inserirlo nel controllo di versione.

services:
  onlyoffice:
    image: onlyoffice/documentserver:YOUR_PINNED_TAG
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: ${ONLYOFFICE_JWT_SECRET}

Definisci ONLYOFFICE_JWT_SECRETnell'ambiente di distribuzione o .envnel file protetto. Blocca un tag immagine testato invece di affidarti a latest, e controlla la documentazione per il tag esatto che esegui. Dopo aver modificato i valori dell'ambiente, ricrea il container utilizzando il tuo normale processo di distribuzione. Un semplice riavvio potrebbe lasciare il vecchio ambiente al suo posto.

Aggiorna il connettore e proteggi il segreto

Apri le impostazioni di integrazione nella piattaforma che si connette a ONLYOFFICE Docs, come Nextcloud o un altro connettore supportato. Inserisci lo stesso segreto JWT nel campo "chiave segreta" e salva. Verifica inoltre l'URL del server documenti configurato e, se il connettore lo espone, l'intestazione di autorizzazione. L'intestazione predefinita in ONLYOFFICE Docs è Authorization; modificala solo se entrambe le parti sono configurate per utilizzare la stessa alternativa.

Un'incongruenza nella chiave segreta si manifesta comunemente come un errore di token non valido o di autorizzazione all'apertura o al salvataggio di un documento. Un'incongruenza può verificarsi anche quando viene aggiornato un solo nodo di Documenti dietro un bilanciatore di carico. Se si gestiscono più nodi, è necessario sincronizzare le stesse impostazioni di chiave segreta e token su tutti i nodi prima di instradare il traffico verso di essi. Implementare le modifiche in un intervallo di tempo controllato: aggiornare Documenti e il connettore contemporaneamente e prevedere che le sessioni di modifica esistenti o le richieste firmate con il vecchio valore non vadano a buon fine durante la transizione.

Chiunque sia in grado di leggere il segreto può creare token che il server potrebbe accettare. Limita l'accesso ai file di configurazione e alle variabili di distribuzione, utilizza un trasporto crittografato per la connessione tra il connettore e la documentazione e ruota il segreto se potrebbe essere stato esposto. La rotazione richiede l'aggiornamento di tutti i nodi della documentazione e del connettore con il nuovo valore; non lasciare le vecchie credenziali nei file archiviati o nei log.

Verifica la configurazione

• Verificare che il servizio o il container della documentazione sia in esecuzione dopo la modifica della configurazione.
• Per una distribuzione Docker, eseguire il comando sudo docker exec <container_name> sudo documentserver-jwt-status.shper verificare lo stato del JWT. Utilizzare il nome effettivo del container. Questa funzione di supporto è documentata per Docker; non dare per scontato che sia disponibile in ogni installazione del pacchetto.
• Apri un documento tramite la piattaforma connessa, apporta una piccola modifica innocua e salvalo. Verifica che l'editor si apra e che la piattaforma riceva la modifica salvata.
• Se l'autenticazione fallisce, confronta il segreto del server e quello del connettore carattere per carattere, verifica che tutti gli switch del token pertinenti siano abilitati e controlla la configurazione dell'intestazione della richiesta.

La guida di configurazione ufficiale è la fonte autorevole per le impostazioni supportate e il comportamento delle diverse versioni. Consultare la documentazione di configurazione JWT di ONLYOFFICE e i parametri di installazione Docker ufficiali per la versione specifica che si intende utilizzare.