Исправлена ​​ошибка «Токен недействителен» в интеграции ONLYOFFICE с Nextcloud.

Сообщение ONLYOFFICE «Токен недействителен» обычно означает, что обе стороны интеграции не проверяют один и тот же JSON Web Token (JWT). В конфигурации Nextcloud важно понимать, что существует несколько путей передачи токена: конфигурация редактора, отправляемая в браузер, входящие запросы к ONLYOFFICE Docs и исходящие запросы, такие как обратные вызовы в Nextcloud. Сбой на любом из этих путей может выглядеть одинаково для пользователя.

Прежде чем начать изменять настройки, важно учесть один важный момент: JWT включен по умолчанию в ONLYOFFICE Docs начиная с версии 7.2 , и сервер документов может автоматически генерировать секрет. Это делает старое руководство, в котором говорится «оставьте JWT отключенным», неподходящим для современной установки. В настоящее время ONLYOFFICE рекомендует настроить собственный секрет и использовать тот же секрет в коннекторе. См. руководство по настройке JWT в ONLYOFFICE .

Краткий справочник: что проверить в первую очередь

1. Убедитесь, что общий секретный ключ действительно тот же самый.

Проверка JWT зависит от общего секрета. ONLYOFFICE Docs подписывает токены этим секретом, а принимающая сторона проверяет подпись, используя то же значение. Разница в один символ, пробел в конце, старая переменная окружения или повторно сгенерированный секрет Docker могут привести к тому, что проверка токена, выглядящего действительным, завершится неудачей.

В Nextcloud коннектор поддерживает эту jwt_secretнастройку. Официальный коннектор также предоставляет occинтерфейс конфигурации, позволяющий проверить значение, которое Nextcloud фактически использует, вместо того, чтобы полагаться на файл конфигурации, который, как вам кажется, активен. Текущие настройки коннектора описаны в официальном файле README коннектора 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

Не копируйте секретный ключ в заявки в службу поддержки, скриншоты, историю командной строки, которой вы делитесь с другими, или в публичные отчеты о проблемах. Сравните его локально.

Для установки ONLYOFFICE Docs в Linux поддерживается следующий конфигурационный файл:

/etc/onlyoffice/documentserver/local.json

В документации ONLYOFFICE разделяются настройки токенов для браузера, входящих и исходящих сообщений. Секретные значения, используемые для проверки, должны соответствовать конфигурации вашего коннектора. Не редактируйте файл default.json; ONLYOFFICE явно предупреждает, что значения по умолчанию могут быть перезаписаны при перезапуске или обновлении. Используйте local.jsonдля установки пакетов.

Если вы запускаете ONLYOFFICE Docs в Docker

Используйте переменные среды Docker вместо ручного редактирования local.jsonвнутри контейнера. ONLYOFFICE утверждает, что Docker может перегенерировать конфигурацию JWT во время запуска; его официальный образ поддерживает JWT_ENABLED, JWT_SECRET, JWT_HEADER, и JWT_IN_BODY. В текущей документации к образу Docker Authorizationв качестве заголовка JWT по умолчанию указан . См. официальный репозиторий Docker DocumentServer .

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

После изменения переменных среды Docker, пересоздайте контейнер, чтобы запущенный сервис их получил. Простое редактирование файла Compose без пересоздания контейнера не изменяет его существующую среду.

2. Убедитесь, что заголовок JWT точно соответствует заданному значению.

Распространенное заблуждение заключается в том, что название заголовка носит чисто декоративный характер. Это не так. В документации ONLYOFFICE есть настраиваемые заголовки токенов для входящих и исходящих сообщений, а в коннекторе Nextcloud есть соответствующая jwt_headerнастройка. Они должны описывать один и тот же путь запроса.

