ONLYOFFICE JWT-Geheimnisse server- und connectorübergreifend einrichten

Verwenden Sie ein einziges sicheres JWT-Geheimnis: Konfigurieren Sie es in ONLYOFFICE Docs, kopieren Sie denselben Wert in die ONLYOFFICE-Einstellungen der verbundenen Plattform und lassen Sie die JWT-Validierung aktiviert. Docs 7.2 und höher aktivieren JWT standardmäßig und generieren automatisch ein Geheimnis. Wenn Sie das Geheimnis ändern, muss jede Integration entsprechend angepasst werden. Die genaue serverseitige Vorgehensweise hängt davon ab, ob Docs als Linux-Paket oder in einem Docker-Container ausgeführt wird.

Was muss übereinstimmen?

JWT (JSON Web Token) ermöglicht ONLYOFFICE Docs die Überprüfung signierter Anfragen. Die Dokumentenplattform und Docs müssen dasselbe Geheimnis und kompatible Header-Einstellungen verwenden. Der Server nutzt separate Token-Einstellungen für die Browserkonfiguration sowie für eingehende und ausgehende Serviceanfragen; die gemeinsamen Geheimniswerte schützen diese Kommunikation. Speichern Sie das Geheimnis nicht auf einer öffentlichen Webseite, in einem clientseitigen JavaScript-Bundle, in einem Support-Ticket oder in einem öffentlich zugänglichen Quellcode-Repository.

Ermitteln Sie vor der Bearbeitung Ihren Bereitstellungstyp und notieren Sie sich die vom Connector verwendete Dokumentations-URL. Generieren Sie mit einem Passwortmanager oder einem kryptografisch sicheren Generator ein langes, unvorhersehbares Geheimnis. Behandeln Sie es wie eine Anmeldeinformation und speichern Sie es in einem geschützten Konfigurationsspeicher.

Konfigurieren einer Linux-Installation

Bei einer paketbasierten Linux-Installation bearbeiten Sie die Datei /etc/onlyoffice/documentserver/local.json. Behalten Sie alle vorhandenen Einstellungen bei: Fügen Sie die folgenden Schlüssel in das bestehende JSON ein, anstatt die gesamte Datei zu ersetzen. Das Beispiel zeigt die Token-Validierungsstruktur und die drei zugehörigen Speicherorte für geheime Informationen, die in der offiziellen Konfigurationsanleitung beschrieben sind:

{
  "services": {
    "CoAuthoring": {
      "token": {
        "enable": {
          "request": {
            "inbox": true,
            "outbox": true
          },
          "browser": true
        }
      },
      "secret": {
        "inbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "outbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "session": { "string": "REPLACE_WITH_YOUR_SECRET" }
      }
    }
  }
}

Ersetzen Sie jeden Platzhalter durch denselben geheimen Wert. Fügen Sie nicht den Beispielplatzhalter selbst ein. Die Schalter browser`<option1>`, inbox`<option2>` und outbox`<option3>` sind unabhängig; die Aktivierung nur eines Schalters aktiviert nicht die gesamte Anforderungsvalidierung. In Version 7.2 und höher ist JWT standardmäßig aktiviert. Die explizite Überprüfung dieser Einstellungen ist jedoch hilfreich, wenn Sie eine bestehende Konfiguration prüfen oder das Verhalten auf verschiedenen Knoten angleichen möchten. Für Versionen vor 7.2 empfiehlt die offizielle Anleitung, alle drei Schalter zu aktivieren.

Überprüfen Sie die JSON-Syntax vor dem Neustart. Starten Sie anschließend die Dokumentenserverdienste neu, damit die Änderungen geladen werden.

sudo systemctl restart ds-converter ds-docservice ds-metrics

Führen Sie den Befehl mit einem Konto aus, das zur Verwaltung von Systemdiensten berechtigt ist. Unter Windows befindet sich die Konfigurationsdatei unter %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json; verwenden Sie die Anweisungen zum Neustart unter Windows in der offiziellen Anleitung anstelle des Linux-Befehls.

Docker konfigurieren, ohne die generierte Konfiguration zu bearbeiten

Für das offizielle Docker-Image des Document Servers muss das JWT über Container-Umgebungsvariablen festgelegt werden. Die offizielle Anleitung warnt davor, dass manuell generierte JWT-Werte local.jsonbeim Neustart des Containers rückgängig gemacht werden können. Legen Sie die entsprechenden Parameter beim Erstellen des Containers oder im Compose-Dienst fest JWT_ENABLED=trueund JWT_SECRETerstellen Sie den Container anschließend neu, damit die Umgebungsvariablen wirksam werden. Speichern Sie das Geheimnis in einer geschützten Umgebungsdatei oder einem Secret Manager und beschränken Sie die Berechtigungen dieser Datei. Vermeiden Sie es, das Geheimnis in die Versionskontrolle einzuchecken.

