Cum se configurează autentificarea cu cheie secretă ONLYOFFICE JWT

Autentificarea ONLYOFFICE JWT funcționează numai atunci când serverul de documente și aplicația de integrare utilizează aceeași cheie secretă. În implementările Docker actuale, validarea JWT este activată în mod implicit. Pentru o integrare stabilă, setați propria cheie persistentă JWT_SECRETîn loc să vă bazați pe valoarea generată automat de container, apoi configurați aceeași cheie secretă în Nextcloud, managerul de documente personalizat sau orice conector care comunică cu ONLYOFFICE Docs.

Această referință practică se concentrează pe configurația de care probabil veți avea nevoie: Docker și Docker Compose, integrări personalizate care configurează editorul de semnătură, comportamentul antetului/corpului, verificarea, rotația și erorile comune. Se bazează pe documentația ONLYOFFICE actuală, verificată în octombrie 2026.

Referință rapidă

Începând cu ONLYOFFICE Docs 7.2, implementările Docker activează JWT în mod implicit și generează un secret aleatoriu atunci când nu furnizați unul. Documentația oficială Docker avertizează că un secret generat automat se poate modifica după o repornire sau recrearea containerului și întreruperea integrărilor. Setați un secret explicit pentru orice implementare reală. Consultați Configurarea JWT pentru ONLYOFFICE Docs și ghidul oficial de instalare Docker .

1. Identificați containerul ONLYOFFICE și metoda de implementare

Pentru o gazdă Docker, începeți cu:

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

Stabiliți dacă instanța a fost lansată cu docker run, Docker Compose, un panou de control sau un alt strat de orchestrare. Trebuie să modificați configurația sursă care creează containerul. Editarea unui fișier generat în interiorul containerului nu este soluția persistentă.

În mod specific pentru Docker, ONLYOFFICE le spune administratorilor să utilizeze variabile de mediu în loc să le editeze manual /etc/onlyoffice/documentserver/local.json. Dacă editați valorile JWT direct în fișierul respectiv, procesul de pornire Docker le poate restaura sau regenera atunci când containerul repornește.

2. Generați un secret puternic și stocați-l în siguranță

O comandă shell convenabilă este:

openssl rand -hex 32

Aceasta produce 32 de octeți aleatori reprezentați ca 64 de caractere hexazecimale. ONLYOFFICE nu necesită exact acest format; cerința importantă este ca ambele părți să împărtășească același secret și ca acesta să fie dificil de ghicit.

Tratați JWT_SECRETca o parolă sau o acreditări API:

• Nu îl trimiteți într-un depozit Git public.
• Nu îl puneți în JavaScript-ul frontend livrat browserelor.
• Restricționați accesul la fișierul mediului Compose sau la depozitul de secrete care îl conține.
• Folosește un secret diferit pentru medii separate, cum ar fi producția și pregătirea.

Documentația de semnătură ONLYOFFICE avertizează explicit că semnarea token-urilor trebuie să aibă loc pe server, deoarece orice cod din browser care conține secretul îl expune utilizatorilor. Exemplele oficiale utilizează HMAC-SHA256 ( HS256). Consultați documentația de semnătură ONLYOFFICE JWT .

3. Configurați JWT în Docker Compose

Un serviciu Compose minimal poate include:

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"

Păstrați secretul propriu-zis în afara fișierului Compose, atunci când este posibil. De exemplu, puneți-l într-un .envfișier cu permisiuni restricționate:

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

Apoi, asigurați-vă că fișierul este exclus din controlul versiunilor și poate fi citit doar de administratorii sau de contul de serviciu care are nevoie de el.

Depozitul oficial ONLYOFFICE Docker-DocumentServer documentează JWT_ENABLED, JWT_SECRET, JWT_HEADER, și JWT_IN_BODY. Codul de pornire Docker curent setează implicit validarea JWT la activată, folosește Authorizationca antet implicit și generează un secret aleatoriu atunci când nu este furnizat unul explicit.

4. Recreați containerul astfel încât noul mediu să fie aplicat

Pentru Compunere:

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

Pentru un container creat inițial cu docker run, ghidul oficial JWT instruiește administratorii să oprească și să elimine vechiul container, apoi să creeze unul nou cu variabilele de mediu JWT. Nu eliminați volumele persistente sau datele montate prin legare în timp ce faceți acest lucru.

De asemenea, puteți inspecta mediul containerului care rulează fără a afișa secretul în sine:

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

