Los de foutmelding "Token is Not Valid" op in de ONLYOFFICE Nextcloud-integratie.

De ONLYOFFICE-melding "Token is niet geldig" betekent meestal dat de twee kanten van de integratie niet dezelfde JSON Web Token (JWT) valideren. In een Nextcloud-configuratie is het belangrijk om te weten dat er verschillende tokenpaden zijn: de editorconfiguratie die naar de browser wordt verzonden, inkomende verzoeken aan ONLYOFFICE Docs en uitgaande verzoeken zoals callbacks naar Nextcloud. Een fout in een van deze paden kan er voor de gebruiker hetzelfde uitzien.

Voordat u instellingen gaat wijzigen, is er één belangrijk detail om rekening mee te houden: JWT is sinds versie 7.2 standaard ingeschakeld in ONLYOFFICE Docs en de documentenserver kan automatisch een geheim genereren. Een oude handleiding die adviseert om JWT uit te schakelen, is daarom geen goede basis voor een moderne installatie. ONLYOFFICE adviseert momenteel om uw eigen geheim te configureren en dit geheim in de connector te gebruiken. Zie de JWT-configuratiehandleiding van ONLYOFFICE .

Snel overzicht: wat moet je als eerste controleren?

1. Controleer of het gedeelde geheim daadwerkelijk hetzelfde is.

De validatie van JWT's is afhankelijk van een gedeeld geheim. ONLYOFFICE Docs ondertekent tokens met dat geheim, en de ontvangende partij verifieert de handtekening met dezelfde waarde. Een verschil van één teken, een spatie aan het einde, een verouderde omgevingsvariabele of een opnieuw gegenereerd Docker-geheim is al voldoende om een ​​ogenschijnlijk geldig token te laten falen in de verificatie.

Op Nextcloud ondersteunt de connector deze jwt_secretinstelling. De officiële connector biedt ook een occconfiguratie-interface, zodat u de waarde kunt controleren die Nextcloud daadwerkelijk gebruikt, in plaats van te vertrouwen op een configuratiebestand waarvan u denkt dat het actief is. De huidige instellingen van de connector staan ​​beschreven in de officiële README van de ONLYOFFICE Nextcloud-connector .

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

Plak het geheim niet in supporttickets, screenshots, gedeelde shellgeschiedenis of openbare probleemrapporten. Vergelijk het lokaal.

Voor een native Linux-installatie van ONLYOFFICE Docs is het ondersteunde configuratiebestand:

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE documenteert aparte instellingen voor browser-, inbox- en outbox-tokens. De geheime waarden die voor validatie worden gebruikt, moeten overeenkomen met uw connectorconfiguratie. Bewerk deze niet default.json; ONLYOFFICE waarschuwt expliciet dat standaardinstellingen kunnen worden overschreven bij een herstart of upgrade. Gebruik deze local.jsonvoor pakketinstallaties.

Als je ONLYOFFICE Docs in Docker uitvoert

Gebruik Docker-omgevingsvariabelen in plaats van handmatig wijzigingen aan te brengen local.jsonin de container. ONLYOFFICE geeft aan dat Docker de JWT-configuratie tijdens het opstarten kan regenereren; de officiële image ondersteunt JWT_ENABLED, JWT_SECRET, JWT_HEADER, en JWT_IN_BODY. De huidige Docker-imagedocumentatie vermeldt Authorizationals de standaard JWT-header. Zie de officiële Docker DocumentServer-repository .

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

Nadat je Docker-omgevingsvariabelen hebt gewijzigd, moet je de container opnieuw aanmaken, zodat de draaiende service deze variabelen ontvangt. Het bewerken van een Compose-bestand zonder de container opnieuw aan te maken, verandert de bestaande omgeving niet.

2. Zorg ervoor dat de JWT-header exact overeenkomt.

Een veelvoorkomend misverstand is dat de headernaam slechts cosmetisch is. Dat is niet het geval. ONLYOFFICE Docs heeft configureerbare tokenheaders voor inbox en outbox, en de Nextcloud-connector heeft een jwt_headerinstelling hiervoor. Deze moeten hetzelfde aanvraagpad beschrijven.

