Solucionar el error "El token no es válido" de ONLYOFFICE en Nextcloud

Si Nextcloud informa que el token no es válido al conectarse a ONLYOFFICE Docs, asegúrese de que el secreto JWT del conector coincida con el secreto que utiliza Document Server. En ONLYOFFICE Docs 7.2 y versiones posteriores, la validación JWT está activada de forma predeterminada y se genera un secreto automáticamente; modificar únicamente la configuración de Nextcloud o editar el archivo de configuración generado por un contenedor Docker puede provocar una desincronización entre ambos sistemas.

Mantenga JWT habilitado. Primero, identifique el secreto activo y el tipo de implementación, actualice la configuración correcta y, a continuación, ejecute la comprobación de conexión del conector. La comprobación debería indicar una conexión exitosa; el simple hecho de que se abra el editor del navegador no demuestra que las descargas de documentos y las devoluciones de llamada funcionen correctamente.

¿Qué te indica el error?

JWT (JSON Web Token) es un token firmado que se utiliza para verificar la confianza depositada en una solicitud entre Nextcloud y ONLYOFFICE Docs. El conector firma las solicitudes con su clave secreta configurada, mientras que Document Server las valida con la suya. Si las claves secretas de firma difieren, la firma del token no se puede validar y la solicitud se rechaza.

Las causas más comunes son una clave secreta copiada de una instalación antigua, una clave secreta generada automáticamente que nunca se introdujo en Nextcloud, una variable de entorno de Docker modificada que no se aplicó al recrear el contenedor, o valores de clave secreta inconsistentes en la configuración del servidor de documentos. Un encabezado JWT personalizado también puede provocar una discrepancia si el conector y el servidor de documentos no utilizan el mismo nombre de encabezado.

Este artículo aborda el problema de coincidencia de JWT. Si el error indica que no se puede acceder al servidor, que el certificado no es válido o que no se puede descargar un documento, revise por separado las direcciones del servidor, el certificado TLS y la ruta de red entre Nextcloud y el servidor de documentos. Una corrección de JWT no solucionará estos problemas.

1. Encuentra la clave secreta activa del servidor de documentos.

Utilice la configuración del servidor de documentos en ejecución. No dé por sentado que un secreto guardado de un contenedor o servidor anterior sigue activo.

• Linux: inspeccionar /etc/onlyoffice/documentserver/local.json.
• Windows: inspeccionar %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json.
• Docker: lee el secreto del contenedor en ejecución. La imagen oficial también admite la lectura del secreto de sesión con este comando:

sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

Sustituya <containerID>con el nombre o ID real del contenedor. Considere el valor devuelto como una credencial: no lo pegue en foros de soporte, capturas de pantalla ni registros públicos.

En local.json, compare los valores en services.CoAuthoring.secret.inbox.string, services.CoAuthoring.secret.outbox.string, y services.CoAuthoring.secret.session.string. Todos deberían ser idénticos para esta configuración estándar. Confirme también que la validación de tokens esté habilitada para el navegador, la bandeja de entrada de solicitudes y la bandeja de salida de solicitudes. Las versiones de la documentación anteriores a la 7.2 requieren que la validación de tokens esté habilitada explícitamente; las versiones posteriores la habilitan por defecto.

2. Actualizar el conector ONLYOFFICE de Nextcloud.

1. Inicia sesión como administrador de Nextcloud y abre Configuración > Administración > ONLYOFFICE .
2. En la configuración del servidor, introduzca la clave secreta exacta que se encuentra en el servidor de documentos en ejecución, en el campo Clave secreta . Evite los espacios al principio o al final y no añada comillas a menos que formen parte de la clave secreta.
3. Verifique la configuración del encabezado JWT si su implementación utiliza un encabezado personalizado. La jwt_headerconfiguración del conector y el encabezado de token configurado en el servidor de documentos deben coincidir. Si no ha personalizado el encabezado intencionalmente, no lo modifique durante esta reparación.
4. Guarda la configuración. Mantén JWT habilitado en ambos lados.

La configuración del conector documentada también se puede cambiar con occel comando de Nextcloud desde el directorio de instalación de Nextcloud:

sudo -u www-data php occ config:app:set onlyoffice jwt_secret --value='YOUR_SECRET'

