So konfigurieren Sie die JWT-Geheimschlüsselauthentifizierung von ONLYOFFICE

Die ONLYOFFICE-JWT-Authentifizierung funktioniert nur, wenn der Dokumentenserver und die integrierende Anwendung denselben geheimen Schlüssel verwenden. Bei aktuellen Docker-Bereitstellungen ist die JWT-Validierung standardmäßig aktiviert. Für eine stabile Integration sollten Sie einen eigenen, persistenten Schlüssel festlegen, JWT_SECRETanstatt sich auf den automatisch vom Container generierten Wert zu verlassen. Konfigurieren Sie anschließend denselben geheimen Schlüssel in Nextcloud, Ihrem benutzerdefinierten Dokumentenmanager oder dem jeweiligen Connector, der mit ONLYOFFICE Docs kommuniziert.

Diese praktische Referenz konzentriert sich auf die Konfigurationen, die Sie am ehesten benötigen: Docker und Docker Compose, benutzerdefinierte Integrationen zur Signierung der Editorkonfiguration, Header-/Body-Verhalten, Verifizierung, Rotation und häufige Fehler. Sie basiert auf der aktuellen ONLYOFFICE-Dokumentation (Stand: Oktober 2026).

Kurzübersicht

Ab ONLYOFFICE Docs 7.2 ist JWT bei Docker-Bereitstellungen standardmäßig aktiviert. Wird kein Geheimnis angegeben, wird automatisch ein zufälliges Geheimnis generiert. Die offizielle Docker-Dokumentation weist darauf hin, dass sich ein automatisch generiertes Geheimnis nach einem Neustart oder der Neuerstellung eines Containers ändern und Integrationen beeinträchtigen kann. Für jede produktive Bereitstellung sollte daher ein explizites Geheimnis festgelegt werden. Weitere Informationen finden Sie unter „JWT für ONLYOFFICE Docs konfigurieren“ und im offiziellen Docker-Installationshandbuch .

1. Identifizieren Sie den ONLYOFFICE-Container und die Bereitstellungsmethode.

Für einen Docker-Host beginnen Sie mit Folgendem:

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

Ermitteln Sie, ob die Instanz mit Docker Compose, einem Control Panel oder einer anderen Orchestrierungsebene gestartet wurde docker run. Sie müssen die Quellkonfiguration ändern, die den Container erstellt. Das Bearbeiten einer generierten Datei innerhalb des Containers ist keine dauerhafte Lösung.

Speziell für Docker empfiehlt ONLYOFFICE Administratoren, Umgebungsvariablen zu verwenden, anstatt die Konfigurationsdatei manuell zu bearbeiten /etc/onlyoffice/documentserver/local.json. Werden JWT-Werte direkt in dieser Datei bearbeitet, kann der Docker-Startprozess sie beim Neustart des Containers wiederherstellen oder neu generieren.

2. Generieren Sie ein starkes Geheimnis und bewahren Sie es sicher auf.

Ein praktischer Shell-Befehl lautet:

openssl rand -hex 32

Dies erzeugt 32 zufällige Bytes, dargestellt als 64 Hexadezimalzeichen. ONLYOFFICE benötigt dieses Format nicht exakt; wichtig ist, dass beide Seiten dasselbe Geheimnis kennen und dass dieses schwer zu erraten ist.

Behandeln Sie es JWT_SECRETwie ein Passwort oder API-Zugangsdaten:

• Bitte nicht in ein öffentliches Git-Repository einchecken.
• Fügen Sie es nicht in den an die Browser ausgelieferten Frontend-JavaScript-Code ein.
• Beschränken Sie den Zugriff auf die Compose-Umgebungsdatei oder den geheimen Speicher, der diese enthält.
• Verwenden Sie für verschiedene Umgebungen wie Produktion und Staging unterschiedliche Geheimnisse.

Die Signaturdokumentation von ONLYOFFICE weist ausdrücklich darauf hin, dass die Token-Signatur serverseitig erfolgen muss, da jeglicher browserseitiger Code, der das Geheimnis enthält, dieses für Benutzer offenlegt. Die offiziellen Beispiele verwenden HMAC-SHA256 ( HS256). Siehe ONLYOFFICE JWT-Signaturdokumentation .

3. JWT in Docker Compose konfigurieren

Ein minimaler Compose-Dienst kann Folgendes umfassen:

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"