Dacă numele containerului este diferit, înlocuiți-l onlyoffice-documentserverîn mod corespunzător.

5. Configurați același secret în integrare

Aceasta este partea cel mai des omisă. Activarea JWT în ONLYOFFICE Docs fără configurarea părții de gestionare a documentelor duce la respingerea solicitărilor editorului. Conectorul sau aplicația personalizată trebuie să semneze solicitările cu exact același secret.

Exemplu Nextcloud

În setările ONLYOFFICE pentru Nextcloud, introduceți aceeași cheie secretă utilizată de serverul de documente. Numele antetului trebuie să corespundă și el. Documentația curentă de integrare Nextcloud a ONLYOFFICE listează jwt_secretși jwt_headerca setări ale conectorului, ca Authorizationantet implicit normal. Consultați documentația oficială a conectorului Nextcloud .

Dacă conectorul are un câmp etichetat „Cheie secretă”, „Secret JWT” sau similar, nu generați un al doilea secret independent acolo. Copiați aceeași valoare a secretului.

6. Pentru o integrare personalizată, semnați configurația completă a editorului pe server

Pentru o aplicație personalizată, construiți mai întâi configurația editorului, semnați acea configurație în backend, apoi atribuiți JWT-ul rezultat tokenproprietății de nivel superior.

Exemplu 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"
});

Documentația ONLYOFFICE pentru semnătura de browser precizează că sarcina utilă a token-ului pentru deschiderea unui fișier trebuie să aibă aceeași structură ca și configurația editorului. Începând cu versiunea 7.1, setul de parametri implicați în validare este strict reglementat pentru această operațiune, așadar semnarea unei structuri învechite sau parțiale este o cauză frecventă a eșecurilor. Consultați Semnarea token-urilor de browser .

Configurația rezultată transmisă către DocsAPI.DocEditorconține token-ul:

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

Referința oficială API definește config.tokensemnătura criptată utilizată de ONLYOFFICE Docs pentru a valida configurația editorului.

7. Înțelegerea diferențelor dintre token-urile de antet și cele de corp

JWT în ONLYOFFICE acoperă mai mult decât configurația editorului de browser. Este folosit și pentru solicitări service-to-service, cum ar fi comenzi, conversii și trafic de callback.

ONLYOFFICE acceptă token-uri de solicitare atât în ​​corp, cât și în antet. Întrebările frecvente despre securitate menționează că anteturile pot încadra limitele de lungime specifice serverului și, prin urmare, recomandă token-uri de corp pentru solicitările primite aplicabile. Începând cu Docs 7.1, un token de corp primit are prioritate atunci când este prezent; în caz contrar, se utilizează token-ul antetului. Partea de ieșire poate trimite ambele. Consultați documentația ONLYOFFICE request-token .

Variabila Docker JWT_IN_BODYare valoarea implicită false, așa că nu o activați doar pentru că există. Schimbați-o doar atunci când integrarea este concepută să trimită și să valideze în mod consecvent token-urile corpului.

8. Testează cu o solicitare reală a unui editor

O secvență de validare utilă este:

1. Deschideți un document prin integrarea reală.
2. Verificați dacă editorul se încarcă fără erori de token.
3. Fă o mică modificare.
4. Închideți editorul sau declanșați calea normală de salvare.
5. Verificați dacă aplicația de stocare primește și acceptă apelul invers.

O pagină de bun venit a serverului de documente executată cu succes nu dovedește că JWT este configurat corect între două aplicații. Erorile JWT apar adesea doar atunci când integrarea trimite configurația editorului, comanda, solicitarea de conversie sau apelul invers.

Prezentarea oficială a securității explică comportamentul așteptat: ONLYOFFICE validează un token și utilizează valorile sarcinii utile semnate; dacă tokenul lipsește sau este invalid atunci când este necesară validarea, solicitarea este respinsă. Consultați prezentarea generală a securității ONLYOFFICE Docs .

9. Verificați starea și jurnalele JWT atunci când autentificarea eșuează

Codul de pornire Docker curent indică administratorii către ajutorul de stare JWT. Cu numele corect al containerului, executați:

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

De asemenea, puteți inspecta jurnalele:

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

Dacă o integrare eșuează imediat după modificarea secretului, comparați aceste elemente în ordine:

