Behebung des Fehlers „Token ist ungültig“ in der ONLYOFFICE Nextcloud-Integration

Die ONLYOFFICE-Meldung „Token ist ungültig“ bedeutet in der Regel, dass die beiden Seiten der Integration nicht dasselbe JSON Web Token (JWT) validieren. In einer Nextcloud-Umgebung ist zu beachten, dass mehrere Token-Pfade existieren: die an den Browser gesendete Editorkonfiguration, eingehende Anfragen an ONLYOFFICE Docs und ausgehende Anfragen wie Rückrufe an Nextcloud. Ein Fehler in einem dieser Pfade kann für den Benutzer ähnliche Symptome hervorrufen.

Bevor Sie Einstellungen ändern, ist ein wichtiger Punkt zu beachten: JWT ist in ONLYOFFICE Docs seit Version 7.2 standardmäßig aktiviert , und der Dokumentenserver kann automatisch ein Geheimnis generieren. Daher ist eine ältere Anleitung, die empfiehlt, JWT deaktiviert zu lassen, für eine moderne Installation nicht mehr zielführend. ONLYOFFICE empfiehlt aktuell, ein eigenes Geheimnis zu konfigurieren und dieses im Connector zu verwenden. Weitere Informationen finden Sie im JWT-Konfigurationsleitfaden von ONLYOFFICE .

Kurzübersicht: Was Sie zuerst überprüfen sollten

1. Bestätigen Sie, dass das gemeinsame Geheimnis tatsächlich dasselbe ist.

Die JWT-Validierung basiert auf einem gemeinsamen Geheimnis. ONLYOFFICE Docs signiert Tokens mit diesem Geheimnis, und der Empfänger überprüft die Signatur mit demselben Wert. Schon ein einziges abweichendes Zeichen, ein nachfolgendes Leerzeichen, eine veraltete Umgebungsvariable oder ein neu generiertes Docker-Geheimnis reichen aus, um die Überprüfung eines scheinbar gültigen Tokens fehlschlagen zu lassen.

Nextcloud unterstützt diese jwt_secretEinstellung. Der offizielle Connector bietet zudem eine occKonfigurationsoberfläche, sodass Sie den von Nextcloud tatsächlich verwendeten Wert überprüfen können, anstatt sich auf eine vermeintlich aktive Konfigurationsdatei zu verlassen. Die aktuellen Einstellungen des Connectors sind in der offiziellen README-Datei des ONLYOFFICE Nextcloud Connectors dokumentiert .

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

Fügen Sie das Geheimnis nicht in Support-Tickets, Screenshots, Shell-Verläufe, die Sie mit anderen teilen, oder öffentliche Fehlerberichte ein. Vergleichen Sie es lokal.

Für eine native Linux-Installation von ONLYOFFICE Docs wird folgende Konfigurationsdatei unterstützt:

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE dokumentiert separate Einstellungen für Browser-, Posteingangs- und Postausgangstoken. Die zur Validierung verwendeten geheimen Werte müssen mit Ihrer Connector-Konfiguration übereinstimmen. Bearbeiten Sie diese Einstellungen nicht default.json; ONLYOFFICE weist ausdrücklich darauf hin, dass Standardwerte beim Neustart oder Upgrade überschrieben werden können. Verwenden Sie diese local.jsonEinstellungen für Paketinstallationen.

Wenn Sie ONLYOFFICE Docs in Docker ausführen

Verwenden Sie Docker-Umgebungsvariablen anstatt die Konfiguration manuell local.jsonim Container zu bearbeiten. ONLYOFFICE gibt an, dass Docker die JWT-Konfiguration beim Start neu generieren kann; das offizielle Image unterstützt `JWT` JWT_ENABLED, JWT_SECRET`JWT`, JWT_HEADER`JWT` und `JWT` JWT_IN_BODY. Die aktuelle Docker-Image-Dokumentation führt `JWT` Authorizationals Standard-JWT-Header auf. Siehe das offizielle Docker DocumentServer-Repository .

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

Nach dem Ändern von Docker-Umgebungsvariablen muss der Container neu erstellt werden, damit der laufende Dienst die Änderungen erhält. Das bloße Bearbeiten einer Compose-Datei ohne Neuerstellung des Containers ändert die bestehende Umgebung nicht.

2. Stellen Sie sicher, dass der JWT-Header exakt übereinstimmt.

Ein häufiges Missverständnis ist, dass der Headername nur kosmetisch sei. Das ist er nicht. ONLYOFFICE Docs bietet konfigurierbare Token-Header für Posteingang und Postausgang, und der Nextcloud-Connector verfügt über eine jwt_headerentsprechende Einstellung. Beide müssen denselben Anfragepfad beschreiben.

