Skonfiguruj tajne klucze JWT ONLYOFFICE na serwerze i łączniku

Konsekwentnie używaj jednego silnego klucza tajnego JWT: skonfiguruj go w ONLYOFFICE Docs, skopiuj tę samą wartość do ustawień ONLYOFFICE na połączonej platformie i włącz walidację JWT. Docs 7.2 i nowsze wersje domyślnie włączają JWT i automatycznie generują klucz tajny; zmiana klucza tajnego oznacza, że ​​każda integracja musi zostać zaktualizowana, aby go dopasować. Dokładna metoda po stronie serwera zależy od tego, czy Docs działa jako pakiet Linux, czy jako kontener Docker.

Co musi pasować?

JWT (JSON Web Token) umożliwia ONLYOFFICE Docs weryfikację podpisanych żądań. Platforma dokumentów i Docs muszą używać tego samego klucza tajnego i zgodnych ustawień nagłówka. Serwer używa oddzielnych ustawień tokena do konfiguracji przeglądarki oraz przychodzących i wychodzących żądań usług; wspólne wartości klucza tajnego chronią te wymiany. Nie należy umieszczać klucza tajnego na publicznej stronie internetowej, w pakiecie JavaScript po stronie klienta, w zgłoszeniu pomocy technicznej ani w publicznie odczytywalnym repozytorium źródłowym.

Przed edycją zidentyfikuj typ wdrożenia i zapisz adres URL Dokumentów używany przez łącznik. Wygeneruj długi, nieprzewidywalny klucz tajny za pomocą menedżera haseł lub generatora zabezpieczonego kryptograficznie. Potraktuj go jak dane uwierzytelniające i przechowuj w magazynie konfiguracji z ograniczonym dostępem.

Konfigurowanie instalacji systemu Linux

W przypadku instalacji Linuksa opartej na pakiecie, edytuj plik /etc/onlyoffice/documentserver/local.json. Zachowaj wszelkie istniejące ustawienia: zamiast zastępować cały plik, scal poniższe klucze z istniejącym plikiem JSON. Przykład pokazuje strukturę walidacji tokenów i trzy pasujące do niej lokalizacje kluczy tajnych opisane w oficjalnym przewodniku konfiguracji:

{
  "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" }
      }
    }
  }
}

Zastąp każdy symbol zastępczy dokładnie taką samą wartością tajną. Nie wklejaj samego przykładowego symbolu zastępczego. Przełączniki browser, inboxi outboxsą oddzielne; włączenie tylko jednego z nich nie włącza walidacji wszystkich żądań. W dokumentach w wersji 7.2 i nowszych JWT jest domyślnie włączony, ale jawne sprawdzenie tych ustawień pomaga podczas audytu istniejącej konfiguracji lub dostosowywania działania między węzłami. W przypadku wersji starszych niż 7.2 oficjalny przewodnik zaleca włączenie wszystkich trzech przełączników.

Przed ponownym uruchomieniem sprawdź poprawność składni JSON. Następnie uruchom ponownie usługi serwera dokumentów, aby załadować zmiany:

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

Uruchom polecenie z konta uprawnionego do zarządzania usługami systemowymi. W systemie Windows plik konfiguracyjny wygląda następująco %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json: zamiast polecenia Linux użyj instrukcji ponownego uruchomienia systemu Windows z oficjalnego podręcznika.

Skonfiguruj Dockera bez edytowania wygenerowanej konfiguracji

W przypadku oficjalnego obrazu Document Server Docker należy ustawić JWT za pomocą zmiennych środowiskowych kontenera. Oficjalny przewodnik ostrzega, że ​​ręczna zmiana wygenerowanych wartości local.jsonmoże zostać cofnięta po ponownym uruchomieniu kontenera. Ustaw JWT_ENABLED=truei JWT_SECRETw poleceniu tworzenia kontenera lub w usłudze Compose, a następnie utwórz kontener ponownie, aby środowisko zaczęło działać. Przechowuj klucz tajny w chronionym pliku środowiskowym lub menedżerze kluczy tajnych i ogranicz uprawnienia tego pliku; unikaj zatwierdzania go w systemie kontroli wersji.

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