Das eigentliche Geheimnis sollte nach Möglichkeit außerhalb der Compose-Datei aufbewahrt werden. Beispielsweise in einer .envDatei mit Zugriffsbeschränkungen:

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

Stellen Sie anschließend sicher, dass diese Datei von der Versionskontrolle ausgeschlossen ist und nur von den Administratoren oder dem Dienstkonto gelesen werden kann, das sie benötigt.

Das offizielle ONLYOFFICE Docker-DocumentServer-Repository dokumentiert JWT_ENABLED, JWT_SECRET, JWT_HEADER, und JWT_IN_BODY. Der aktuelle Docker-Startcode aktiviert standardmäßig die JWT-Validierung, verwendet Authorizationals Standardheader und generiert ein zufälliges Geheimnis, wenn kein explizites angegeben wird.

4. Erstellen Sie den Container neu, damit die neue Umgebung angewendet wird.

Für Compose:

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

Für einen ursprünglich mit JWT erstellten Container docker runempfiehlt die offizielle JWT-Anleitung, den alten Container zu stoppen und zu entfernen und anschließend einen neuen mit den JWT-Umgebungsvariablen zu erstellen. Dabei dürfen keine persistenten Volumes oder eingebundenen Daten entfernt werden.

Sie können die Umgebung des laufenden Containers auch untersuchen, ohne das Geheimnis selbst auszugeben:

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

Falls der Containername abweicht, ersetzen Sie ihn onlyoffice-documentserverentsprechend.

5. Konfigurieren Sie dasselbe Geheimnis in der Integration.

Dieser Schritt wird am häufigsten übersehen. Die Aktivierung von JWT in ONLYOFFICE Docs ohne entsprechende Konfiguration der Dokumentenverwaltung führt zu abgelehnten Editoranfragen. Der Connector oder die benutzerdefinierte Anwendung muss Anfragen mit exakt demselben Geheimnis signieren.

Nextcloud-Beispiel

Geben Sie in den ONLYOFFICE-Einstellungen für Nextcloud denselben geheimen Schlüssel ein, der auch vom Dokumentenserver verwendet wird. Der Headername muss ebenfalls übereinstimmen. Die aktuelle Dokumentation zur Nextcloud-Integration von ONLYOFFICE listet `<key>` jwt_secretund jwt_header`<key>` als Konnektoreinstellungen auf, wobei ` Authorization<key>` der Standardheader ist. Weitere Informationen finden Sie in der offiziellen Nextcloud-Konnektordokumentation .

Wenn Ihr Konnektor ein Feld mit der Bezeichnung „Geheimer Schlüssel“, „JWT-Geheimnis“ oder Ähnlichem besitzt, generieren Sie dort kein zweites, unabhängiges Geheimnis. Kopieren Sie stattdessen denselben Geheimniswert.

6. Für eine benutzerdefinierte Integration signieren Sie die vollständige Editorkonfiguration auf dem Server.

Bei einer benutzerdefinierten Anwendung erstellen Sie zuerst die Editorkonfiguration, signieren diese Konfiguration im Backend und weisen dann das resultierende JWT der obersten tokenEigenschaft zu.

Node.js-Beispiel:

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

Die Dokumentation zur Browsersignatur von ONLYOFFICE besagt, dass die Token-Payload zum Öffnen einer Datei dieselbe Struktur wie die Editorkonfiguration aufweisen muss. Seit Version 7.1 ist der Satz der Validierungsparameter für diesen Vorgang streng reglementiert, weshalb das Signieren einer veralteten oder unvollständigen Struktur häufig zu Fehlern führt. Siehe Browser-Token-Signatur .

Die resultierende Konfiguration, die an übergeben wird, DocsAPI.DocEditorenthält das Token:

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

Die offizielle API-Referenz definiert config.tokenals die verschlüsselte Signatur, die von ONLYOFFICE Docs zur Validierung der Editorkonfiguration verwendet wird.

7. Header- und Body-Tokens verstehen

JWT in ONLYOFFICE umfasst mehr als nur die Browser-Editor-Konfiguration. Es wird auch für Service-zu-Service-Anfragen wie Befehls-, Konvertierungs- und Callback-Datenverkehr verwendet.

