Jak skonfigurować uwierzytelnianie kluczem tajnym ONLYOFFICE JWT

Uwierzytelnianie JWT ONLYOFFICE działa tylko wtedy, gdy serwer dokumentów i aplikacja integrująca używają tego samego klucza tajnego. W obecnych wdrożeniach Dockera walidacja JWT jest domyślnie włączona. Aby zapewnić stabilną integrację, należy ustawić własną wartość stałą JWT_SECRETzamiast polegać na wartości generowanej automatycznie przez kontener, a następnie skonfigurować ten sam klucz tajny w NextCloud, własnym menedżerze dokumentów lub dowolnym łączniku, który komunikuje się z ONLYOFFICE Docs.

Ten praktyczny przewodnik koncentruje się na konfiguracji, której najprawdopodobniej będziesz potrzebować: Docker i Docker Compose, niestandardowych integracjach podpisujących konfigurację edytora, zachowaniu nagłówka/treści, weryfikacji, rotacji i typowych błędach. Opiera się na aktualnej dokumentacji ONLYOFFICE, sprawdzonej w październiku 2026 roku.

Krótki przewodnik

Począwszy od ONLYOFFICE Docs 7.2, wdrożenia Dockera domyślnie włączają JWT i generują losowy klucz tajny, jeśli go nie podasz. Oficjalna dokumentacja Dockera ostrzega, że ​​automatycznie generowany klucz tajny może ulec zmianie po ponownym uruchomieniu lub odtworzeniu kontenera, co może przerwać integrację. Ustaw jawny klucz tajny dla każdego rzeczywistego wdrożenia. Zobacz Konfigurowanie JWT dla ONLYOFFICE Docs w dokumentacji oraz oficjalny podręcznik instalacji Dockera .

1. Zidentyfikuj kontener ONLYOFFICE i metodę wdrożenia

W przypadku hosta Docker zacznij od:

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

Sprawdź, czy instancja została uruchomiona za pomocą docker runDocker Compose, panelu sterowania czy innej warstwy orkiestracji. Musisz zmienić konfigurację źródłową, która tworzy kontener. Edycja wygenerowanego pliku w kontenerze nie jest trwałym rozwiązaniem.

W przypadku Dockera, ONLYOFFICE zaleca administratorom korzystanie ze zmiennych środowiskowych zamiast ręcznej edycji /etc/onlyoffice/documentserver/local.json. Jeśli edytujesz wartości JWT bezpośrednio w tym pliku, proces uruchamiania Dockera może je przywrócić lub zregenerować po ponownym uruchomieniu kontenera.

2. Wygeneruj silny sekret i przechowuj go bezpiecznie

Wygodnym poleceniem powłoki jest:

openssl rand -hex 32

Generuje to 32 losowe bajty reprezentowane przez 64 znaki szesnastkowe. ONLYOFFICE nie wymaga tego dokładnego formatu; ważne jest, aby obie strony miały ten sam sekret i aby był trudny do odgadnięcia.

Traktuj JWT_SECRETjak hasło lub dane uwierzytelniające API:

• Nie umieszczaj danych w publicznym repozytorium Git.
• Nie umieszczaj go w kodzie JavaScript dostarczanym do przeglądarek.
• Ogranicz dostęp do pliku środowiska Compose lub magazynu sekretów, który go zawiera.
• Użyj różnych kluczy tajnych dla oddzielnych środowisk, takich jak produkcja i testowanie.

Dokumentacja podpisu ONLYOFFICE wyraźnie ostrzega, że ​​podpisywanie tokenów musi odbywać się na serwerze, ponieważ każdy kod po stronie przeglądarki zawierający klucz tajny ujawnia go użytkownikom. Oficjalne przykłady używają HMAC-SHA256 ( HS256). Zobacz dokumentację podpisu JWT ONLYOFFICE .

3. Skonfiguruj JWT w Docker Compose

Podstawowa usługa Compose może obejmować:

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"

Jeśli to praktyczne, zachowaj prawdziwy sekret poza plikiem „Utwórz”. Na przykład umieść go w .envpliku z ograniczonymi uprawnieniami:

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

