Napraw błąd „Token jest nieprawidłowy” w integracji ONLYOFFICE Nextcloud

Komunikat ONLYOFFICE „Token is not valid” zazwyczaj oznacza, że ​​obie strony integracji nie weryfikują tego samego tokenu JSON Web Token (JWT). W konfiguracji NextCloud ważne jest, aby istniało kilka ścieżek tokenów: konfiguracja edytora wysyłana do przeglądarki, żądania przychodzące do ONLYOFFICE Docs oraz żądania wychodzące, takie jak wywołania zwrotne do NextCloud. Awaria w każdej z nich może wyglądać podobnie z punktu widzenia użytkownika.

Przed rozpoczęciem zmiany ustawień należy zwrócić uwagę na jeden istotny szczegół: JWT jest domyślnie włączony w ONLYOFFICE Docs od wersji 7.2 , a serwer dokumentów może automatycznie generować klucz tajny. To sprawia, że ​​stary samouczek zalecający „pozostaw JWT wyłączony” stanowi słabą podstawę dla nowoczesnej instalacji. Aktualne wytyczne ONLYOFFICE zalecają skonfigurowanie własnego klucza tajnego i użycie go w konektorze. Zobacz przewodnik konfiguracji JWT ONLYOFFICE .

Krótki przewodnik: co sprawdzić w pierwszej kolejności

1. Potwierdź, że współdzielony sekret jest rzeczywiście taki sam

Walidacja JWT opiera się na współdzielonym kluczu tajnym. ONLYOFFICE Docs podpisuje tokeny tym kluczem tajnym, a strona odbierająca weryfikuje podpis, używając tej samej wartości. Różnica jednego znaku, spacja na końcu, stara zmienna środowiskowa lub ponownie wygenerowany klucz tajny Dockera wystarczą, aby token wyglądający na poprawny nie został zweryfikowany.

W NextCloud łącznik obsługuje to jwt_secretustawienie. Oficjalny łącznik udostępnia również occinterfejs konfiguracyjny, dzięki czemu można sprawdzić wartość faktycznie używaną przez NextCloud, zamiast polegać na pliku konfiguracyjnym, który wydaje się aktywny. Aktualne ustawienia łącznika są udokumentowane w oficjalnym pliku README łącznika ONLYOFFICE NextCloud .

sudo -u www-data php occ config:app:get onlyoffice jwt_secret
sudo -u www-data php occ config:app:get onlyoffice jwt_header

Nie wklejaj tajnego hasła do zgłoszeń pomocy technicznej, zrzutów ekranu, historii powłoki udostępnianej innym osobom ani publicznych raportów o problemach. Porównaj je lokalnie.

W przypadku natywnej instalacji ONLYOFFICE Docs w systemie Linux obsługiwany plik konfiguracyjny to:

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE dokumentuje oddzielne ustawienia tokenów przeglądarki, skrzynki odbiorczej i skrzynki nadawczej. Wartości tajne używane do walidacji muszą być zgodne z konfiguracją łącznika. Nie edytować default.json; ONLYOFFICE wyraźnie ostrzega, że ​​ustawienia domyślne mogą zostać nadpisane po ponownym uruchomieniu lub aktualizacji. Używaj local.jsondo instalacji pakietów.

Jeśli uruchamiasz ONLYOFFICE Docs w Dockerze

Używaj zmiennych środowiskowych Dockera zamiast ręcznej edycji local.jsonw kontenerze. ONLYOFFICE informuje, że Docker może regenerować konfigurację JWT podczas uruchamiania; jego oficjalny obraz obsługuje JWT_ENABLED, JWT_SECRET, JWT_HEADERi JWT_IN_BODY. Aktualna dokumentacja obrazu Dockera wymienia go Authorizationjako domyślny nagłówek JWT. Zobacz oficjalne repozytorium Docker DocumentServer .

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=replace-with-a-long-random-secret
  - JWT_HEADER=Authorization

Po zmianie zmiennych środowiskowych Dockera utwórz ponownie kontener, aby usługa mogła je otrzymać. Sama edycja pliku Compose bez ponownego utworzenia kontenera nie zmienia jego istniejącego środowiska.

2. Upewnij się, że nagłówek JWT jest dokładnie taki sam

Częstym nieporozumieniem jest to, że nazwa nagłówka ma charakter kosmetyczny. Nie jest. ONLYOFFICE Docs ma konfigurowalne nagłówki tokenów skrzynki odbiorczej i nadawczej, a łącznik Nextcloud ma jwt_headerustawienie. Muszą one opisywać tę samą ścieżkę żądania.

