Fix "Token is Not Valid" Error in ONLYOFFICE Nextcloud Integration

The ONLYOFFICE message “Token is not valid” usually means the two sides of the integration are not validating the same JSON Web Token (JWT). In a Nextcloud setup, the important point is that there are several token paths: the editor configuration sent to the browser, incoming requests to ONLYOFFICE Docs, and outgoing requests such as callbacks to Nextcloud. A failure in any one of them can look similar from the user side.

One current detail matters before you start changing settings: JWT has been enabled by default in ONLYOFFICE Docs since version 7.2, and the Document Server can generate a secret automatically. That makes an old tutorial that says “leave JWT disabled” a poor baseline for a modern installation. ONLYOFFICE’s current guidance is to configure your own secret and use the same secret in the connector. See ONLYOFFICE’s JWT configuration guide.

Quick reference: what to check first

1. Confirm the shared secret is actually the same

JWT validation depends on a shared secret. ONLYOFFICE Docs signs tokens with that secret, and the receiving side verifies the signature using the same value. A one-character difference, trailing whitespace, old environment variable, or regenerated Docker secret is enough to make a valid-looking token fail verification.

On Nextcloud, the connector supports the jwt_secret setting. The official connector also provides an occ configuration interface, so you can inspect the value that Nextcloud is actually using instead of relying on a configuration file you think is active. The connector’s current settings are documented in the official ONLYOFFICE Nextcloud connector README.

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

Do not paste the secret into support tickets, screenshots, shell history shared with others, or public issue reports. Compare it locally.

For a native Linux installation of ONLYOFFICE Docs, the supported configuration file is:

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE documents separate browser, inbox, and outbox token settings. The secret values used for validation must be consistent with your connector configuration. Do not edit default.json; ONLYOFFICE explicitly warns that defaults can be overwritten on restart or upgrade. Use local.json for package installations.

If you run ONLYOFFICE Docs in Docker

Use Docker environment variables rather than hand-editing local.json inside the container. ONLYOFFICE states that Docker can regenerate JWT configuration during startup; its official image supports JWT_ENABLED, JWT_SECRET, JWT_HEADER, and JWT_IN_BODY. The current Docker image documentation lists Authorization as the default JWT header. See the official Docker DocumentServer repository.

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

After changing Docker environment variables, recreate the container so the running service receives them. Merely editing a Compose file without recreating the container does not change its existing environment.

2. Make the JWT header match exactly

A common misunderstanding is that the header name is cosmetic. It is not. ONLYOFFICE Docs has configurable inbox and outbox token headers, and the Nextcloud connector has a jwt_header setting. They must describe the same request path.

Current ONLYOFFICE API documentation lists Authorization as the Document Server default for incoming JWT requests, and the official Nextcloud integration documentation likewise identifies Authorization as the normal connector default. Older examples and existing installations may use AuthorizationJWT or another explicitly configured value. The safe rule is therefore not “always use one specific string”; it is make the active configuration match on both sides.

The request format also matters. ONLYOFFICE’s API documentation shows header tokens sent using the Bearer scheme. For the underlying protocol details, see ONLYOFFICE token-in-header documentation.

إذا كنت تستخدم رأسًا مخصصًا عن قصد، فقم بضبط القيمة نفسها في كلا المنتجين. أما إذا لم يكن لديك سبب لتخصيصه، فإن استخدام القيمة الافتراضية الحالية Authorizationيقلل من عدد العناصر المتغيرة.

3. تحقق مما إذا كان الخادم الوكيل العكسي يقوم بتغيير مسار الرمز المميز

إذا كانت إعدادات Nextcloud وONLYOFFICE متطابقة ولكن الخطأ لا يزال قائماً، فافحص المسار بينهما. قد يؤثر خادم وكيل عكسي أو بوابة مصادقة أو جدار حماية تطبيقات الويب أو وحدة تحكم الدخول على رؤوس التفويض. يعتمد هذا على بنية نظامك، لذا لا تفترض أن الخادم الوكيل هو السبب دون دليل.

استخدم تسلسل الاختبار العملي هذا:

• تأكد من إمكانية الوصول إلى عنوان URL الخاص بخادم المستندات العام من مضيف Nextcloud.
• تأكد من أن عنوان URL الخاص بخادم المستندات الداخلي، إذا تم تكوينه، يتم حله من خادم أو حاوية Nextcloud.
• تأكد من أن عنوان URL الداخلي Nextcloud/storage يتم حله من مضيف أو حاوية ONLYOFFICE Docs.
• قم بفحص سجلات الوصول/الأخطاء الخاصة بالوكيل أثناء تشغيل فحص الموصل.
• إذا كان لدى خادم الوكيل الخاص بك قواعد صريحة لذلك Authorization، فتأكد من أنه يقوم بإعادة توجيه الطلب بدلاً من استبدال أو إزالة العنوان.

لا تُعطّل JWT لمجرد إخفاء الخطأ، فهذا يُزيل آلية التحقق بدلاً من إصلاحها. كذلك، لا تُعطّل التحقق من TLS كحلٍّ لمشكلة JWT، فالتحقق من الشهادة والتحقق من توقيع JWT عمليتان منفصلتان. إذا كانت لديك مشكلة في الشهادة، فقم بإصلاح سلسلة الشهادات أو إعدادات الثقة بشكل مستقل.

4. استخدم خاصية فحص الحالة الصحية الخاصة بالموصل

يتضمن موصل ONLYOFFICE الرسمي أمر تشخيصي مصمم خصيصًا لهذا الغرض:

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

تشير وثائق الموصل إلى أن هذا الفحص يُبلغ إما عن نجاح الاتصال أو عن سبب الخطأ. وهو أكثر فائدة من اختبار صفحة خادم المستندات فقط، لأنه يختبر التكامل من منظور Nextcloud.

إذا أظهر الفحص إمكانية الوصول إلى خادم المستندات ولكن فشل التحقق من صحة الرمز المميز، فارجع إلى السر والرأس. أما إذا تعذر الوصول إلى الخادم نهائيًا، فحل مشكلات نظام أسماء النطاقات (DNS) والتوجيه وجدار الحماية وبروتوكول أمان طبقة النقل (TLS) أو عنوان URL الداخلي قبل إضاعة المزيد من الوقت على JWT.

5. تحقق من الوقت فقط عندما تشير الأدلة إلى ذلك

قد تتضمن رموز JWT بيانات متعلقة بالوقت، ويكشف موصل Nextcloud عن هذه البيانات jwt_leewayويضبطها jwt_expiration. هذا لا يعني أنه يجب عليك زيادة هامش الخطأ أولاً. فوجود خطأ جوهري في الساعة قد يتسبب في فشل الرموز الصحيحة؛ بينما قد تؤدي زيادة هامش الخطأ إلى إخفاء مشكلة في البنية التحتية.

قارن التوقيت العالمي المنسق (UTC) على مضيفات أو حاويات Nextcloud و ONLYOFFICE:

date -u
timedatectl status

تأكد من مزامنة الوقت بين النظامين بدقة. لا تنظر في هامش خطأ محدود إلا بعد التأكد من وجود فرق زمني صغير ومشروع. تجد إعدادات JWT المدعومة للموصل في مرجع تكوين الموصل الرسمي .

كيف يعمل التحقق من صحة JWT في هذا التكامل

يستخدم ONLYOFFICE Docs تقنية JWT لحماية تهيئة المحرر وطلبات الخادم إلى الخادم. يفصل واجهة برمجة التطبيقات (API) الخاصة به رموز المتصفح عن رموز طلبات HTTP الواردة والصادرة. بالنسبة للطلبات الواردة، يمكن تضمين الرمز في ترويسة الطلب، أو في نص الطلب (لطلبات POST المدعومة). أما بالنسبة لطلبات GET، فتوثّق ONLYOFFICE كيفية التعامل مع الرموز في الترويسة. راجع توثيق توقيع الطلب الرسمي .

وهذا يفسر سبب نجاح عملية ما وفشل أخرى. على سبيل المثال، قد ينجح فتح المحرر بينما تفشل عملية استدعاء لاحقة أو طلب تنزيل إذا كان اتجاه واحد فقط يحتوي على إعدادات الرمز المميز الصحيحة.