• Este JWT_ENABLEDde fapt activat în containerul recreat?
• Integrarea folosește exact același secret, inclusiv scrierea cu majuscule și semnele de punctuație?
• Conectorul folosește același nume de antet JWT?
• Pentru un editor personalizat, semnați același obiect de configurație pe care îl trimiteți browserului?
• Sunt, de asemenea, semnate și validate apelurile inverse și cererile de comandă, așa cum este necesar?
• A fost trunchiat, interpretat sau înlocuit un secret stocat într-un shell sau într-un fișier Compose prin expansiunea variabilei de mediu?

Modele comune de eșec

„Jeton nevalid” sau „Semnătură nevalidă”

Cea mai probabilă cauză este o nepotrivire de secret sau un token semnat peste o sarcină utilă diferită de solicitarea validată. Regenerați tokenul după orice modificare relevantă a configurației. Nu reutilizați un token exemplu din documentație; acele exemple sunt semnate cu secrete demonstrative și nu sunt valide pentru serverul dvs.

Funcționează până când Docker repornește.

De obicei, aceasta înseamnă că implementarea se baza pe secretul JWT generat automat. ONLYOFFICE avertizează explicit că un secret aleatoriu poate fi regenerat după repornire sau recrearea containerului. Setați JWT_SECRET-l și introduceți aceeași valoare în integrare.

Nextcloud afișează o eroare de conexiune sau de token

Verificați mai întâi secretul și antetul de pe ambele părți. Documentația Nextcloud de la ONLYOFFICE necesită ca conectorii jwt_headersă se potrivească cu antetul configurat în Document Server. Valoarea implicită curentă este Authorization.

O cerere semnată mare returnează o eroare HTTP

Verificați dacă JWT este trimis într-un antet care depășește limita de dimensiune a antetului proxy sau server web. Întrebările frecvente despre securitate de la ONLYOFFICE explică faptul că acesta este unul dintre motivele pentru care token-urile de corp sunt preferate pentru cererile POST aplicabile.

Rotirea secretului JWT în siguranță

O rotație a secretelor JWT trebuie coordonată. Nu există niciun avantaj în a schimba doar serverul de documente în timp ce conectorul continuă să semneze cu vechiul secret.

Pentru o implementare simplă cu o singură instanță:

1. Generați noul secret și stocați-l în siguranță.
2. Programați o scurtă perioadă de mentenanță dacă editorii activi ar putea fi afectați.
3. Actualizați secretul integrării și pe cel al serverului de documente JWT_SECRETca o singură modificare coordonată.
4. Recreați containerul Server de documente.
5. Deschideți, editați și salvați un document de test.
6. Confirmați funcționarea apelurilor inverse înainte de a readuce serviciul la utilizare normală.

Pentru mai multe instanțe de Document Server în spatele unui echilibrator de încărcare, toate instanțele care deservesc aceeași integrare necesită o configurație JWT compatibilă în timpul modificării. Planificați implementarea în loc să rotiți un nod ad-hoc.

Listă de verificare a producției

• Secret persistent: setat JWT_SECRETexplicit; nu se bazează pe valoarea generată aleatoriu.
• Același secret peste tot: Document Server și integrarea trebuie să aibă aceeași valoare.
• Semnarea backend: nu expuneți niciodată secretul în codul frontend/browser.
• HS256: utilizați abordarea HMAC-SHA256 prezentată în exemplele oficiale de cod ONLYOFFICE.
• Acord de antet: dacă un conector trimite JWT printr-un antet denumit, numele respectiv trebuie să corespundă cu Document Server.
• Recreerea containerului: Modificările mediului Docker necesită recrearea containerului.
• Test de integrare real: deschidere, editare, salvare și verificare comportament callback.
• Stocare secretă: păstrați secretul departe de depozitele și jurnalele publice.
• Rotație controlată: actualizați ambele părți simultan și verificați înainte de a termina întreținerea.

Concluzie

Pentru o instalare ONLYOFFICE bazată pe Docker, configurația durabilă este simplă: generați un secret puternic, setați variabile de mediu ale containerului JWT_ENABLED=true(și JWT_SECRETthrough), recreați containerul și configurați exact același secret în conector sau backend. Integrările personalizate ar trebui să semneze configurația editorului și cererile de servicii pe server cu HS256, niciodată în codul browserului.

Dacă JWT se defectează brusc după o repornire, verificați dacă secretul a fost vreodată făcut persistent. Dacă eșuează imediat după o modificare a configurației, comparați secretul, antetul și sarcina utilă semnată înainte de a căuta în altă parte. Aceste trei verificări rezolvă majoritatea erorilor de configurare JWT fără a slăbi autentificarea.