Cómo configurar la autenticación con clave secreta JWT de ONLYOFFICE

La autenticación JWT de ONLYOFFICE solo funciona cuando el servidor de documentos y la aplicación de integración utilizan la misma clave secreta. En las implementaciones actuales de Docker, la validación JWT está habilitada de forma predeterminada. Para una integración estable, configure su propia clave persistente JWT_SECRETen lugar de depender del valor generado automáticamente por el contenedor y, a continuación, configure la misma clave secreta en Nextcloud, su gestor de documentos personalizado o cualquier conector que se comunique con ONLYOFFICE Docs.

Esta guía práctica se centra en la configuración que probablemente necesite: Docker y Docker Compose, integraciones personalizadas para la firma de la configuración del editor, comportamiento de encabezados y cuerpos, verificación, rotación y errores comunes. Se basa en la documentación actual de ONLYOFFICE, revisada en octubre de 2026.

Referencia rápida

A partir de ONLYOFFICE Docs 7.2, las implementaciones de Docker habilitan JWT de forma predeterminada y generan una clave secreta aleatoria si no se proporciona ninguna. La documentación oficial de Docker advierte que una clave secreta generada automáticamente puede cambiar después de un reinicio o la recreación del contenedor y provocar fallos en las integraciones. Para cualquier implementación real, establezca una clave secreta explícita. Consulte la sección «Configuración de JWT para ONLYOFFICE Docs» y la guía de instalación oficial de Docker .

1. Identifique el contenedor ONLYOFFICE y el método de implementación.

Para un host Docker, comience con:

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
docker images | grep onlyoffice

Determina si la instancia se inició con docker runDocker Compose, un panel de control u otra capa de orquestación. Debes modificar la configuración de origen que crea el contenedor. Editar un archivo generado dentro del contenedor no es una solución permanente.

En el caso específico de Docker, ONLYOFFICE recomienda a los administradores usar variables de entorno en lugar de editar manualmente el archivo /etc/onlyoffice/documentserver/local.json. Si se editan los valores JWT directamente en ese archivo, el proceso de inicio de Docker puede restaurarlos o regenerarlos cuando se reinicie el contenedor.

2. Genera un secreto seguro y guárdalo de forma segura.

Un comando de shell conveniente es:

openssl rand -hex 32

Esto genera 32 bytes aleatorios representados como 64 caracteres hexadecimales. ONLYOFFICE no requiere este formato exacto; lo importante es que ambas partes compartan la misma clave secreta y que sea difícil de adivinar.

Trátelo JWT_SECRETcomo una contraseña o una credencial de API:

• No lo subas a un repositorio Git público.
• No lo incluyas en el código JavaScript del frontend que se envía a los navegadores.
• Restringir el acceso al archivo de entorno de Compose o al almacén de secretos que lo contiene.
• Utilice una clave secreta diferente para entornos distintos, como producción y pruebas.

La documentación de firmas de ONLYOFFICE advierte explícitamente que la firma del token debe realizarse en el servidor, ya que cualquier código del lado del navegador que contenga el secreto lo expone a los usuarios. Los ejemplos oficiales utilizan HMAC-SHA256 ( HS256). Consulte la documentación de firmas JWT de ONLYOFFICE .

3. Configurar JWT en Docker Compose

Un servicio Compose mínimo puede incluir:

services:
  documentserver:
    image: onlyoffice/documentserver:latest
    restart: unless-stopped
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: "${ONLYOFFICE_JWT_SECRET}"
      JWT_HEADER: "Authorization"
      JWT_IN_BODY: "false"
    ports:
      - "8080:80"

Mantén el secreto real fuera del archivo Compose siempre que sea posible. Por ejemplo, colócalo en un .envarchivo con permisos restringidos:

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

A continuación, asegúrese de que ese archivo esté excluido del control de versiones y que solo puedan leerlo los administradores o la cuenta de servicio que lo necesite.

El repositorio oficial de ONLYOFFICE Docker-DocumentServer documenta JWT_ENABLED, JWT_SECRET, JWT_HEADER, y JWT_IN_BODY. El código de inicio actual de Docker habilita la validación JWT por defecto, utiliza Authorizationcomo encabezado predeterminado y genera un secreto aleatorio cuando no se proporciona uno explícito.

4. Recrea el contenedor para que se aplique el nuevo entorno.

Para componer:

docker compose up -d --force-recreate
docker compose ps

Para un contenedor creado originalmente con docker run, la guía oficial de JWT indica a los administradores que detengan y eliminen el contenedor antiguo, y luego creen uno nuevo con las variables de entorno JWT. No eliminen los volúmenes persistentes ni los datos montados mediante enlace durante este proceso.

También puedes inspeccionar el entorno del contenedor en ejecución sin imprimir el secreto en sí:

docker inspect onlyoffice-documentserver \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep '^JWT_' \
  | sed 's/^JWT_SECRET=.*/JWT_SECRET=[REDACTED]/'

