Beheben des ONLYOFFICE-Fehlers „Token ist ungültig“ in Nextcloud

Wenn Nextcloud beim Verbindungsaufbau zu ONLYOFFICE Docs die Fehlermeldung „Token ungültig“ meldet, stellen Sie sicher, dass das JWT-Secret des Connectors mit dem Secret des Dokumentenservers übereinstimmt. In ONLYOFFICE Docs 7.2 und höher ist die JWT-Validierung standardmäßig aktiviert und ein Secret wird automatisch generiert. Änderungen an den Nextcloud-Einstellungen oder an der Konfigurationsdatei eines Docker-Containers können zu Inkonsistenzen zwischen den beiden Systemen führen.

Lassen Sie JWT aktiviert. Ermitteln Sie zunächst das aktive Geheimnis und den Bereitstellungstyp, aktualisieren Sie die korrekte Konfiguration und führen Sie anschließend die Verbindungsprüfung des Connectors aus. Die Prüfung sollte eine erfolgreiche Verbindung melden; das bloße Öffnen des Browser-Editors beweist nicht, dass Dokument-Downloads und Rückrufe funktionieren.

Was sagt Ihnen die Fehlermeldung?

JWT (JSON Web Token) ist ein signiertes Token, das die Vertrauenswürdigkeit einer Anfrage zwischen Nextcloud und ONLYOFFICE Docs überprüft. Der Connector signiert Anfragen mit seinem konfigurierten Geheimnis, während der Dokumentenserver sie mit seinem ebenfalls konfigurierten Geheimnis validiert. Stimmen die Signaturgeheimnisse nicht überein, kann die Token-Signatur nicht validiert werden und die Anfrage wird abgelehnt.

Die häufigsten Ursachen sind ein aus einer alten Installation kopiertes Geheimnis, ein automatisch generiertes Geheimnis, das nie in Nextcloud eingegeben wurde, eine geänderte Docker-Umgebungsvariable, die beim Neuerstellen des Containers nicht angewendet wurde, oder inkonsistente Geheimniswerte in der Konfiguration des Dokumentenservers. Auch ein benutzerdefinierter JWT-Header kann zu einer Diskrepanz führen, wenn Connector und Dokumentenserver nicht denselben Headernamen verwenden.

Dieser Artikel behandelt JWT-Fehler. Sollte die Fehlermeldung stattdessen besagen, dass der Server nicht erreichbar ist, das Zertifikat ungültig ist oder ein Dokument nicht heruntergeladen werden kann, überprüfen Sie die Serveradressen, das TLS-Zertifikat und den Netzwerkpfad zwischen Nextcloud und dem Dokumentserver separat. Eine JWT-Korrektur behebt diese Probleme nicht.

1. Ermitteln Sie das aktive Geheimnis des Dokumentenservers.

Verwenden Sie die Konfiguration des laufenden Dokumentenservers. Gehen Sie nicht davon aus, dass ein von einem vorherigen Container oder Server gespeichertes Geheimnis noch aktiv ist.

• Linux: inspect /etc/onlyoffice/documentserver/local.json.
• Windows: überprüfen %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json.
• Docker: Lesen Sie das Secret aus dem laufenden Container. Das offizielle Image unterstützt ebenfalls das Lesen des Session-Secrets mit diesem Befehl:

sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

Ersetzen Sie dies <containerID>durch den tatsächlichen Containernamen oder die ID. Behandeln Sie den zurückgegebenen Wert als Anmeldeinformation: Fügen Sie ihn nicht in Supportforen, Screenshots oder öffentliche Protokolle ein.

Vergleichen Sie in der Datei local.jsondie Werte in den Feldern services.CoAuthoring.secret.inbox.string, services.CoAuthoring.secret.outbox.string, und services.CoAuthoring.secret.session.string. Bei dieser Standardkonfiguration sollten alle Werte identisch sein. Stellen Sie außerdem sicher, dass die Token-Validierung für Browser, Anfrage-Posteingang und Anfrage-Postausgang aktiviert ist. In Dokumentationsversionen vor 7.2 muss die Token-Validierung explizit aktiviert werden; in späteren Versionen ist sie standardmäßig aktiviert.

2. Aktualisieren Sie den ONLYOFFICE-Connector von Nextcloud.

1. Melden Sie sich als Nextcloud-Administrator an und öffnen Sie Einstellungen > Administration > ONLYOFFICE .
2. Geben Sie in den Servereinstellungen im Feld „Geheimer Schlüssel“ den exakten Schlüssel des laufenden Dokumentenservers ein . Vermeiden Sie führende und nachfolgende Leerzeichen und verwenden Sie keine Anführungszeichen, es sei denn, diese sind Bestandteil des Schlüssels selbst.
3. Überprüfen Sie die JWT-Header-Einstellungen, falls Ihre Bereitstellung einen benutzerdefinierten Header verwendet. Die Einstellungen des Connectors jwt_headerund der konfigurierte Token-Header des Dokumentenservers müssen übereinstimmen. Wenn Sie den Header nicht absichtlich angepasst haben, ändern Sie ihn im Rahmen dieser Reparatur nicht.
4. Einstellungen speichern. JWT auf beiden Seiten aktiviert lassen.

Die dokumentierte Konnektoreinstellung kann auch mit dem Nextcloud- occBefehl aus dem Nextcloud-Installationsverzeichnis geändert werden:

sudo -u www-data php occ config:app:set onlyoffice jwt_secret --value='YOUR_SECRET'