Zdefiniuj ONLYOFFICE_JWT_SECRETw środowisku wdrożeniowym lub .envpliku chronionym. Przypnij przetestowany tag obrazu zamiast polegać na latest, i sprawdź w dokumentacji, który tag uruchamiasz. Po zmianie wartości środowiskowych utwórz kontener ponownie, korzystając ze standardowego procesu wdrażania. Proste ponowne uruchomienie może pozostawić stare środowisko na miejscu.

Zaktualizuj łącznik i chroń sekret

Otwórz ustawienia integracji na platformie łączącej się z ONLYOFFICE Docs, takiej jak NextCloud lub inny obsługiwany konektor. Wprowadź ten sam sekret JWT w polu klucza tajnego i zapisz. Sprawdź również skonfigurowany adres URL serwera dokumentów oraz, jeśli konektor go udostępnia, nagłówek autoryzacji. Domyślny nagłówek w ONLYOFFICE Docs to Authorization; zmień go tylko wtedy, gdy obie strony są skonfigurowane do korzystania z tej samej alternatywy.

Niezgodność klucza tajnego często objawia się błędem nieprawidłowego tokenu lub autoryzacji podczas otwierania lub zapisywania dokumentu. Niezgodność może również wystąpić, gdy zaktualizowano tylko jeden węzeł Docs za modułem równoważenia obciążenia. Jeśli obsługujesz wiele węzłów, zsynchronizuj te same ustawienia klucza tajnego i tokena na wszystkich węzłach przed wysłaniem do nich ruchu. Wdrażaj zmiany w kontrolowanym oknie: aktualizuj Docs i łącznik jednocześnie i licz się z tym, że istniejące sesje edytora lub żądania podpisane starą wartością zakończą się niepowodzeniem podczas przejścia.

Każdy, kto może odczytać sekret, może tworzyć tokeny akceptowane przez serwer. Ogranicz dostęp do plików konfiguracyjnych i zmiennych wdrożeniowych, korzystaj z szyfrowanego transportu dla połączenia między łącznikiem a Dokumentami i dokonuj rotacji sekretu, jeśli mógł on zostać ujawniony. Rotacja wymaga aktualizacji wszystkich węzłów Dokumentów i łącznika do nowej wartości; nie pozostawiaj starych danych uwierzytelniających w plikach ani logach.

Sprawdź konfigurację

• Sprawdź, czy usługa lub kontener Docs działa po zmianie konfiguracji.
• W przypadku wdrożenia Dockera uruchom komendę JWT, sudo docker exec <container_name> sudo documentserver-jwt-status.shaby sprawdzić status JWT. Użyj rzeczywistej nazwy kontenera. Ta funkcja pomocnicza jest udokumentowana dla Dockera; nie zakładaj, że jest dostępna w każdej instalacji pakietu.
• Otwórz dokument za pośrednictwem połączonej platformy, wprowadź niewielką, nieszkodliwą zmianę i zapisz ją. Upewnij się, że edytor się otwiera, a platforma odbiera zapisaną zmianę.
• Jeśli uwierzytelnianie się nie powiedzie, porównaj znak po znaku tajny klucz serwera i łącznika, sprawdź, czy wszystkie odpowiednie przełączniki tokenów są włączone i zweryfikuj konfigurację nagłówka żądania.

Oficjalny przewodnik konfiguracji jest źródłem informacji o obsługiwanych ustawieniach i zachowaniu wersji. Zapoznaj się z dokumentacją konfiguracji JWT ONLYOFFICE oraz oficjalnymi parametrami instalacji Dockera, aby dowiedzieć się, jaką wersję wdrażasz.