В текущей документации по API ONLYOFFICE в качестве сервера документов по умолчанию для входящих запросов JWT указан Authorizationсервер документов, а в официальной документации по интеграции с Nextcloud также указан Authorizationстандартный параметр коннектора по умолчанию. В более старых примерах и существующих установках может использоваться AuthorizationJWTили другое явно заданное значение. Таким образом, безопасное правило заключается не в том, чтобы «всегда использовать одну конкретную строку», а в том, чтобы активная конфигурация совпадала с обеих сторон .

Формат запроса также имеет значение. В документации API ONLYOFFICE показаны токены заголовка, отправляемые с использованием схемы Bearer. Подробную информацию о базовом протоколе см. в документации ONLYOFFICE по токенам в заголовках .

Если вы намеренно используете пользовательский заголовок, установите одинаковое значение в обоих продуктах. Если нет причин для его настройки, использование текущего значения по умолчанию Authorizationуменьшает количество изменяемых элементов.

3. Проверьте, не изменяет ли обратный прокси-сервер путь к токену.

Если настройки Nextcloud и ONLYOFFICE совпадают, но ошибка сохраняется, проверьте путь между ними. Обратный прокси-сервер, шлюз аутентификации, WAF или контроллер входящего трафика могут влиять на заголовки авторизации. Это зависит от вашей системы, поэтому не следует предполагать, что виноват прокси-сервер, без доказательств.

Используйте следующую последовательность практических тестов:

• Убедитесь, что общедоступный URL-адрес сервера документов доступен с хоста Nextcloud.
• Убедитесь, что внутренний URL-адрес сервера документов, если он настроен, разрешается с сервера или контейнера Nextcloud.
• Убедитесь, что внутренний URL-адрес Nextcloud/хранилища разрешается с хоста или контейнера ONLYOFFICE Docs.
• Просмотрите журналы доступа/ошибок прокси-сервера во время проверки коннектора.
• Если ваш прокси-сервер имеет явные правила для этого Authorization, подтвердите, что он пересылает заголовок, а не заменяет или удаляет его.

Не отключайте JWT только для того, чтобы ошибка исчезла. Это удалит механизм проверки, а не исправит его. Также не отключайте проверку TLS в качестве решения проблемы с JWT: проверка сертификата и проверка подписи JWT — это разные процессы. Если у вас проблема с сертификатом, исправьте цепочку сертификатов или конфигурацию доверия независимо друг от друга.

4. Используйте встроенную проверку работоспособности разъема.

Официальный коннектор ONLYOFFICE включает в себя специально разработанную диагностическую команду:

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

В документации к коннектору указано, что эта проверка сообщает либо об успешном подключении, либо о причине ошибки. Она более полезна, чем тестирование только целевой страницы Document Server, поскольку проверяет интеграцию с точки зрения Nextcloud.

Если проверка показывает, что сервер документов доступен, но проверка токена не удалась, вернитесь к секрету и заголовку. Если связаться с сервером вообще не удаётся, прежде чем тратить время на JWT, решите проблемы с DNS, маршрутизацией, брандмауэром, TLS или внутренними URL-адресами.

5. Проверяйте время только тогда, когда на это указывают имеющиеся данные.

JWT-токены могут содержать утверждения, связанные со временем, и коннектор Nextcloud предоставляет jwt_leewayсоответствующие jwt_expirationнастройки. Это не означает, что следует сначала увеличивать допустимый отклонение. Существенно неверные часы могут привести к сбою в работе токенов, которые в остальном корректны; увеличение допустимого отклонения может скрыть проблему с инфраструктурой.

Сравните время UTC на хостах или контейнерах Nextcloud и ONLYOFFICE:

date -u
timedatectl status

Убедитесь, что обе системы надежно синхронизируют время. Только после подтверждения небольшой, но допустимой разницы во времени следует рассматривать возможность узкого отклонения. Поддерживаемые коннектором настройки JWT перечислены в официальном справочнике по конфигурации коннектора .

Как работает проверка JWT в этой интеграции