Ersetzen Sie YOUR_SECRETden Platzhalter durch den tatsächlichen Wert. Die Verwendung von Anführungszeichen in der Shell hilft, die Interpunktion zu erhalten. Geheimnisse, die ein einzelnes Anführungszeichen enthalten, erfordern jedoch eine sicherere Methode als die direkte Eingabe in die Befehlszeile. Befehlszeilenargumente können zudem für privilegierte Prozesse oder die Shell-Historie sichtbar sein. Verwenden Sie nach Möglichkeit die Administratorschnittstelle und überprüfen Sie den gespeicherten Wert, ohne ihn preiszugeben.

3. Wenden Sie die Änderung auf die für Ihre Installation richtige Weise an.

Docker oder Docker Compose

Bei Docker-Bereitstellungen konfigurieren Sie JWT über die Containerumgebung, anstatt die automatisch generierte Datei manuell zu bearbeiten local.json. Legen Sie dasselbe Geheimnis in der Dienstdefinition des Dokumentenservers fest:

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

Nach der Änderung der Compose-Datei muss der Document Server-Container neu erstellt werden, damit die Umgebungsänderungen wirksam werden. Zum Beispiel aus dem Verzeichnis, das die Compose-Datei enthält:

docker compose up -d --force-recreate <documentserver-service>

Ersetzen Sie den Dienstnamen durch den Namen aus Ihrer Compose-Datei. Ein einfacher Neustart wendet geänderte Umgebungsvariablen nicht auf einen bestehenden Container an. Wenn Sie `compose up` verwenden docker run, erstellen Sie den Container mit den aktualisierten Werten neu JWT_ENABLEDund JWT_SECRETbehalten Sie dabei die vorhandenen Ports, Volumes und andere erforderliche Optionen bei. Löschen Sie keinen Produktionscontainer, bevor Sie diese Einstellungen und die persistenten Dateneinbindungen bestätigt haben.

Lesen Sie nach dem Start des Containers dessen aktives Geheimnis mit dem oben genannten Befehl erneut ein und stellen Sie sicher, dass der Wert weiterhin mit Nextcloud übereinstimmt. Vermeiden Sie es, ein Produktionsgeheimnis in einer öffentlich zugänglichen Compose-Datei oder einem Quellcode-Repository zu speichern.

Linux-Paket oder Windows-Installation

Wenn Sie absichtlich ein benutzerdefiniertes Geheimnis festlegen local.json, stellen Sie sicher, dass die drei Geheimnisfelder übereinstimmen und die erforderlichen Token-Validierungswerte aktiviert sind. Wenden Sie die Änderung an, indem Sie die entsprechenden Dokumentenserverdienste neu starten. Die aktuelle ONLYOFFICE-Anleitung listet unter Linux die Neustartmethoden `<service>` ds-converter, ds-docservice`<service>` und ` ds-metrics<service>` auf. Installationen, die von einem anderen Dienstverwalter betreut werden, erfordern möglicherweise die für diese Konfiguration geeignete Neustartmethode. Unter Windows starten Sie die ONLYOFFICE-Dienste nach dem Speichern der Konfiguration neu.

Eine nach dem Neustart weiterhin bestehende Diskrepanz bedeutet in der Regel, dass eine generierte Konfiguration oder Bereitstellungsumgebung die bearbeitete Datei überschreibt. Bei Docker verschieben Sie die Korrektur in die Umgebungsvariablen und erstellen den Container neu. Bei paketierten Bereitstellungen überprüfen Sie die aktive Konfiguration und die Startkonfiguration des Dienstes, bevor Sie weitere Einstellungen ändern.

Überprüfen Sie die Reparatur

1. Führen Sie im Nextcloud-Installationsverzeichnis die offizielle Connector-Prüfung durch:

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

Verwenden Sie das für Ihre Installation passende Webserver-Konto, falls es nicht bereits vorhanden ist www-data. Der Befehl sollte eine erfolgreiche Verbindung melden. Falls weiterhin ein ungültiges Token gemeldet wird, überprüfen Sie erneut, ob das aktive Geheimnis des laufenden Dokumentenservers exakt mit Nextcloud übereinstimmt und ob alle benutzerdefinierten JWT-Header übereinstimmen.

2. Öffnen Sie ein kleines Testdokument aus Nextcloud mit ONLYOFFICE. Prüfen Sie, ob der Editor geladen wird, nehmen Sie eine kleine Änderung vor, speichern Sie die Datei, schließen Sie den Editor und öffnen Sie die Datei erneut, um zu überprüfen, ob die Änderung übernommen wurde.
3. Wenn die Prüfung nun einen Netzwerk- oder Zertifikatsfehler meldet, ändern Sie keine JWT-Werte mehr. Stellen Sie sicher, dass Nextcloud die Adresse des Dokumentenservers und der Dokumentenserver die Nextcloud-Callback-Adresse erreichen kann. Verwenden Sie nach Möglichkeit ein vertrauenswürdiges TLS-Zertifikat; die Deaktivierung der Zertifikatsprüfung ist eine unsichere Notlösung und behebt das Problem der Token-Validierung nicht.

Diese Prüfungen stellen sicher, dass die konfigurierte Verbindung und ein grundlegender Speicherpfad funktionieren. Sie beweisen jedoch nicht, dass jede Reverse-Proxy-Route, externe Speicherkonfiguration oder Multi-Server-Topologie korrekt ist; testen Sie diese Pfade separat, falls Ihre Bereitstellung sie verwendet.

Offizielle Referenzen

• ONLYOFFICE: Nextcloud-Integration und JWT-Einrichtung
• ONLYOFFICE: JWT für den Dokumentenserver konfigurieren
• ONLYOFFICE Nextcloud-Connector: Konfigurationsoptionen und occ-Befehle

Die Konfigurationsdetails wurden am 9. Oktober 2026 anhand der offiziellen ONLYOFFICE-Dokumentation und des Connector-Repositorys überprüft. UI-Bezeichnungen und Service-Management können je nach Connector, Betriebssystem und Bereitstellungsmethode variieren.