Die aktuelle ONLYOFFICE-API-Dokumentation führt Authorizationals Standardwert für eingehende JWT-Anfragen den Dokumentenserver auf, und auch die offizielle Nextcloud-Integrationsdokumentation nennt ihn Authorizationals Standardwert für den normalen Connector. Ältere Beispiele und bestehende Installationen verwenden möglicherweise AuthorizationJWTeinen anderen explizit konfigurierten Wert. Die sichere Regel lautet daher nicht „immer eine bestimmte Zeichenfolge verwenden“, sondern vielmehr, die aktive Konfiguration auf beiden Seiten anzupassen .

Das Anfrageformat ist ebenfalls wichtig. Die API-Dokumentation von ONLYOFFICE zeigt, dass Header-Tokens mithilfe des Bearer-Schemas gesendet werden. Details zum zugrundeliegenden Protokoll finden Sie in der Dokumentation zu Tokens im Header von ONLYOFFICE .

Wenn Sie bewusst einen benutzerdefinierten Header verwenden, konfigurieren Sie denselben Wert in beiden Produkten. Wenn Sie keinen Grund zur Anpassung haben, Authorizationreduziert die Verwendung des aktuellen Standardwerts den Aufwand.

3. Prüfen Sie, ob ein Reverse-Proxy den Token-Pfad ändert.

Wenn die Einstellungen von Nextcloud und ONLYOFFICE übereinstimmen, der Fehler aber weiterhin besteht, überprüfen Sie den Pfad zwischen den Systemen. Ein Reverse-Proxy, ein Authentifizierungs-Gateway, eine Web Application Firewall (WAF) oder ein Ingress-Controller kann die Autorisierungs-Header beeinflussen. Dies hängt von Ihrer Systemarchitektur ab; gehen Sie daher nicht ohne Beweise davon aus, dass der Proxy die Ursache ist.

Nutzen Sie diese praktische Testsequenz:

• Prüfen Sie, ob die öffentliche Dokumentenserver-URL vom Nextcloud-Host aus erreichbar ist.
• Prüfen Sie, ob die interne Dokumentenserver-URL, sofern konfiguriert, vom Nextcloud-Server oder -Container aufgelöst wird.
• Prüfen Sie, ob die interne Nextcloud/Speicher-URL vom ONLYOFFICE Docs-Host oder -Container aufgelöst werden kann.
• Prüfen Sie die Proxy-Zugriffs-/Fehlerprotokolle während der Konnektorprüfung.
• Wenn Ihr Proxy explizite Regeln für Authorizationden Header hat, vergewissern Sie sich, dass er ihn weiterleitet und nicht ersetzt oder entfernt.

Deaktivieren Sie JWT nicht, nur um den Fehler zu beheben. Dadurch wird der Validierungsmechanismus außer Kraft gesetzt, anstatt ihn zu reparieren. Deaktivieren Sie auch nicht die TLS-Verifizierung, um JWT zu beheben: Zertifikatsverifizierung und JWT-Signaturvalidierung sind separate Kontrollmechanismen. Wenn Sie ein Zertifikatsproblem haben, korrigieren Sie die Zertifikatskette oder die Vertrauenskonfiguration separat.

4. Verwenden Sie die eigene Integritätsprüfung des Konnektors.

Der offizielle ONLYOFFICE-Connector enthält einen speziell entwickelten Diagnosebefehl:

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

Laut der Dokumentation des Konnektors meldet diese Prüfung entweder eine erfolgreiche Verbindung oder die Ursache eines Fehlers. Sie ist aussagekräftiger als die alleinige Prüfung der Startseite des Dokumentenservers, da sie die Integration aus der Perspektive von Nextcloud testet.

Wenn die Prüfung ergibt, dass der Dokumentenserver erreichbar ist, die Tokenvalidierung aber fehlschlägt, kehren Sie zum Geheimnis und Header zurück. Wenn der Server überhaupt nicht erreichbar ist, beheben Sie DNS-, Routing-, Firewall-, TLS- oder interne URL-Probleme, bevor Sie weitere Zeit in JWT investieren.

5. Überprüfen Sie die Zeit nur dann, wenn die Beweislage darauf hindeutet.

JWTs können zeitbezogene Angaben enthalten, und der Nextcloud-Connector legt jwt_leewayentsprechende jwt_expirationEinstellungen offen. Das bedeutet jedoch nicht, dass Sie den Toleranzbereich zuerst erhöhen sollten. Eine wesentlich fehlerhafte Uhrzeit kann dazu führen, dass ansonsten korrekte Token fehlschlagen; eine Erhöhung des Toleranzbereichs kann das Infrastrukturproblem verschleiern.

Vergleichen Sie die UTC-Zeit auf den Nextcloud- und ONLYOFFICE-Hosts bzw. -Containern:

date -u
timedatectl status

Stellen Sie sicher, dass beide Systeme die Zeit zuverlässig synchronisieren. Erst nach Bestätigung einer kleinen, legitimen Zeitdifferenz sollten Sie eine geringe Toleranz in Betracht ziehen. Die vom Konnektor unterstützten JWT-Einstellungen sind in der offiziellen Konfigurationsreferenz des Konnektors aufgeführt .

Wie die JWT-Validierung in dieser Integration funktioniert

