Remediați eroarea „Tokenul nu este valid” în integrarea ONLYOFFICE Nextcloud

Mesajul ONLYOFFICE „Token-ul nu este valid” înseamnă de obicei că cele două părți ale integrării nu validează același token web JSON (JWT). Într-o configurație Nextcloud, punctul important este că există mai multe căi pentru token-uri: configurația editorului trimisă către browser, cererile primite către ONLYOFFICE Docs și cererile trimise, cum ar fi apelurile inverse către Nextcloud. O eroare în oricare dintre ele poate părea similară din partea utilizatorului.

Un detaliu important este important înainte de a începe să modificați setările: JWT este activat în mod implicit în ONLYOFFICE Docs încă de la versiunea 7.2 , iar serverul de documente poate genera automat un secret. Acest lucru face ca un tutorial vechi care spune „lăsați JWT dezactivat” să fie o bază nepotrivită pentru o instalare modernă. Îndrumările actuale ale ONLYOFFICE sunt să configurați propriul secret și să utilizați același secret în conector. Consultați ghidul de configurare JWT al ONLYOFFICE .

Referință rapidă: ce trebuie verificat mai întâi

1. Confirmați că secretul partajat este de fapt același

Validarea JWT depinde de un secret partajat. ONLYOFFICE Docs semnează token-uri cu acel secret, iar partea receptoră verifică semnătura folosind aceeași valoare. O diferență de un caracter, un spațiu alb la final, o variabilă de mediu veche sau un secret Docker regenerat sunt suficiente pentru ca un token care pare valid să eșueze verificarea.

Pe Nextcloud, conectorul acceptă această jwt_secretsetare. Conectorul oficial oferă și o occinterfață de configurare, astfel încât să puteți inspecta valoarea pe care Nextcloud o folosește de fapt, în loc să vă bazați pe un fișier de configurare pe care îl considerați activ. Setările actuale ale conectorului sunt documentate în fișierul oficial README al conectorului ONLYOFFICE 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

Nu lipiți secretul în tichetele de asistență, capturile de ecran, istoricul shell-ului partajat cu alții sau rapoartele publice de probleme. Comparați-l local.

Pentru o instalare nativă Linux a ONLYOFFICE Docs, fișierul de configurare acceptat este:

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE documentează setări separate pentru token-uri în browser, inbox și outbox. Valorile secrete utilizate pentru validare trebuie să fie în concordanță cu configurația conectorului. Nu editați default.json; ONLYOFFICE avertizează explicit că valorile implicite pot fi suprascrise la repornire sau la actualizare. Se utilizează local.jsonpentru instalările de pachete.

Dacă rulați ONLYOFFICE Docs în Docker

Folosiți variabile de mediu Docker în loc să editați manual local.jsonîn interiorul containerului. ONLYOFFICE afirmă că Docker poate regenera configurația JWT în timpul pornirii; imaginea sa oficială acceptă JWT_ENABLED, JWT_SECRET, JWT_HEADERși JWT_IN_BODY. Documentația actuală a imaginii Docker listează Authorizationca antet JWT implicit. Consultați repozitoriul oficial Docker DocumentServer .

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

După modificarea variabilelor de mediu Docker, recreați containerul astfel încât serviciul care rulează să le primească. Simpla editare a unui fișier Compose fără recrearea containerului nu modifică mediul său existent.

2. Faceți ca antetul JWT să se potrivească exact

O neînțelegere frecventă este că numele antetului este cosmetic. Nu este. ONLYOFFICE Docs are antete configurabile pentru token-urile Inbox și Outbox, iar conectorul Nextcloud are o jwt_headersetare. Acestea trebuie să descrie aceeași cale de solicitare.