المفاهيم الخاطئة الشائعة

"إذا أعاد الأمر /healthcheck القيمة true، فيجب أن يكون JWT صحيحًا."

لا. تُثبت نقطة نهاية الصحة أن الخدمة تستجيب، لكنها لا تُثبت أن موصل Nextcloud وخادم المستندات يشتركان في نفس سر JWT والرأس. الإجراء: تشغيل occ onlyoffice:documentserver --checkوفحص إعدادات الموصل الفعّالة.

"يمكنني تعديل ملف local.json داخل حاوية Docker وينتهي الأمر."

هذا الأمر غير مستقر في بيئات Docker. توصي ONLYOFFICE بتعيين JWT عبر متغيرات بيئة Docker لأن بدء التشغيل قد يُعيد إنشاء الإعدادات. الإجراء: حدد المتغيرات JWT_ENABLEDو JWT_SECRETو عند الحاجة، JWT_HEADERفي إعدادات الحاوية، ثم أعد إنشاء الحاوية.

"يُعدّ AuthorizationJWT دائمًا الترويسة المطلوبة."

لا. تُدرج قائمة التكوين الرسمية الحالية لخادم المستندات Authorizationكعنوان افتراضي، على الرغم من أن عمليات النشر الحالية والأمثلة القديمة قد تستخدم عنوانًا آخر مُكوّنًا بشكل صريح. الإجراء: اقرأ كلا التكوينين النشطين واجعلهما متطابقين.

"إيقاف تشغيل JWT هو الحل الأسرع."

قد يُزيل هذا الإجراء خطأ التحقق الفوري، ولكنه يُزيل أيضًا إجراءً أمنيًا، وقد يُخفي عدم التطابق الأساسي. الإجراء: أصلح السر/الرأس المشترك ما لم يكن لديك سبب موثق ومقصود للعمل بدون JWT.

قائمة التحقق النهائية للتحقق من الصحة

• تم تكوين نفس سر JWT في Nextcloud و ONLYOFFICE Docs.
• اسم رأس JWT متطابق على كلا الجانبين.
• تستخدم عمليات نشر Docker متغيرات بيئية ثابتة، وليس تعديلًا مخصصًا داخل الحاوية.
• يمكن الوصول إلى عناوين URL الخاصة بالخادم العام والداخلي في الاتجاه الذي يتم استخدامها فيه.
• لا توجد قاعدة وكيل تقوم بشكل غير متوقع بإزالة أو إعادة كتابة رأس JWT.
• يحتوي نظاما Nextcloud و ONLYOFFICE على ساعات متزامنة.
• occ onlyoffice:documentserver --checkينجح.
• يتم فتح مستند حقيقي، وتعديله، وحفظه تلقائيًا، وإغلاقه، ثم إعادة فتحه مع التغييرات المحفوظة.

عندما يستمر خطأ الرمز المميز

إذا تطابقت البيانات السرية والرؤوس، وتمت مزامنة الساعات، ونجح فحص الموصل، ولكن لا تزال عملية معينة تُبلغ عن رمز غير صالح، فقم بتسجيل اتجاه الطلب الفاشل والسجلات ذات الصلة قبل تغيير المزيد من الإعدادات. يميز ONLYOFFICE بين التحقق من صحة المتصفح والبريد الوارد والبريد الصادر، لذا فإن السؤال التالي هو ما إذا كان الفشل يحدث أثناء تهيئة المحرر، أو أمر مُرسل إلى خادم المستندات، أو رد اتصال/تنزيل مُرسل إلى Nextcloud.

استخدم سجلات خادم المستندات مع سجلات Nextcloud وسجلات الوكيل لنفس الطابع الزمني. تجنب نشر رموز JWT أو البيانات السرية كاملةً علنًا. إذا كنت بحاجة إلى مقارنة بنية الرمز المميز، فقم بإخفاء التوقيع والبيانات الحساسة. تجد وصفًا لسلوك التوقيع والتحقق المرجعي في وثائق التوقيع الخاصة بـ ONLYOFFICE .