Si el nombre del contenedor es diferente, sustitúyalo onlyoffice-documentserversegún corresponda.

5. Configure el mismo secreto en la integración.

Esta es la parte que con mayor frecuencia se pasa por alto. Habilitar JWT en ONLYOFFICE Docs sin configurar la gestión de documentos provoca que se rechacen las solicitudes del editor. El conector o la aplicación personalizada deben firmar las solicitudes con la misma clave secreta.

Ejemplo de Nextcloud

En la configuración de ONLYOFFICE para Nextcloud, introduzca la misma clave secreta que utiliza el servidor de documentos. El nombre del encabezado también debe coincidir. La documentación actual de la integración de ONLYOFFICE con Nextcloud enumera jwt_secrety jwt_headercomo configuraciones del conector, con Authorizationcomo encabezado predeterminado normal. Consulte la documentación oficial del conector de Nextcloud .

Si su conector tiene un campo etiquetado como "Clave secreta", "Secreto JWT" o similar, no genere un segundo secreto independiente allí. Copie el mismo valor del secreto.

6. Para una integración personalizada, firme la configuración completa del editor en el servidor.

tokenPara una aplicación personalizada, primero cree la configuración del editor, firme esa configuración en el servidor y, a continuación, asigne el JWT resultante a la propiedad de nivel superior .

Ejemplo de Node.js:

import jwt from "jsonwebtoken";

const config = {
  documentType: "word",
  document: {
    fileType: "docx",
    key: "document-2026-001",
    title: "Project Plan.docx",
    url: "https://files.example.com/project-plan.docx"
  },
  editorConfig: {
    callbackUrl: "https://app.example.com/onlyoffice/callback"
  }
};

config.token = jwt.sign(config, process.env.ONLYOFFICE_JWT_SECRET, {
  algorithm: "HS256"
});

La documentación de ONLYOFFICE sobre la firma del navegador indica que la carga útil del token para abrir un archivo debe tener la misma estructura que la configuración del editor. Desde la versión 7.1, el conjunto de parámetros involucrados en la validación está estrictamente regulado para esta operación, por lo que firmar una estructura obsoleta o incompleta es una causa común de fallos. Consulte Firma del token del navegador .

La configuración resultante que se pasa DocsAPI.DocEditorcontiene el token:

new DocsAPI.DocEditor("placeholder", config);

La referencia oficial de la API define config.tokencomo la firma cifrada utilizada por ONLYOFFICE Docs para validar la configuración del editor.

7. Comprender los tokens de encabezado frente a los tokens de cuerpo.

En ONLYOFFICE, JWT abarca más que la configuración del editor del navegador. También se utiliza para solicitudes entre servicios, como tráfico de comandos, conversiones y devoluciones de llamada.

ONLYOFFICE admite tokens de solicitud tanto en el cuerpo como en la cabecera. En sus preguntas frecuentes sobre seguridad se indica que las cabeceras pueden alcanzar los límites de longitud específicos del servidor y, por lo tanto, se recomienda el uso de tokens en el cuerpo para las solicitudes entrantes que lo permitan. A partir de la versión 7.1 de la documentación, el token del cuerpo de la solicitud entrante tiene prioridad cuando está presente; de ​​lo contrario, se utiliza el token de la cabecera. El remitente puede enviar ambos. Consulte la documentación de tokens de solicitud de ONLYOFFICE .

La variable de Docker JWT_IN_BODYtiene un valor predeterminado false, así que no la habilite solo porque existe. Cámbiela únicamente cuando su integración esté diseñada para enviar y validar tokens de cuerpo de forma consistente.

8. Prueba con una solicitud real del editor.

Una secuencia de validación útil es:

1. Abra un documento a través de su integración real.
2. Verifique que el editor se cargue sin errores de token.
3. Haz una pequeña modificación.
4. Cierra el editor o activa la ruta de guardado normal.
5. Verifique que la aplicación de almacenamiento reciba y acepte la devolución de llamada.

Una página de bienvenida exitosa en el servidor de documentos no demuestra que JWT esté configurado correctamente entre las dos aplicaciones. Los errores de JWT suelen aparecer solo cuando la integración envía la configuración del editor, el comando, la solicitud de conversión o la devolución de llamada.

La descripción general de seguridad oficial explica el comportamiento esperado: ONLYOFFICE valida un token y utiliza los valores de la carga útil firmada; si el token falta o no es válido cuando se requiere la validación, la solicitud se rechaza. Consulte la descripción general de seguridad de la documentación de ONLYOFFICE .

9. Compruebe el estado y los registros de JWT cuando falle la autenticación.

El código de inicio actual de Docker dirige a los administradores al asistente de estado JWT. Con el nombre de contenedor correcto, ejecute:

docker exec onlyoffice-documentserver \
  sudo documentserver-jwt-status.sh

También puede inspeccionar los registros:

docker logs --tail 200 onlyoffice-documentserver
docker exec onlyoffice-documentserver \
  find /var/log/onlyoffice/documentserver -type f -maxdepth 3 -print