Następnie upewnij się, że plik jest wyłączony spod kontroli wersji i może być odczytywany tylko przez administratorów lub konta usługi, które tego potrzebują.

Oficjalne repozytorium ONLYOFFICE Docker-DocumentServer zawiera dokumenty JWT_ENABLED, JWT_SECRET, JWT_HEADERi JWT_IN_BODY. Aktualny kod startowy Dockera domyślnie włącza walidację JWT, używa Authorizationdomyślnego nagłówka i generuje losowy klucz tajny, gdy nie podano jawnego klucza.

4. Utwórz ponownie kontener, aby zastosować nowe środowisko

Do tworzenia:

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

W przypadku kontenera pierwotnie utworzonego za pomocą JWT docker run, oficjalny podręcznik JWT zaleca administratorom zatrzymanie i usunięcie starego kontenera, a następnie utworzenie nowego ze zmiennymi środowiskowymi JWT. Podczas wykonywania tej czynności nie należy usuwać woluminów trwałych ani danych zamontowanych w powiązaniu.

Można również sprawdzić środowisko działającego kontenera bez drukowania samego sekretu:

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

Jeśli nazwa kontenera jest inna, należy ją onlyoffice-documentserverodpowiednio zmienić.

5. Skonfiguruj ten sam sekret w integracji

To jest najczęściej pomijany element. Włączenie JWT w ONLYOFFICE Docs bez skonfigurowania strony zarządzania dokumentami powoduje odrzucenie żądań redaktora. Konektor lub aplikacja niestandardowa musi podpisywać żądania dokładnie tym samym tajnym kluczem.

Przykład Nextcloud

W ustawieniach ONLYOFFICE dla Nextcloud wprowadź ten sam klucz tajny, którego używa Serwer Dokumentów. Nazwa nagłówka również musi być taka sama. Aktualna dokumentacja integracji Nextcloud dla ONLYOFFICE zawiera ustawienia łącznika jwt_secreti jako domyślny nagłówek. Zobacz oficjalną dokumentację łącznika Nextcloud .jwt_headerAuthorization

Jeśli Twój konektor ma pole oznaczone etykietą „Klucz tajny”, „Sekret JWT” lub podobną, nie generuj tam drugiego, niezależnego sekretu. Skopiuj tę samą wartość sekretu.

6. W przypadku integracji niestandardowej podpisz pełną konfigurację edytora na serwerze

W przypadku aplikacji niestandardowej należy najpierw utworzyć konfigurację edytora, podpisać ją w systemie zaplecza, a następnie przypisać powstały token JWT do właściwości najwyższego poziomu token.

Przykład Node.js:

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

Dokumentacja podpisu przeglądarki ONLYOFFICE mówi, że ładunek tokena do otwarcia pliku musi mieć taką samą strukturę jak konfiguracja edytora. Od wersji 7.1 zestaw parametrów zaangażowanych w walidację jest ściśle regulowany dla tej operacji, więc podpisanie nieaktualnej lub częściowej struktury jest częstą przyczyną błędów. Zobacz Podpisywanie tokenów przeglądarki .

Wynikowa konfiguracja przekazana do DocsAPI.DocEditorzawiera token:

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

Oficjalne odniesienie do API definiuje go config.tokenjako zaszyfrowany podpis używany przez ONLYOFFICE Docs do weryfikacji konfiguracji edytora.

7. Zrozumienie różnicy między tokenami nagłówka i treści

JWT w ONLYOFFICE obejmuje więcej niż tylko konfigurację edytora przeglądarki. Jest również używany do obsługi żądań między usługami, takich jak polecenia, konwersje i ruch wywołań zwrotnych.

ONLYOFFICE obsługuje tokeny żądania zarówno w treści, jak i nagłówku. W FAQ dotyczącym bezpieczeństwa zaznaczono, że nagłówki mogą przekraczać limity długości specyficzne dla serwera, dlatego zaleca się stosowanie tokenów ciała dla odpowiednich żądań przychodzących. Od wersji 7.1, przychodzący token ciała ma pierwszeństwo, jeśli jest obecny; w przeciwnym razie używany jest token nagłówka. Strona wychodząca może wysłać oba. Zobacz dokumentację tokenów żądania ONLYOFFICE .

