Настройка секретных JWT-ключей ONLYOFFICE на сервере и в коннекторе.

Используйте один надежный секретный ключ JWT постоянно: настройте его в ONLYOFFICE Docs, скопируйте то же значение в настройки ONLYOFFICE подключенной платформы и оставьте проверку JWT включенной. В Docs 7.2 и более поздних версиях JWT включен по умолчанию и автоматически генерируется секретный ключ; изменение секретного ключа означает, что каждую интеграцию необходимо обновить в соответствии с ним. Точный метод на стороне сервера зависит от того, работает ли Docs как пакет Linux или контейнер Docker.

Что должно совпадать?

JWT (JSON Web Token) позволяет ONLYOFFICE Docs проверять подписанные запросы. Платформа документов и сам Docs должны использовать один и тот же секретный ключ и совместимые настройки заголовка. Сервер использует отдельные настройки токена для конфигурации браузера и входящих и исходящих запросов к сервису; общие значения секретного ключа защищают эти обмены. Не размещайте секретный ключ на общедоступной веб-странице, в пакете JavaScript на стороне клиента, в заявке в службу поддержки или в общедоступном репозитории исходного кода.

Перед редактированием определите тип развертывания и запишите URL-адрес документации, используемый вашим коннектором. Сгенерируйте длинный, непредсказуемый секрет с помощью менеджера паролей или криптографически защищенного генератора. Рассматривайте его как учетные данные и храните в защищенном хранилище конфигурации.

Настройка установки Linux

Для установки Linux на основе пакетов отредактируйте файл /etc/onlyoffice/documentserver/local.json. Сохраните все существующие настройки: объедините следующие ключи с существующим JSON-файлом, а не заменяйте весь файл. В примере показана структура проверки токенов и три соответствующих расположения секретов, описанных в официальном руководстве по настройке:

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

Замените каждый заполнитель точно таким же секретным значением. Не вставляйте сам пример заполнителя. Переключатели browser, inbox, и outboxявляются отдельными; включение только одного не включает проверку всех запросов. В Docs 7.2 и более поздних версиях JWT включен по умолчанию, но явная проверка этих параметров помогает при аудите существующей конфигурации или согласовании поведения между узлами. Для версий до 7.2 в официальном руководстве рекомендуется включить все три переключателя.

Перед перезапуском проверьте синтаксис JSON. Затем перезапустите службы сервера документов, чтобы изменения вступили в силу:

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

Выполните команду от имени учетной записи, имеющей права на управление системными службами. В Windows файл конфигурации находится по адресу %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json; вместо команды Linux используйте инструкции по перезагрузке Windows из официального руководства.

Настройте Docker без редактирования сгенерированного конфигурационного файла.

Для официального образа Docker Document Server установите JWT через переменные среды контейнера. В официальном руководстве предупреждается, что ручное изменение сгенерированных данных local.jsonможет быть отменено при перезапуске контейнера. Установите JWT_ENABLED=trueи JWT_SECRETв команде создания контейнера или в службе Compose, затем пересоздайте контейнер, чтобы изменения среды вступили в силу. Храните секрет в защищенном файле среды или менеджере секретов и ограничьте права доступа к этому файлу; избегайте добавления его в систему контроля версий.

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

Определите параметры ONLYOFFICE_JWT_SECRETв среде развертывания или защищенном .envфайле. Закрепите проверенный тег образа, а не полагайтесь на другой latest, и проверьте документацию, чтобы узнать точный тег, который вы используете. После изменения значений среды пересоздайте контейнер, используя обычный процесс развертывания. Простая перезагрузка может сохранить старую среду.

Обновите коннектор и защитите секрет.

Откройте настройки интеграции на платформе, которая подключается к ONLYOFFICE Docs, например, Nextcloud или другом поддерживаемом коннекторе. Введите тот же секретный JWT-код в поле secret-key и сохраните. Также подтвердите настроенный URL-адрес сервера документов и, если коннектор его предоставляет, заголовок авторизации. Заголовок по умолчанию в ONLYOFFICE Docs — Authorization; изменяйте его только в том случае, если обе стороны настроены на использование одного и того же альтернативного заголовка.

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

Любой, кто может прочитать секретный ключ, может создавать токены, которые сервер может принимать. Ограничьте доступ к файлам конфигурации и переменным развертывания, используйте зашифрованный транспорт для соединения коннектора с Docs и обновляйте секретный ключ, если он мог быть раскрыт. Обновление требует обновления всех узлов Docs и коннектора до нового значения; не оставляйте старые учетные данные в зарегистрированных файлах или журналах.

Проверьте конфигурацию

• Убедитесь, что служба или контейнер Docs запущены после изменения конфигурации.
• Для развертывания в Docker выполните команду sudo docker exec <container_name> sudo documentserver-jwt-status.shдля проверки статуса JWT. Используйте фактическое имя контейнера. Эта вспомогательная команда задокументирована для Docker; не следует предполагать, что она доступна в каждой установке пакета.
• Откройте документ через подключенную платформу, внесите небольшие безобидные изменения и сохраните его. Убедитесь, что редактор открылся и платформа получила сохраненные изменения.
• Если аутентификация не удалась, сравните секретные ключи сервера и коннектора посимвольно, убедитесь, что все соответствующие переключатели токена включены, и проверьте конфигурацию заголовка запроса.

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