De huidige ONLYOFFICE API-documentatie vermeldt Authorizationals de standaard Document Server voor inkomende JWT-verzoeken, en de officiële Nextcloud-integratiedocumentatie identificeert eveneens Authorizationals de normale connectorstandaard. Oudere voorbeelden en bestaande installaties gebruiken mogelijk AuthorizationJWTof een andere expliciet geconfigureerde waarde. De veilige regel is daarom niet "gebruik altijd één specifieke tekenreeks"; het is om ervoor te zorgen dat de actieve configuratie aan beide zijden overeenkomt .

Het formaat van het verzoek is ook belangrijk. De API-documentatie van ONLYOFFICE laat zien dat header-tokens worden verzonden met behulp van het Bearer-schema. Zie de ONLYOFFICE-documentatie over tokens in de header voor meer informatie over het onderliggende protocol .

Als u bewust een aangepaste header gebruikt, configureer dan dezelfde waarde in beide producten. Als er geen reden is om deze aan te passen, is het beter om de huidige standaardwaarde te gebruiken, omdat dit het Authorizationaantal variabele factoren vermindert.

3. Controleer of een reverse proxy het tokenpad wijzigt.

Als de Nextcloud- en ONLYOFFICE-instellingen overeenkomen, maar de fout blijft bestaan, controleer dan het pad ertussen. Een reverse proxy, authenticatiegateway, WAF of ingress controller kan de autorisatieheaders beïnvloeden. Dit hangt af van uw stack, dus ga er niet zomaar vanuit dat de proxy de boosdoener is zonder bewijs.

Gebruik deze praktische testreeks:

• Controleer of de openbare URL van de documentenserver bereikbaar is vanaf de Nextcloud-host.
• Controleer of de interne URL van de documentserver, indien geconfigureerd, correct wordt opgelost vanaf de Nextcloud-server of -container.
• Controleer of de interne Nextcloud/storage-URL correct wordt opgelost vanaf de ONLYOFFICE Docs-host of -container.
• Controleer de toegangs-/foutlogboeken van de proxy tijdens het uitvoeren van de connectorcontrole.
• Als uw proxy expliciete regels heeft voor Authorization, controleer dan of deze de header doorstuurt in plaats van vervangt of verwijdert.

Schakel JWT niet uit om de fout te laten verdwijnen. Daarmee wordt het validatiemechanisme verwijderd in plaats van hersteld. Schakel ook geen TLS-verificatie uit als JWT-oplossing: certificaatverificatie en JWT-handtekeningvalidatie zijn afzonderlijke controles. Als u een certificaatprobleem hebt, corrigeer dan de certificaatketen of de vertrouwensconfiguratie afzonderlijk.

4. Gebruik de eigen gezondheidscontrole van de connector.

De officiële ONLYOFFICE-connector bevat een speciaal daarvoor ontwikkelde diagnostische opdracht:

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

Volgens de documentatie van de connector rapporteert deze controle een succesvolle verbinding of de oorzaak van een fout. Dit is nuttiger dan alleen de landingspagina van de Document Server te testen, omdat de integratie vanuit het perspectief van Nextcloud wordt getest.

Als de controle aangeeft dat de documentenserver bereikbaar is, maar de tokenvalidatie mislukt, ga dan terug naar het geheim en de header. Als de server helemaal niet bereikbaar is, los dan eerst DNS-, routerings-, firewall-, TLS- of interne URL-problemen op voordat je meer tijd besteedt aan JWT.

5. Controleer de tijd alleen wanneer het bewijs daarop wijst.

JWT's kunnen tijdgerelateerde claims bevatten en de Nextcloud-connector toont jwt_leewaydeze jwt_expirationinstellingen. Dat betekent niet dat u de marge direct moet vergroten. Een klok die wezenlijk onjuist is, kan ervoor zorgen dat anderszins correcte tokens niet werken; het vergroten van de marge kan het infrastructuurprobleem maskeren.

Vergelijk de UTC-tijd op de Nextcloud- en ONLYOFFICE-hosts of -containers:

date -u
timedatectl status

Zorg ervoor dat beide systemen de tijd betrouwbaar synchroniseren. Pas nadat u een klein, legitiem klokverschil hebt bevestigd, kunt u een beperkte marge overwegen. De door de connector ondersteunde JWT-instellingen staan ​​vermeld in de officiële configuratiehandleiding van de connector .

Hoe JWT-validatie werkt in deze integratie.