services:
  onlyoffice:
    image: onlyoffice/documentserver:YOUR_PINNED_TAG
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: ${ONLYOFFICE_JWT_SECRET}

Definieren Sie ONLYOFFICE_JWT_SECRETdie Umgebungsvariablen in der Bereitstellungsumgebung oder der geschützten .envDatei. Verwenden Sie ein getestetes Image-Tag anstelle der Standardeinstellung latestund prüfen Sie die Dokumentation des verwendeten Tags. Nach dem Ändern der Umgebungsvariablen erstellen Sie den Container mit Ihrem gewohnten Bereitstellungsprozess neu. Ein einfacher Neustart kann die alte Umgebung beibehalten.

Aktualisieren Sie den Connector und schützen Sie das Geheimnis.

Öffnen Sie die Integrationseinstellungen in der Plattform, die mit ONLYOFFICE Docs verbunden ist, z. B. Nextcloud oder ein anderer unterstützter Connector. Geben Sie im Feld für den geheimen Schlüssel denselben JWT-Schlüssel ein und speichern Sie die Einstellungen. Überprüfen Sie außerdem die konfigurierte Dokumentenserver-URL und, falls der Connector diese bereitstellt, den Autorisierungsheader. Der Standardheader in ONLYOFFICE Docs ist „http://localhost:8000“. AuthorizationÄndern Sie ihn nur, wenn beide Seiten für die Verwendung derselben Alternative konfiguriert sind.

Eine Diskrepanz zwischen Geheimnis und Token äußert sich häufig als ungültiges Token oder Autorisierungsfehler beim Öffnen oder Speichern eines Dokuments. Eine solche Diskrepanz kann auch auftreten, wenn nur ein Docs-Knoten hinter einem Load Balancer aktualisiert wurde. Wenn Sie mehrere Knoten betreiben, synchronisieren Sie die Einstellungen für Geheimnis und Token auf allen Knoten, bevor Sie Datenverkehr an diese senden. Führen Sie Änderungen kontrolliert durch: Aktualisieren Sie Docs und den Connector gleichzeitig. Bestehende Editor-Sitzungen oder Anfragen, die mit dem alten Wert signiert sind, schlagen während der Umstellung fehl.

Wer das Geheimnis lesen kann, kann Tokens erstellen, die der Server möglicherweise akzeptiert. Beschränken Sie den Zugriff auf Konfigurationsdateien und Bereitstellungsvariablen, verwenden Sie eine verschlüsselte Verbindung zwischen Connector und Docs und rotieren Sie das Geheimnis, falls es offengelegt wurde. Die Rotation erfordert die Aktualisierung aller Docs-Knoten und des Connectors auf den neuen Wert; lassen Sie keine alten Anmeldeinformationen in eingecheckten Dateien oder Protokollen zurück.

Überprüfen Sie die Konfiguration

• Prüfen Sie, ob der Docs-Dienst bzw. -Container nach der Konfigurationsänderung ausgeführt wird.
• Führen Sie bei einer Docker-Bereitstellung den Befehl aus, sudo docker exec <container_name> sudo documentserver-jwt-status.shum den JWT-Status zu überprüfen. Verwenden Sie dabei den tatsächlichen Containernamen. Dieser Helfer ist für Docker dokumentiert; gehen Sie nicht davon aus, dass er bei jeder Paketinstallation verfügbar ist.
• Öffnen Sie ein Dokument über die verbundene Plattform, nehmen Sie eine kleine, unbedenkliche Änderung vor und speichern Sie es. Vergewissern Sie sich, dass sich sowohl der Editor öffnet als auch die Plattform die gespeicherte Änderung empfängt.
• Falls die Authentifizierung fehlschlägt, vergleichen Sie das Server- und Connector-Geheimnis Zeichen für Zeichen, prüfen Sie, ob alle relevanten Token-Schalter aktiviert sind, und überprüfen Sie die Konfiguration des Anforderungsheaders.

Die offizielle Konfigurationsanleitung ist maßgebend für die unterstützten Einstellungen und das Versionsverhalten. Konsultieren Sie die JWT-Konfigurationsdokumentation von ONLYOFFICE und die offiziellen Docker-Installationsparameter für die genaue Version, die Sie einsetzen.