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.

Si utiliza deliberadamente un encabezado personalizado, configure el mismo valor en ambos productos. Si no tiene motivos para personalizarlo, usar la configuración predeterminada actual Authorizationreduce la complejidad.

3. Compruebe si un proxy inverso está cambiando la ruta del token.

Si la configuración de Nextcloud y ONLYOFFICE coincide, pero el error persiste, revise la ruta entre ellas. Un proxy inverso, una puerta de enlace de autenticación, un WAF o un controlador de entrada pueden afectar los encabezados de autorización. Esto depende de su infraestructura, así que no dé por sentado que el proxy es el culpable sin pruebas.

Utilice esta secuencia de prueba práctica:

• Confirme que la URL pública del servidor de documentos sea accesible desde el host de Nextcloud.
• Confirme que la URL interna del servidor de documentos, si está configurada, se resuelve desde el servidor o contenedor de Nextcloud.
• Confirme que la URL interna de Nextcloud/almacenamiento se resuelve desde el host o contenedor de ONLYOFFICE Docs.
• Inspeccione los registros de acceso/error del proxy mientras ejecuta la comprobación del conector.
• Si su proxy tiene reglas explícitas para Authorization, confirme que reenvía en lugar de reemplazar o eliminar el encabezado.

No desactive JWT solo para que desaparezca el error. Esto elimina el mecanismo de validación en lugar de repararlo. Tampoco desactive la verificación TLS como solución para JWT: la verificación del certificado y la validación de la firma JWT son controles independientes. Si tiene un problema con el certificado, corrija la cadena de certificados o la configuración de confianza de forma independiente.

4. Utilice la comprobación de estado del propio conector.

El conector oficial de ONLYOFFICE incluye un comando de diagnóstico diseñado específicamente para ello:

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

La documentación del conector indica que esta comprobación informa si la conexión se realizó correctamente o si se produjo un error. Resulta más útil que probar únicamente la página de inicio del servidor de documentos, ya que permite comprobar la integración desde la perspectiva de Nextcloud.

Si la comprobación indica que el servidor de documentos es accesible, pero la validación del token falla, vuelva al secreto y al encabezado. Si no puede acceder al servidor en absoluto, solucione los problemas de DNS, enrutamiento, cortafuegos, TLS o URL internas antes de dedicar más tiempo a JWT.

5. Verifica la hora solo cuando la evidencia lo indique.

Los JWT pueden incluir declaraciones relacionadas con el tiempo, y el conector de Nextcloud expone esta información jwt_leewayy jwt_expirationconfiguraciones. Esto no significa que debas aumentar el margen de tolerancia de inmediato. Un reloj con un error significativo puede provocar que tokens que, de otro modo, serían correctos, fallen; aumentar el margen de tolerancia puede ocultar el problema de infraestructura.

Compara la hora UTC en los hosts o contenedores de Nextcloud y ONLYOFFICE:

date -u
timedatectl status

Asegúrese de que ambos sistemas sincronicen la hora de forma fiable. Solo después de confirmar una pequeña diferencia horaria legítima debería considerar un margen de tolerancia muy ajustado. La configuración JWT compatible con el conector se detalla en la referencia oficial de configuración del conector .

Cómo funciona la validación de JWT en esta integración

ONLYOFFICE Docs utiliza JWT para proteger la inicialización del editor y las solicitudes entre servidores. Su API separa los tokens del navegador de los tokens de las solicitudes HTTP entrantes y salientes. Para las solicitudes entrantes, el token puede incluirse en la cabecera o, para las solicitudes POST compatibles, en el cuerpo de la solicitud. Para las solicitudes GET, ONLYOFFICE documenta el manejo de tokens basado en la cabecera. Consulte la documentación oficial sobre la firma de solicitudes .

Esto explica por qué una operación puede funcionar mientras que otra falla. Por ejemplo, abrir el editor puede tener éxito, pero una devolución de llamada o solicitud de descarga posterior puede fallar si solo una de las direcciones tiene la configuración de token correcta.

conceptos erróneos comunes

“Si /healthcheck devuelve verdadero, el JWT debe ser correcto.”

No. Un punto final de estado demuestra que el servicio responde; no demuestra que el conector de Nextcloud y el servidor de documentos compartan el mismo secreto JWT y encabezado. Acción: ejecute occ onlyoffice:documentserver --checke inspeccione la configuración efectiva del conector.

“Puedo editar local.json dentro de un contenedor Docker y listo.”

Esto es frágil para las implementaciones de Docker. ONLYOFFICE recomienda configurar JWT a través de variables de entorno de Docker porque el inicio puede regenerar la configuración. Acción: defina JWT_ENABLED, JWT_SECRET, y, cuando sea necesario, JWT_HEADERen la configuración de su contenedor y vuelva a crear el contenedor.

“AuthorizationJWT es siempre el encabezado requerido.”

No. La configuración oficial actual del servidor de documentos incluye Authorizationcomo encabezado predeterminado, aunque las implementaciones existentes y los ejemplos anteriores pueden usar otro encabezado configurado explícitamente. Acción: leer ambas configuraciones activas y hacerlas idénticas.

“Desactivar JWT es la solución más rápida.”

Si bien puede eliminar el error de validación inmediato, también elimina un control de seguridad y puede ocultar la discrepancia subyacente. Acción: corrija el secreto/encabezado compartido a menos que tenga una razón documentada y justificada para operar sin JWT.

Lista de verificación de validación final

• La misma clave secreta JWT está configurada en Nextcloud y en la documentación de ONLYOFFICE.
• El nombre del encabezado JWT coincide en ambos lados.
• Las implementaciones de Docker utilizan variables de entorno persistentes, no una edición puntual dentro del contenedor.
• Las URL de los servidores públicos e internos son accesibles en la dirección en la que se utilizan.
• Ninguna regla de proxy elimina o reescribe inesperadamente el encabezado JWT.
• Los sistemas Nextcloud y ONLYOFFICE tienen sus relojes sincronizados.
• occ onlyoffice:documentserver --checktiene éxito.
• Un documento real se abre, se edita, se guarda automáticamente, se cierra y se vuelve a abrir con los cambios guardados.

Cuando el error del token aún persiste

Si los secretos y los encabezados coinciden, los relojes están sincronizados y la comprobación del conector se realiza correctamente, pero una operación específica sigue informando de un token no válido, capture la dirección exacta de la solicitud fallida y los registros correspondientes antes de cambiar más configuraciones. ONLYOFFICE distingue la validación del navegador, la bandeja de entrada y la bandeja de salida, por lo que la siguiente pregunta es si el fallo se produce durante la inicialización del editor, un comando enviado al servidor de documentos o una devolución de llamada/descarga enviada a Nextcloud.

Utilice los registros del servidor de documentos junto con los registros de Nextcloud y los registros del proxy para la misma marca de tiempo. Evite publicar JWT completos o secretos públicamente. Si necesita comparar la estructura del token, oculte la firma y las declaraciones confidenciales. El comportamiento de referencia para la firma y la validación se describe en la documentación de firmas de ONLYOFFICE .