ONLYOFFICE unterstützt Request-Token sowohl im Body als auch im Header. In den Sicherheits-FAQs wird darauf hingewiesen, dass Header serverseitige Längenbeschränkungen erreichen können. Daher werden für entsprechende eingehende Anfragen Body-Token empfohlen. Ab Version 7.1 hat ein im Body vorhandener Token Vorrang; andernfalls wird der Header-Token verwendet. Ausgehende Anfragen können beide Token senden. Weitere Informationen finden Sie in der Dokumentation zu ONLYOFFICE Request-Token .

Die Docker-Variable JWT_IN_BODYist standardmäßig auf „false“ gesetzt false. Aktivieren Sie sie daher nicht einfach, weil sie existiert. Ändern Sie sie nur dann, wenn Ihre Integration so konzipiert ist, dass sie Body-Tokens konsistent sendet und validiert.

8. Testen Sie es mit einer echten Redaktionsanfrage.

Eine sinnvolle Validierungssequenz ist:

1. Öffnen Sie ein Dokument über Ihre Realintegration.
2. Überprüfen Sie, ob der Editor ohne Token-Fehler geladen wird.
3. Nimm eine kleine Änderung vor.
4. Schließen Sie den Editor oder speichern Sie auf normalem Wege.
5. Prüfen Sie, ob die Speicheranwendung den Rückruf empfängt und akzeptiert.

Eine erfolgreiche Willkommensseite des Dokumentenservers beweist nicht , dass JWT zwischen zwei Anwendungen korrekt konfiguriert ist. JWT-Fehler treten häufig erst auf, wenn die Integration die Editorkonfiguration, den Befehl, die Konvertierungsanforderung oder den Callback sendet.

Die offizielle Sicherheitsübersicht erläutert das erwartete Verhalten: ONLYOFFICE validiert ein Token und verwendet die signierten Nutzdatenwerte. Fehlt das Token oder ist es ungültig, wenn eine Validierung erforderlich ist, wird die Anfrage abgelehnt. Siehe die Sicherheitsübersicht in der ONLYOFFICE-Dokumentation .

9. Überprüfen Sie den JWT-Status und die Protokolle, wenn die Authentifizierung fehlschlägt.

Der aktuelle Docker-Startcode verweist Administratoren auf den JWT-Status-Helper. Führen Sie mit dem korrekten Containernamen folgenden Befehl aus:

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

Sie können auch die Protokolle einsehen:

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

Falls eine Integration unmittelbar nach der Änderung des Geheimnisses fehlschlägt, vergleichen Sie diese Elemente der Reihe nach:

• Ist es JWT_ENABLEDim neu erstellten Container tatsächlich aktiviert?
• Verwendet die Integration genau dasselbe Geheimnis, einschließlich Groß- und Kleinschreibung sowie Zeichensetzung?
• Verwendet der Konnektor denselben JWT-Headernamen?
• Wird für einen benutzerdefinierten Editor dasselbe Konfigurationsobjekt signiert, das auch an den Browser gesendet wird?
• Werden Rückrufe und Befehlsanforderungen wie erforderlich ebenfalls signiert und validiert?
• Wurde ein in einer Shell- oder Compose-Datei gespeichertes Geheimnis durch die Erweiterung von Umgebungsvariablen abgeschnitten, interpretiert oder ersetzt?

Häufige Ausfallmuster

„Ungültiges Token“ oder „Ungültige Signatur“

Die wahrscheinlichste Ursache ist eine Diskrepanz zwischen Geheimnis und Anfrage oder ein Token, das mit einer Nutzlast signiert wurde, die sich von der zu validierenden Anfrage unterscheidet. Generieren Sie das Token nach jeder relevanten Konfigurationsänderung neu. Verwenden Sie kein Beispieltoken aus der Dokumentation; diese Beispiele sind mit Demonstrationsgeheimnissen signiert und für Ihren Server ungültig.

Es funktioniert bis zum Neustart von Docker.

Dies bedeutet in der Regel, dass die Bereitstellung auf dem automatisch generierten JWT-Secret basierte. ONLYOFFICE weist ausdrücklich darauf hin, dass nach einem Neustart oder der Neuerstellung eines Containers ein zufälliges Secret generiert werden kann. Legen Sie daher JWT_SECRETeinen eigenen Wert fest und verwenden Sie denselben Wert in der Integration.

Nextcloud zeigt einen Verbindungs- oder Tokenfehler an.