В документации ONLYOFFICE используется JWT для защиты инициализации редактора и запросов между серверами. Его API разделяет токены браузера от токенов входящих и исходящих HTTP-запросов. Для входящих запросов токен может передаваться в заголовке или, для поддерживаемых POST-запросов, в теле запроса. Для GET-запросов ONLYOFFICE описывает обработку токенов на основе заголовков. См. официальную документацию по подписи запроса .

Это объясняет, почему одна операция может сработать, а другая — нет. Например, открытие редактора может пройти успешно, в то время как последующий обратный вызов или запрос на загрузку завершится неудачей, если только в одном направлении установлены правильные настройки токена.

Распространенные заблуждения

«Если /healthcheck возвращает true, значит, JWT корректен».

Нет. Проверка работоспособности подтверждает, что служба отвечает; она не доказывает, что коннектор Nextcloud и Document Server используют один и тот же секретный ключ JWT и заголовок. Действие: запустите occ onlyoffice:documentserver --checkи проверьте действующие настройки коннектора.

«Я могу редактировать файл local.json внутри контейнера Docker и на этом всё».

Это ненадежно для развертывания в Docker. ONLYOFFICE рекомендует устанавливать JWT через переменные среды Docker, поскольку при запуске может произойти перегенерация конфигурации. Действие: определите JWT_ENABLED, JWT_SECRET, и, при необходимости, JWT_HEADERв конфигурации контейнера и пересоздайте контейнер.

«Заголовок AuthorizationJWT всегда является обязательным».

Нет. В текущей официальной конфигурации Document Server Authorizationв качестве заголовка по умолчанию указан другой заголовок, хотя в существующих развертываниях и более старых примерах может использоваться другой явно настроенный заголовок. Действие: прочтите обе активные конфигурации и сделайте их идентичными.

«Отключение JWT — это самое быстрое решение».

Это может устранить непосредственную ошибку проверки, но также снимает элемент контроля безопасности и может маскировать лежащее в основе несоответствие. Действие: исправьте общий секрет/заголовок, если у вас нет уважительной, документально подтвержденной причины работать без JWT.

Контрольный список окончательной проверки

• Один и тот же секретный ключ JWT настроен в Nextcloud и ONLYOFFICE Docs.
• Имя заголовка JWT совпадает с обеих сторон.
• При развертывании Docker используются постоянные переменные среды, а не внесение изменений в контейнер по мере необходимости.
• Доступ к публичным и внутренним URL-адресам серверов возможен в том направлении, где они используются.
• Ни одно правило прокси-сервера неожиданно не удаляет и не перезаписывает заголовок JWT.
• В системах Nextcloud и ONLYOFFICE часы синхронизированы.
• occ onlyoffice:documentserver --checkпреуспевает.
• Настоящий документ открывается, редактируется, автоматически сохраняется, закрывается и открывается заново с сохраненными изменениями.

Когда ошибка токена все еще сохраняется

Если секретные данные и заголовки совпадают, часы синхронизированы, и проверка коннектора проходит успешно, но конкретная операция по-прежнему сообщает о недействительном токене, необходимо зафиксировать точное направление запроса, приведшего к ошибке, и соответствующие журналы, прежде чем изменять дополнительные настройки. ONLYOFFICE различает проверку браузера, входящих и исходящих сообщений, поэтому следующий вопрос заключается в том, происходит ли ошибка во время инициализации редактора, команды, отправленной на сервер документов, или обратного вызова/загрузки, отправленной обратно в Nextcloud.

Используйте журналы Document Server вместе с журналами Nextcloud и прокси-сервера для одной и той же метки времени. Избегайте публичной публикации полных JWT-токенов или секретных ключей. Если вам необходимо сравнить структуру токенов, отредактируйте подпись и конфиденциальные данные. Описание эталонного поведения при подписании и проверке приведено в документации ONLYOFFICE по подписям .