ONLYOFFICE Docs gebruikt JWT om de initialisatie van de editor en server-naar-server-verzoeken te beschermen. De API scheidt browsertokens van inkomende en uitgaande HTTP-verzoektokens. Voor inkomende verzoeken kan het token in een header worden meegestuurd of, voor ondersteunde POST-verzoeken, in de body van het verzoek. Voor GET-verzoeken beschrijft ONLYOFFICE de verwerking van tokens via de header. Zie de officiële documentatie over verzoeksignaturen .

Dit verklaart waarom de ene bewerking wel werkt en de andere niet. Het openen van de editor kan bijvoorbeeld lukken, terwijl een latere callback of downloadaanvraag mislukt als slechts één van beide richtingen de juiste tokeninstellingen heeft.

Veelvoorkomende misvattingen

"Als /healthcheck true retourneert, moet de JWT correct zijn."

Nee. Een health endpoint bewijst dat de service reageert; het bewijst niet dat de Nextcloud-connector en de Document Server hetzelfde JWT-geheim en dezelfde header delen. Actie: voer de test uit occ onlyoffice:documentserver --checken controleer de effectieve connectorinstellingen.

“Ik kan local.json bewerken in een Docker-container en klaar is Kees.”

Dat is een kwetsbaar punt voor Docker-implementaties. ONLYOFFICE raadt aan om JWT via Docker-omgevingsvariabelen in te stellen, omdat de configuratie bij het opstarten opnieuw kan worden gegenereerd. Actie: definieer JWT_ENABLED, JWT_SECRET, en, indien nodig, JWT_HEADERin uw containerconfiguratie en maak de container opnieuw aan.

"AuthorizationJWT is altijd de vereiste header."

Nee. De huidige officiële configuratie van de documentserver vermeldt Authorizationals standaardheader, hoewel bestaande implementaties en oudere voorbeelden mogelijk een andere, expliciet geconfigureerde header gebruiken. Actie: lees beide actieve configuraties en zorg dat ze identiek zijn.

"JWT uitschakelen is de snelste oplossing."

Het kan de directe validatiefout verhelpen, maar het verwijdert ook een beveiligingsmaatregel en kan de onderliggende discrepantie maskeren. Actie: corrigeer het gedeelde geheim/de header, tenzij u een bewuste, gedocumenteerde reden hebt om zonder JWT te werken.

Definitieve validatiechecklist

• Hetzelfde JWT-geheim wordt geconfigureerd in Nextcloud en de OnlyOffice-documentatie.
• De JWT-headernaam komt aan beide zijden overeen.
• Docker-implementaties maken gebruik van permanente omgevingsvariabelen, niet van een ad-hocwijziging binnen de container.
• De openbare en interne server-URL's zijn bereikbaar in de richting waarin ze worden gebruikt.
• Geen enkele proxyregel verwijdert of herschrijft onverwacht de JWT-header.
• De Nextcloud- en ONLYOFFICE-systemen hebben gesynchroniseerde klokken.
• occ onlyoffice:documentserver --checkslaagt.
• Een echt document wordt geopend, bewerkt, automatisch opgeslagen, gesloten en opnieuw geopend met de opgeslagen wijzigingen.

Als de tokenfout nog steeds aanwezig is

Als de geheimen en headers overeenkomen, de klokken gesynchroniseerd zijn en de connectorcontrole slaagt, maar een specifieke bewerking nog steeds een ongeldig token rapporteert, leg dan de exacte richting van het mislukte verzoek en de bijbehorende logboeken vast voordat u verdere instellingen wijzigt. ONLYOFFICE maakt onderscheid tussen validatie in de browser, inbox en outbox, dus de volgende vraag is of de fout optreedt tijdens de initialisatie van de editor, een opdracht die naar de documentenserver wordt verzonden of een callback/download die naar Nextcloud wordt teruggestuurd.

Gebruik de logbestanden van de documentenserver samen met de Nextcloud-logbestanden en proxy-logbestanden voor hetzelfde tijdstempel. Vermijd het openbaar maken van volledige JWT's of geheimen. Als u de tokenstructuur wilt vergelijken, moet u de handtekening en gevoelige claims anonimiseren. Het referentiegedrag voor ondertekening en validatie wordt beschreven in de documentatie over handtekeningen van ONLYOFFICE .