Prüfen Sie zunächst das Geheimnis und den Header auf beiden Seiten. Die Nextcloud-Dokumentation von ONLYOFFICE erfordert, dass der Connector mit jwt_headerdem im Dokumentenserver konfigurierten Header übereinstimmt. Der aktuelle Standardwert ist Authorization…

Eine große signierte Anfrage gibt einen HTTP-Fehler zurück.

Prüfen Sie, ob das JWT in einem Header gesendet wird, der die Header-Größenbeschränkung des Proxys oder Webservers überschreitet. Die Sicherheits-FAQ von ONLYOFFICE erklärt, dass dies ein Grund dafür ist, dass Body-Tokens für entsprechende POST-Anfragen bevorzugt werden.

Sicheres Rotieren des JWT-Geheimnisses

Die Rotation des JWT-Geheimnisses muss koordiniert werden. Es bringt keinen Vorteil, nur den Dokumentenserver zu ändern, solange der Connector weiterhin mit dem alten Geheimnis signiert.

Für eine unkomplizierte Einzelinstanzbereitstellung:

1. Generieren Sie das neue Geheimnis und speichern Sie es sicher.
2. Planen Sie ein kurzes Wartungsfenster ein, falls aktive Bearbeiter betroffen sein könnten.
3. Aktualisieren Sie das Integrationsgeheimnis und das Geheimnis des Dokumentenservers JWT_SECRETals eine koordinierte Änderung.
4. Den Dokumentenserver-Container neu erstellen.
5. Öffnen, bearbeiten und speichern Sie ein Testdokument.
6. Stellen Sie sicher, dass die Rückruffunktionen funktionieren, bevor Sie den Dienst wieder in den Normalbetrieb zurückführen.

Bei mehreren Document-Server-Instanzen hinter einem Load Balancer benötigen alle Instanzen, die dieselbe Integration bedienen, während der Umstellung eine kompatible JWT-Konfiguration. Planen Sie die Umstellung systematisch, anstatt einzelne Knoten ad hoc auszutauschen.

Produktionscheckliste

• Permanentes Geheimnis: explizit festlegen JWT_SECRET; sich nicht auf den zufällig generierten Wert verlassen.
• Überall gilt dasselbe Geheimnis: Dokumentenserver und Integration müssen denselben Wert teilen.
• Backend-Signierung: Das Geheimnis darf niemals im Frontend-/Browser-Code offengelegt werden.
• HS256: Verwenden Sie den HMAC-SHA256-Ansatz, der in den offiziellen Codebeispielen von ONLYOFFICE gezeigt wird.
• Header-Übereinstimmung: Wenn ein Connector JWT über einen benannten Header sendet, muss dieser Name mit dem Document Server übereinstimmen.
• Neuerstellung des Containers: Änderungen an der Docker-Umgebung erfordern die Neuerstellung des Containers.
• Realer Integrationstest: Öffnen, Bearbeiten, Speichern und Überprüfen des Callback-Verhaltens.
• Geheime Speicherung: Halten Sie das Geheimnis von öffentlichen Repositories und Protokollen fern.
• Kontrollierte Rotation: Aktualisieren Sie beide Seiten gleichzeitig und überprüfen Sie die Aktualisierung, bevor Sie die Wartung abschließen.

Fazit

Für eine Docker-basierte ONLYOFFICE-Installation ist die dauerhafte Konfiguration einfach: Generieren Sie ein sicheres Geheimnis, setzen Sie es JWT_ENABLED=trueüber JWT_SECRETContainer-Umgebungsvariablen, erstellen Sie den Container neu und konfigurieren Sie genau dasselbe Geheimnis in Ihrem Connector oder Backend. Benutzerdefinierte Integrationen sollten die Editorkonfiguration und Serviceanfragen serverseitig mit HS256 signieren, niemals im Browsercode.

Wenn JWT nach einem Neustart plötzlich nicht mehr funktioniert, prüfen Sie, ob das Geheimnis jemals persistent gespeichert wurde. Tritt der Fehler unmittelbar nach einer Konfigurationsänderung auf, vergleichen Sie Geheimnis, Header und signierte Nutzdaten, bevor Sie an anderer Stelle suchen. Diese drei Prüfungen beheben die meisten Fehler bei der JWT-Konfiguration, ohne die Authentifizierung zu schwächen.