Zmienna Docker JWT_IN_BODYma domyślnie wartość false, więc nie włączaj jej tylko dlatego, że istnieje. Zmień ją tylko wtedy, gdy Twoja integracja jest zaprojektowana tak, aby wysyłać i walidować tokeny treści w sposób spójny.

8. Przetestuj z prawdziwym żądaniem edytora

Przydatna sekwencja walidacji wygląda następująco:

1. Otwórz dokument poprzez rzeczywistą integrację.
2. Sprawdź, czy edytor ładuje się bez błędów tokenów.
3. Wprowadź niewielką zmianę.
4. Zamknij edytor lub użyj normalnej ścieżki zapisu.
5. Sprawdź, czy aplikacja pamięci masowej odbiera i akceptuje wywołanie zwrotne.

Poprawna strona powitalna serwera dokumentów nie dowodzi, że JWT jest poprawnie skonfigurowany między dwiema aplikacjami. Błędy JWT często pojawiają się tylko wtedy, gdy integracja wysyła konfigurację edytora, polecenie, żądanie konwersji lub wywołanie zwrotne.

Oficjalny przegląd bezpieczeństwa wyjaśnia oczekiwane zachowanie: ONLYOFFICE weryfikuje token i używa podpisanych wartości danych; jeśli token jest brakujący lub nieprawidłowy, gdy wymagana jest walidacja, żądanie jest odrzucane. Zobacz przegląd bezpieczeństwa w dokumentacji ONLYOFFICE .

9. Sprawdź status i dzienniki JWT w przypadku niepowodzenia uwierzytelniania

Aktualny kod startowy Dockera kieruje administratorów do pomocnika stanu JWT. Mając poprawną nazwę kontenera, uruchom:

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

Można również sprawdzić logi:

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

Jeżeli integracja zakończy się niepowodzeniem zaraz po zmianie klucza tajnego, porównaj poniższe elementy w podanej kolejności:

• Czy jest on JWT_ENABLEDrzeczywiście włączony w odtworzonym kontenerze?
• Czy integracja wykorzystuje dokładnie ten sam sekret, w tym kapitalizację i interpunkcję?
• Czy łącznik używa tej samej nazwy nagłówka JWT?
• Czy w przypadku edytora niestandardowego podpisujesz ten sam obiekt konfiguracyjny, który wysyłasz do przeglądarki?
• Czy wywołania zwrotne i żądania poleceń są również podpisywane i weryfikowane zgodnie z wymaganiami?
• Czy sekret zapisany w powłoce lub pliku Compose został obcięty, zinterpretowany lub zastąpiony przez rozszerzenie zmiennej środowiskowej?

Typowe wzorce awarii

„Nieprawidłowy token” lub „Nieprawidłowy podpis”

Najbardziej prawdopodobną przyczyną jest niezgodność klucza tajnego lub token podpisany w treści różniącej się od żądania podlegającego weryfikacji. Po każdej istotnej zmianie konfiguracji należy ponownie wygenerować token. Nie należy ponownie używać przykładowego tokenu z dokumentacji; te przykłady są podpisane kluczami tajnymi demonstracyjnymi i nie są ważne dla Twojego serwera.

Działa do momentu ponownego uruchomienia Dockera

Zwykle oznacza to, że wdrożenie opierało się na automatycznie wygenerowanym kluczu tajnym JWT. ONLYOFFICE wyraźnie ostrzega, że ​​losowy klucz tajny może zostać wygenerowany ponownie po ponownym uruchomieniu lub odtworzeniu kontenera. Ustaw go JWT_SECRETsamodzielnie i wpisz tę samą wartość w integracji.

Nextcloud pokazuje błąd połączenia lub tokena