ONLYOFFICE Docs verwendet JWT zum Schutz der Editorinitialisierung und von Server-zu-Server-Anfragen. Die API trennt Browser-Token von eingehenden und ausgehenden HTTP-Anfrage-Token. Bei eingehenden Anfragen kann das Token im Header oder, bei unterstützten POST-Anfragen, im Anfragetext übertragen werden. Für GET-Anfragen dokumentiert ONLYOFFICE die headerbasierte Token-Verarbeitung. Siehe die offizielle Dokumentation zur Anfragesignatur .

Dies erklärt, warum ein Vorgang funktionieren kann, ein anderer jedoch fehlschlägt. Beispielsweise kann das Öffnen des Editors erfolgreich sein, während ein späterer Rückruf oder eine Download-Anfrage fehlschlägt, wenn nur eine Richtung die korrekten Token-Einstellungen aufweist.

Häufige Missverständnisse

„Wenn /healthcheck true zurückgibt, muss JWT korrekt sein.“

Nein. Ein Health-Endpunkt beweist lediglich, dass der Dienst antwortet; er beweist aber nicht, dass der Nextcloud-Connector und der Dokumentenserver dasselbe JWT-Secret und denselben JWT-Header verwenden. Maßnahme: Führen Sie den occ onlyoffice:documentserver --checkConnector aus und überprüfen Sie die effektiven Einstellungen.

„Ich kann die Datei local.json innerhalb eines Docker-Containers bearbeiten und bin damit fertig.“

Dies ist bei Docker-Bereitstellungen problematisch. ONLYOFFICE empfiehlt, JWT über Docker-Umgebungsvariablen zu setzen, da der Startvorgang die Konfiguration neu generieren kann. Maßnahme: Definieren Sie JWT_ENABLED`<jwt-config-config>`, JWT_SECRET`<jwt-config-config>` und gegebenenfalls ` JWT_HEADER<jwt-config-config>` in Ihrer Containerkonfiguration und erstellen Sie den Container neu.

„AuthorizationJWT ist immer der erforderliche Header.“

Nein. Die aktuelle offizielle Konfiguration des Dokumentenservers führt Authorizationdiesen Header als Standard auf, obwohl bestehende Installationen und ältere Beispiele möglicherweise einen anderen, explizit konfigurierten Header verwenden. Maßnahme: Lesen Sie beide aktiven Konfigurationen und gleichen Sie sie an.

„Das Deaktivieren von JWT ist die schnellste Lösung.“

Dadurch wird zwar der unmittelbare Validierungsfehler behoben, aber gleichzeitig eine Sicherheitskontrolle aufgehoben und die zugrundeliegende Diskrepanz verschleiert. Handlungsempfehlung: Korrigieren Sie das gemeinsame Geheimnis/den Header, es sei denn, Sie haben einen triftigen, dokumentierten Grund, ohne JWT zu arbeiten.

Checkliste für die abschließende Validierung

• Derselbe JWT-Secret ist in Nextcloud und ONLYOFFICE Docs konfiguriert.
• Der Name des JWT-Headers stimmt auf beiden Seiten überein.
• Docker-Deployments verwenden persistente Umgebungsvariablen, keine Ad-hoc-Änderung innerhalb des Containers.
• Die öffentlichen und internen Server-URLs sind in der Richtung erreichbar, in der sie verwendet werden.
• Keine Proxy-Regel entfernt oder überschreibt unerwartet den JWT-Header.
• Die Systeme Nextcloud und ONLYOFFICE verfügen über synchronisierte Uhren.
• occ onlyoffice:documentserver --checkgelingt.
• Ein echtes Dokument wird geöffnet, bearbeitet, automatisch gespeichert, geschlossen und mit den gespeicherten Änderungen wieder geöffnet.

Wenn der Token-Fehler weiterhin besteht

Wenn die Geheimnisse und Header übereinstimmen, die Uhren synchronisiert sind und die Verbindungsprüfung erfolgreich war, aber eine bestimmte Operation dennoch ein ungültiges Token meldet, erfassen Sie die genaue Richtung der fehlerhaften Anfrage und die zugehörigen Protokolle, bevor Sie weitere Einstellungen ändern. ONLYOFFICE unterscheidet zwischen Browser-, Posteingangs- und Postausgangsvalidierung. Daher ist die nächste Frage, ob der Fehler bei der Initialisierung des Editors, einem an den Dokumentenserver gesendeten Befehl oder einem an Nextcloud zurückgesendeten Callback/Download auftritt.

Verwenden Sie die Protokolle des Dokumentenservers zusammen mit den Nextcloud- und Proxy-Protokollen für denselben Zeitstempel. Vermeiden Sie die öffentliche Veröffentlichung vollständiger JWTs oder Geheimnisse. Wenn Sie die Tokenstruktur vergleichen müssen, schwärzen Sie die Signatur und sensible Angaben. Das Referenzverhalten für Signierung und Validierung ist in der Signaturdokumentation von ONLYOFFICE beschrieben .