Documentația actuală a API-ului ONLYOFFICE listează Authorizationca implicit Document Server pentru cererile JWT primite, iar documentația oficială de integrare Nextcloud identifică, de asemenea, Authorizationca implicit normal conectorul. Exemplele mai vechi și instalările existente pot utiliza AuthorizationJWTsau o altă valoare configurată explicit. Prin urmare, regula de siguranță nu este „utilizați întotdeauna un șir specific”; ci este ca configurația activă să se potrivească pe ambele părți .

Formatul cererii contează și el. Documentația API a ONLYOFFICE prezintă token-urile din antet trimise folosind schema Bearer. Pentru detalii despre protocolul subiacent, consultați documentația ONLYOFFICE token-in-header .

Dacă utilizați în mod deliberat un antet personalizat, configurați aceeași valoare în ambele produse. Dacă nu aveți niciun motiv să îl personalizați, utilizarea valorii implicite curente Authorizationreduce componentele mobile.

3. Verificați dacă un proxy invers modifică calea tokenului

Dacă setările Nextcloud și ONLYOFFICE se potrivesc, dar eroarea persistă, verificați calea dintre ele. Un proxy invers, un gateway de autentificare, un WAF sau un controler de intrare pot afecta anteturile de autorizare. Acest lucru depinde de stiva dvs., așa că nu presupuneți că proxy-ul este vinovat fără dovezi.

Folosește această secvență practică de teste:

• Confirmați că adresa URL publică a serverului de documente este accesibilă de pe gazda Nextcloud.
• Confirmați că adresa URL internă a serverului de documente, dacă este configurată, se rezolvă de pe serverul sau containerul Nextcloud.
• Confirmați că URL-ul intern Nextcloud/storage se rezolvă din gazda sau containerul ONLYOFFICE Docs.
• Inspectați jurnalele de acces/erori proxy în timp ce rulați verificarea conectorului.
• Dacă proxy-ul are reguli explicite pentru Authorization, confirmați că transmite mai departe, în loc să înlocuiască sau să elimine antetul.

Nu dezactivați JWT doar pentru a face eroarea să dispară. Aceasta elimină mecanismul de validare, în loc să îl repare. De asemenea, nu dezactivați verificarea TLS ca o soluție JWT: verificarea certificatului și validarea semnăturii JWT sunt controale separate. Dacă aveți o problemă cu certificatul, remediați lanțul de certificate sau configurația de încredere independent.

4. Folosește propria verificare a stării de funcționare a conectorului

Conectorul oficial ONLYOFFICE include o comandă de diagnosticare special concepută:

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

Documentația conectorului precizează că această verificare raportează fie o conexiune reușită, fie cauza unei erori. Este mai utilă decât testarea doar a paginii de destinație a serverului de documente, deoarece exersează integrarea din perspectiva Nextcloud.

Dacă verificarea indică faptul că serverul de documente este accesibil, dar validarea token-ului eșuează, reveniți la secret și la antet. Dacă nu poate ajunge deloc la server, rezolvați problemele legate de DNS, rutare, firewall, TLS sau URL-ul intern înainte de a petrece mai mult timp cu JWT.

5. Verificați timpul doar atunci când dovezile indică acest lucru

jwt_leewayJWT-urile pot include revendicări legate de timp și expuneri și setări ale conectorului Nextcloud jwt_expiration. Asta nu înseamnă că ar trebui să măriți mai întâi leaway-ul. Un ceas care este material greșit poate cauza eșecul unor token-uri altfel corecte; creșterea leaway-ului poate ascunde problema infrastructurii.

Comparați ora UTC pe gazdele sau containerele Nextcloud și ONLYOFFICE:

date -u
timedatectl status

Asigurați-vă că ambele sisteme sincronizează timpul în mod fiabil. Numai după confirmarea unei diferențe de ceas mici și legitime ar trebui să luați în considerare o marjă de manevră limitată îngust. Setările JWT acceptate de conector sunt listate în referința oficială de configurare a conectorului .

Cum funcționează validarea JWT în această integrare