Sustituya YOUR_SECRETel valor por el valor real. El uso de comillas en la shell ayuda a preservar la puntuación, pero los secretos que contienen una sola comilla requieren un método más seguro que insertarlos directamente en la línea de comandos. Los argumentos de la línea de comandos también pueden ser visibles para la inspección de procesos privilegiados o el historial de la shell. Siempre que sea posible, utilice la interfaz de administrador y verifique el valor almacenado sin exponerlo.

3. Aplique el cambio de la manera correcta para su instalación.

Docker o Docker Compose

Para implementaciones de Docker, configure JWT a través del entorno del contenedor en lugar de editar manualmente el archivo generado automáticamente local.json. Establezca el mismo secreto en la definición del servicio del servidor de documentos:

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

Después de modificar el archivo Compose, vuelva a crear el contenedor del servidor de documentos para que el entorno surta efecto. Por ejemplo, desde el directorio que contiene el archivo Compose:

docker compose up -d --force-recreate <documentserver-service>

Sustituya el nombre del servicio por el de su propio archivo Compose. Un simple reinicio no aplica un valor de entorno modificado a un contenedor existente. Si utiliza docker run, vuelva a crear el contenedor con los valores actualizados JWT_ENABLED, JWT_SECRETconservando sus puertos, volúmenes y demás opciones necesarias. No elimine un contenedor de producción hasta que haya confirmado la configuración y el montaje de datos persistentes.

Cuando se inicie el contenedor, vuelva a leer su clave secreta activa con el comando anterior y asegúrese de que el valor siga coincidiendo con Nextcloud. Evite colocar una clave secreta de producción en un archivo Compose o repositorio de código fuente compartido públicamente.

Paquete de Linux o instalación de Windows

Si configura intencionadamente un secreto personalizado en local.json, asegúrese de que los tres campos del secreto coincidan y de que los valores de validación de token necesarios estén habilitados. Aplique el cambio reiniciando los servicios del servidor de documentos correspondientes. Las instrucciones actuales de ONLYOFFICE enumeran ds-converter, ds-docservicey ds-metricsen Linux; las instalaciones gestionadas por un supervisor de servicio diferente pueden requerir el método de reinicio adecuado para esa configuración. En Windows, reinicie los servicios de ONLYOFFICE después de guardar la configuración.

Una discrepancia que persiste tras reiniciar suele indicar que una configuración o entorno de despliegue generado está sobrescribiendo el archivo editado. En Docker, mueva la corrección a las variables de entorno y vuelva a crear el contenedor. Para despliegues empaquetados, revise la configuración activa y la configuración de inicio del servicio antes de modificar más ajustes.

Verificar la reparación

1. En el directorio de instalación de Nextcloud, ejecute la comprobación oficial del conector:

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

Si no es así, utilice la cuenta de servidor web adecuada para su instalación www-data. El comando debería indicar una conexión exitosa. Si aún así indica un token no válido, confirme nuevamente que el secreto activo del servidor de documentos en ejecución coincide exactamente con Nextcloud y que cualquier encabezado JWT personalizado es correcto.

2. Abra un pequeño documento de prueba desde Nextcloud con ONLYOFFICE. Confirme que el editor se carga, realice un pequeño cambio, guárdelo, cierre el editor y vuelva a abrir el archivo para confirmar que el cambio se ha guardado.
3. Si la comprobación informa de un error de red o de certificado, deje de modificar los valores JWT. Verifique que Nextcloud pueda acceder a la dirección del servidor de documentos y que este pueda acceder a la dirección de devolución de llamada de Nextcloud. Utilice un certificado TLS de confianza siempre que sea posible; deshabilitar la verificación del certificado es una solución provisional insegura y no soluciona el problema de la validación del token.

Estas comprobaciones verifican que la conexión configurada y una ruta de guardado básica funcionan correctamente. No garantizan que todas las rutas de proxy inverso, configuraciones de almacenamiento externo o topologías de múltiples servidores sean correctas; pruebe esas rutas por separado si su implementación las utiliza.

Referencias oficiales

• ONLYOFFICE: Integración con Nextcloud y configuración de JWT
• ONLYOFFICE: Configurar JWT para el servidor de documentos
• Conector ONLYOFFICE para Nextcloud: opciones de configuración y comandos occ

Los detalles de configuración se verificaron con la documentación oficial de ONLYOFFICE y el repositorio de conectores el 9 de octubre de 2026. Las etiquetas de la interfaz de usuario y la administración de servicios pueden variar según el conector, el sistema operativo y el método de implementación.