Aktualna dokumentacja API ONLYOFFICE określa Authorizationserwer dokumentów jako domyślny dla przychodzących żądań JWT, a oficjalna dokumentacja integracji Nextcloud również określa go Authorizationjako standardowy domyślny konektor. Starsze przykłady i istniejące instalacje mogą używać AuthorizationJWTlub innej jawnie skonfigurowanej wartości. Bezpieczna zasada nie polega zatem na „zawsze używaj jednego konkretnego ciągu znaków”, lecz na zapewnieniu zgodności aktywnej konfiguracji po obu stronach .

Format żądania również ma znaczenie. Dokumentacja API ONLYOFFICE pokazuje tokeny nagłówkowe wysyłane za pomocą schematu Bearer. Szczegóły dotyczące protokołu można znaleźć w dokumentacji tokenu w nagłówku ONLYOFFICE .

Jeśli celowo używasz niestandardowego nagłówka, skonfiguruj tę samą wartość w obu produktach. Jeśli nie masz powodu, aby go dostosowywać, użycie obecnej wartości domyślnej Authorizationzmniejszy liczbę ruchomych części.

3. Sprawdź, czy odwrotny serwer proxy zmienia ścieżkę tokena

Jeśli ustawienia Nextcloud i ONLYOFFICE są zgodne, ale błąd nadal występuje, sprawdź ścieżkę między nimi. Odwrotny serwer proxy, brama uwierzytelniania, WAF lub kontroler ruchu przychodzącego mogą wpływać na nagłówki autoryzacji. Zależy to od stosu, więc nie zakładaj, że serwer proxy jest winny bez dowodów.

Skorzystaj z poniższej sekwencji testu praktycznego:

• Sprawdź, czy publiczny adres URL serwera dokumentów jest dostępny z hosta Nextcloud.
• Sprawdź, czy wewnętrzny adres URL serwera dokumentów (jeśli został skonfigurowany) jest rozwiązywany przez serwer lub kontener Nextcloud.
• Sprawdź, czy wewnętrzny adres URL Nextcloud/storage jest powiązany z hostem lub kontenerem ONLYOFFICE Docs.
• Sprawdź dzienniki błędów/dostępu serwera proxy podczas sprawdzania łącznika.
• Jeśli Twój serwer proxy ma wyraźne reguły dotyczące Authorizationnagłówka, potwierdź jego przekazanie, a nie zastąpienie lub usunięcie nagłówka.

Nie wyłączaj JWT tylko po to, by błąd zniknął. To usunie mechanizm walidacji, a nie go naprawi. Nie wyłączaj również weryfikacji TLS jako rozwiązania problemu z JWT: weryfikacja certyfikatu i walidacja podpisu JWT to oddzielne mechanizmy. W przypadku problemu z certyfikatem, napraw łańcuch certyfikatów lub konfigurację zaufania niezależnie.

4. Użyj własnej kontroli stanu złącza

Oficjalny łącznik ONLYOFFICE zawiera specjalnie opracowane polecenie diagnostyczne:

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

W dokumentacji łącznika podano, że to sprawdzenie zgłasza albo pomyślne połączenie, albo przyczynę błędu. Jest to bardziej przydatne niż testowanie tylko strony docelowej Serwera Dokumentów, ponieważ sprawdza integrację z perspektywy NextCloud.

Jeśli sprawdzenie wskazuje, że serwer dokumentów jest osiągalny, ale walidacja tokenu się nie powiedzie, wróć do klucza tajnego i nagłówka. Jeśli w ogóle nie można nawiązać połączenia z serwerem, rozwiąż problemy z DNS, routingiem, zaporą sieciową, TLS lub wewnętrznym adresem URL, zanim poświęcisz więcej czasu na JWT.

5. Sprawdź czas tylko wtedy, gdy dowody na to wskazują

Tokeny JWT mogą zawierać żądania związane z czasem, a łącznik Nextcloud udostępnia jwt_leewayi jwt_expirationudostępnia ustawienia. Nie oznacza to, że należy najpierw zwiększyć margines błędu. Istotnie błędny zegar może spowodować awarię poprawnych tokenów; zwiększenie marginesu błędu może ukryć problem z infrastrukturą.

Porównaj czas UTC na hostach lub kontenerach Nextcloud i ONLYOFFICE:

date -u
timedatectl status

Upewnij się, że oba systemy niezawodnie synchronizują czas. Dopiero po potwierdzeniu niewielkiej, prawidłowej różnicy w taktowaniu, rozważ wąsko ograniczony margines błędu. Obsługiwane ustawienia JWT konektora są wymienione w oficjalnym dokumencie referencyjnym dotyczącym konfiguracji konektora .