ONLYOFFICE Docs folosește JWT pentru a proteja inițializarea editorului și cererile de la server la server. API-ul său separă token-urile de browser de token-urile de cereri HTTP primite și trimise. Pentru cererile primite, token-ul poate fi transportat într-un antet sau, pentru cererile POST acceptate, în corpul cererii. Pentru cererile GET, ONLYOFFICE documentează gestionarea token-urilor bazate pe antet. Consultați documentația oficială pentru semnătura cererilor .

Aceasta explică de ce o operație poate funcționa în timp ce o alta eșuează. De exemplu, deschiderea editorului poate reuși, în timp ce o solicitare ulterioară de apel invers sau de descărcare eșuează dacă doar o direcție are setările corecte ale token-ului.

Concepții greșite comune

„Dacă /healthcheck returnează true, JWT trebuie să fie corect.”

Nu. Un endpoint de funcționare dovedește că serviciul răspunde; nu dovedește că conectorul Nextcloud și serverul de documente partajează același secret și antet JWT. Acțiune: rulați occ onlyoffice:documentserver --checkși inspectați setările efective ale conectorului.

„Pot edita fișierul local.json într-un container Docker și gata.”

Acest lucru este fragil pentru implementările Docker. ONLYOFFICE recomandă setarea JWT prin variabilele de mediu Docker, deoarece pornirea poate regenera configurația. Acțiune: definiți JWT_ENABLED, JWT_SECRET, și , atunci când este necesar, JWT_HEADERîn configurația containerului și recreați containerul.

„AuthorizationJWT este întotdeauna antetul obligatoriu.”

Nu. Configurația oficială curentă a serverului de documente este listată Authorizationca antet implicit, deși implementările existente și exemplele mai vechi pot utiliza un alt antet configurat explicit. Acțiune: citiți ambele configurații active și faceți-le identice.

„Dezactivarea JWT este cea mai rapidă soluție.”

Poate elimina eroarea de validare imediată, dar elimină și un control de securitate și poate masca nepotrivirea subiacentă. Acțiune: remediați secretul/antetul partajat, cu excepția cazului în care aveți un motiv deliberat și documentat pentru a opera fără JWT.

Lista de verificare finală pentru validare

• Același secret JWT este configurat în Nextcloud și ONLYOFFICE Docs.
• Numele antetului JWT se potrivește pe ambele părți.
• Implementările Docker utilizează variabile de mediu persistente, nu o editare ad-hoc în interiorul containerului.
• Adresele URL ale serverului public și intern sunt accesibile în direcția în care sunt utilizate.
• Nicio regulă proxy nu elimină sau rescrie în mod neașteptat antetul JWT.
• Sistemele Nextcloud și ONLYOFFICE au ceasuri sincronizate.
• occ onlyoffice:documentserver --checkreușește.
• Un document real se deschide, editează, salvează automat, se închide și se redeschide cu modificările salvate.

Când eroarea tokenului persistă

Dacă secretele și anteturile se potrivesc, ceasurile sunt sincronizate, iar verificarea conectorului reușește, dar o operațiune specifică raportează în continuare un token nevalid. Capturați direcția exactă a solicitării eșuate și jurnalele corespunzătoare înainte de a modifica mai multe setări. ONLYOFFICE distinge validarea browserului, a inbox-ului și a outbox-ului, așa că următoarea întrebare este dacă eroarea apare în timpul inițializării editorului, a unei comenzi trimise către Document Server sau a unei apeluri inverse/descărcări trimise înapoi către Nextcloud.

Folosește jurnalele Document Server împreună cu jurnalele Nextcloud și jurnalele proxy pentru aceeași marcă temporală. Evită să postezi JWT-uri sau secrete complete public. Dacă trebuie să compari structura token-urilor, elimină semnătura și revendicările sensibile. Comportamentul de referință pentru semnare și validare este descris în documentația de semnătură ONLYOFFICE .