Si una integración falla inmediatamente después de cambiar el secreto, compare estos elementos en orden:

• ¿Está JWT_ENABLEDrealmente habilitado en el contenedor recreado?
• ¿La integración utiliza exactamente el mismo código secreto, incluyendo mayúsculas y puntuación?
• ¿El conector utiliza el mismo nombre de encabezado JWT?
• Para un editor personalizado, ¿estás firmando el mismo objeto de configuración que envías al navegador?
• ¿Las devoluciones de llamada y las solicitudes de comandos también están firmadas y validadas según lo requerido?
• ¿Se truncó, interpretó o reemplazó algún secreto almacenado en un archivo de shell o Compose mediante la expansión de una variable de entorno?

Patrones de fallos comunes

“Token no válido” o “Firma no válida”

La causa más probable es una discrepancia en la clave secreta o un token firmado con una carga útil diferente a la de la solicitud que se está validando. Genere un nuevo token después de cualquier cambio de configuración relevante. No reutilice ningún token de ejemplo de la documentación; estos ejemplos están firmados con claves secretas de demostración y no son válidos para su servidor.

Funciona hasta que Docker se reinicia.

Esto suele significar que la implementación dependía del secreto JWT generado automáticamente. ONLYOFFICE advierte explícitamente que se puede regenerar un secreto aleatorio después de reiniciar o recrear el contenedor. Configúrelo JWT_SECRETusted mismo e introduzca el mismo valor en la integración.

Nextcloud muestra un error de conexión o de token.

Primero, verifique el secreto y el encabezado en ambos lados. La documentación de Nextcloud de ONLYOFFICE requiere que el conector jwt_headercoincida con el encabezado configurado en Document Server. El valor predeterminado actual normal es Authorization.

Una solicitud firmada grande devuelve un error HTTP.

Investiga si el JWT se envía en una cabecera que excede el límite de tamaño de cabecera del proxy o del servidor web. Las preguntas frecuentes sobre seguridad de ONLYOFFICE explican que esta es una de las razones por las que se prefieren los tokens en el cuerpo para las solicitudes POST aplicables.

Rotación segura del secreto JWT

Es necesario coordinar la rotación de la clave secreta JWT. No tiene sentido cambiar solo el servidor de documentos mientras el conector sigue firmando con la clave secreta anterior.

Para una implementación sencilla de instancia única:

1. Genera el nuevo secreto y guárdalo de forma segura.
2. Programe una breve ventana de mantenimiento si los editores activos pudieran verse afectados.
3. Actualizar la clave secreta de la integración y la del servidor de documentos JWT_SECRETcomo un único cambio coordinado.
4. Vuelva a crear el contenedor del servidor de documentos.
5. Abra, edite y guarde un documento de prueba.
6. Confirme que las funciones de devolución de llamada funcionan correctamente antes de volver a utilizar el servicio con normalidad.

Para múltiples instancias de Document Server detrás de un balanceador de carga, todas las instancias que dan servicio a la misma integración necesitan una configuración JWT compatible durante el cambio. Planifique el despliegue en lugar de rotar un nodo de forma improvisada.

Lista de verificación de producción

• Secreto persistente: configúrelo JWT_SECRETexplícitamente; no confíe en el valor generado aleatoriamente.
• El mismo secreto en todas partes: el servidor de documentos y la integración deben compartir el mismo valor.
• Firma en el servidor: nunca exponga el secreto en el código del servidor/navegador.
• HS256: utilice el método HMAC-SHA256 que se muestra en los ejemplos de código oficiales de ONLYOFFICE.
• Acuerdo de encabezado: si un conector envía JWT a través de un encabezado con nombre, ese nombre debe coincidir con el del servidor de documentos.
• Recreación del contenedor: Los cambios en el entorno Docker requieren la recreación del contenedor.
• Prueba de integración real: abrir, editar, guardar y verificar el comportamiento de la función de devolución de llamada.
• Almacenamiento secreto: mantenga el secreto fuera de los repositorios y registros públicos.
• Rotación controlada: actualice ambos lados simultáneamente y verifique antes de finalizar el mantenimiento.

En resumen

Para una instalación de ONLYOFFICE basada en Docker, la configuración persistente es sencilla: genere un secreto seguro, configúrelo JWT_ENABLED=truemediante JWT_SECRETvariables de entorno del contenedor, vuelva a crear el contenedor y configure el mismo secreto en su conector o backend. Las integraciones personalizadas deben firmar la configuración del editor y las solicitudes de servicio en el servidor con HS256, nunca en el código del navegador.

Si JWT deja de funcionar repentinamente tras un reinicio, compruebe si la clave secreta se configuró como persistente. Si falla inmediatamente después de un cambio de configuración, compare la clave secreta, el encabezado y la carga útil firmada antes de buscar en otro lugar. Estas tres comprobaciones resuelven la mayoría de los errores de configuración de JWT sin debilitar la autenticación.