Jak działa walidacja JWT w tej integracji

ONLYOFFICE Docs używa JWT do ochrony inicjalizacji edytora i żądań serwer-serwer. Jego API oddziela tokeny przeglądarki od przychodzących i wychodzących tokenów żądań HTTP. W przypadku żądań przychodzących token może być przenoszony w nagłówku lub, w przypadku obsługiwanych żądań POST, w treści żądania. W przypadku żądań GET, ONLYOFFICE dokumentuje obsługę tokenów opartą na nagłówkach. Zobacz oficjalną dokumentację dotyczącą sygnatur żądań .

To wyjaśnia, dlaczego jedna operacja może działać, a inna kończy się niepowodzeniem. Na przykład otwarcie edytora może się powieść, podczas gdy późniejsze wywołanie zwrotne lub żądanie pobrania zakończy się niepowodzeniem, jeśli tylko jeden kierunek ma poprawne ustawienia tokena.

Powszechne błędne przekonania

„Jeśli /healthcheck zwróci wartość true, to JWT musi być poprawny.”

Nie. Punkt końcowy stanu potwierdza, że ​​usługa odpowiada, ale nie potwierdza, że ​​łącznik Nextcloud i Serwer Dokumentów korzystają z tego samego tajnego klucza JWT i nagłówka. Działanie: uruchom occ onlyoffice:documentserver --checki sprawdź prawidłowe ustawienia łącznika.

„Mogę edytować plik local.json w kontenerze Docker i gotowe”.

To jest delikatne dla wdrożeń Dockera. ONLYOFFICE zaleca ustawienie JWT za pomocą zmiennych środowiskowych Dockera, ponieważ uruchomienie może zregenerować konfigurację. Działanie: zdefiniuj JWT_ENABLED, JWT_SECRET, i , w razie potrzeby, JWT_HEADERw konfiguracji kontenera i utwórz go ponownie.

„AuthorizationJWT jest zawsze wymaganym nagłówkiem.”

Nie. Aktualna oficjalna konfiguracja Serwera Dokumentów jest Authorizationdomyślnie wymieniona jako nagłówek, chociaż istniejące wdrożenia i starsze przykłady mogą używać innego, jawnie skonfigurowanego nagłówka. Działanie: odczytaj obie aktywne konfiguracje i zmień ich tożsamość.

„Najszybszym rozwiązaniem jest wyłączenie JWT”.

Może usunąć natychmiastowy błąd walidacji, ale usuwa również kontrolę bezpieczeństwa i może zamaskować podstawową niezgodność. Działanie: popraw współdzielony sekret/nagłówek, chyba że masz celowy, udokumentowany powód, aby działać bez JWT.

Ostateczna lista kontrolna walidacji

• Ten sam sekret JWT jest skonfigurowany w Nextcloud i ONLYOFFICE Docs.
• Nazwa nagłówka JWT jest taka sama po obu stronach.
• Wdrożenia Dockera korzystają ze stałych zmiennych środowiskowych, a nie z doraźnych edycji wewnątrz kontenera.
• Publiczne i wewnętrzne adresy URL serwera są dostępne w kierunku, w którym zostały użyte.
• Żadna reguła proxy nie powoduje nieoczekiwanego usunięcia lub przepisania nagłówka JWT.
• Systemy Nextcloud i ONLYOFFICE mają zsynchronizowane zegary.
• occ onlyoffice:documentserver --checkudaje się.
• Prawdziwy dokument otwiera się, edytuje, automatycznie zapisuje, zamyka i otwiera ponownie z zapisanymi zmianami.

Jeśli błąd tokena nadal występuje

Jeśli sekrety i nagłówki są zgodne, zegary są zsynchronizowane, a sprawdzenie łącznika kończy się powodzeniem, ale konkretna operacja nadal zgłasza nieprawidłowy token, przed zmianą dalszych ustawień należy zarejestrować dokładny kierunek nieudanego żądania i odpowiednie logi. ONLYOFFICE rozróżnia walidację przeglądarki, skrzynki odbiorczej i nadawczej, więc kolejne pytanie brzmi, czy błąd wystąpił podczas inicjalizacji edytora, polecenia wysłanego do serwera dokumentów, czy też wywołania zwrotnego/pobrania wysłanego z powrotem do NextCloud.

Używaj logów serwera dokumentów razem z logami Nextcloud i logami proxy dla tego samego znacznika czasu. Unikaj publikowania całych tokenów JWT lub sekretów. Jeśli musisz porównać strukturę tokenów, usuń podpis i poufne deklaracje. Sposób działania funkcji podpisywania i walidacji opisano w dokumentacji podpisów ONLYOFFICE .