Najpierw sprawdź tajny klucz i nagłówek po obu stronach. Dokumentacja Nextcloud ONLYOFFICE wymaga, aby łącznik jwt_headerbył zgodny z nagłówkiem skonfigurowanym w Serwerze Dokumentów. Obecnie domyślna wartość to Authorization.

Duże podpisane żądanie zwraca błąd HTTP

Sprawdź, czy JWT jest wysyłany w nagłówku, który przekracza limit rozmiaru nagłówka serwera proxy lub serwera WWW. W FAQ ONLYOFFICE dotyczącym bezpieczeństwa wyjaśniono, że jest to jeden z powodów, dla których tokeny ciała są preferowane w przypadku żądań POST.

Bezpieczna rotacja klucza tajnego JWT

Rotacja sekretu JWT musi być skoordynowana. Zmiana samego serwera dokumentów nie przynosi żadnych korzyści, podczas gdy łącznik nadal podpisuje się przy użyciu starego sekretu.

W przypadku prostego wdrożenia pojedynczej instancji:

1. Wygeneruj nowy klucz tajny i przechowuj go bezpiecznie.
2. Zaplanuj krótką przerwę konserwacyjną, jeśli może ona wpłynąć na pracę aktywnych redaktorów.
3. Zaktualizuj klucz tajny integracji i Serwera dokumentów JWT_SECRETw ramach jednej skoordynowanej zmiany.
4. Utwórz ponownie kontener Serwera dokumentów.
5. Otwórz, edytuj i zapisz dokument testowy.
6. Przed przywróceniem usługi do normalnego użytkowania należy sprawdzić, czy wywołania zwrotne działają.

W przypadku wielu instancji Serwera Dokumentów za modułem równoważenia obciążenia, wszystkie instancje obsługujące tę samą integrację wymagają zgodnej konfiguracji JWT podczas zmiany. Zaplanuj wdrożenie zamiast rotacji jednego węzła ad hoc.

Lista kontrolna produkcji

• Tajemnica trwała: ustaw JWT_SECRETjawnie; nie polegaj na losowo wygenerowanej wartości.
• Wszędzie ten sam sekret: Serwer Dokumentów i integracja muszą mieć tę samą wartość.
• Podpisywanie zaplecza: nigdy nie ujawniaj tajnego kodu w kodzie front-endu/przeglądarki.
• HS256: użyj podejścia HMAC-SHA256 pokazanego w oficjalnych przykładach kodu ONLYOFFICE.
• Uzgadnianie nagłówka: jeśli łącznik wysyła JWT za pośrednictwem nazwanego nagłówka, nazwa ta musi być zgodna z nazwą Document Server.
• Odtwarzanie kontenera: zmiany w środowisku Docker wymagają ponownego utworzenia kontenera.
• Rzeczywisty test integracyjny: otwieranie, edycja, zapisywanie i weryfikacja zachowania wywołania zwrotnego.
• Przechowywanie tajnych informacji: nie ujawniaj ich publicznie dostępnym repozytoriom ani logom.
• Kontrolowany obrót: zaktualizuj obie strony jednocześnie i sprawdź przed zakończeniem konserwacji.

Podsumowanie

W przypadku instalacji ONLYOFFICE opartej na Dockerze, trwała konfiguracja jest prosta: wygeneruj silny klucz tajny, ustaw JWT_ENABLED=truei JWT_SECRETprzeprowadź zmienne środowiskowe kontenera, ponownie utwórz kontener i skonfiguruj dokładnie ten sam klucz tajny w konektorze lub zapleczu. W przypadku integracji niestandardowych konfiguracja edytora i żądania serwisowe powinny być podpisywane na serwerze za pomocą protokołu HS256, a nie w kodzie przeglądarki.

Jeśli JWT nagle ulegnie awarii po restarcie, sprawdź, czy sekret został kiedykolwiek utrwalony. Jeśli problem wystąpi natychmiast po zmianie konfiguracji, porównaj sekret, nagłówek i podpisany ładunek, zanim zaczniesz szukać gdzie indziej. Te trzy sprawdzenia rozwiązują większość błędów konfiguracji JWT bez osłabiania uwierzytelniania.