Configurar las claves JWT de ONLYOFFICE en el servidor y el conector.

Utilice una clave secreta JWT segura y consistente: configúrela en ONLYOFFICE Docs, copie el mismo valor en la configuración de ONLYOFFICE de la plataforma conectada y mantenga habilitada la validación JWT. Docs 7.2 y versiones posteriores habilitan JWT de forma predeterminada y generan una clave secreta automáticamente; si se cambia la clave secreta, todas las integraciones deben actualizarse para que coincidan. El método exacto del lado del servidor depende de si Docs se ejecuta como un paquete de Linux o un contenedor Docker.

¿Qué debe coincidir?

JWT (JSON Web Token) permite a ONLYOFFICE Docs verificar las solicitudes firmadas. La plataforma de documentos y Docs deben usar la misma clave secreta y configuraciones de encabezado compatibles. El servidor utiliza configuraciones de token independientes para la configuración del navegador y las solicitudes de servicio entrantes y salientes; los valores de la clave secreta compartida protegen estos intercambios. No incluya la clave secreta en una página web pública, un paquete JavaScript del lado del cliente, un ticket de soporte ni un repositorio de código fuente de acceso público.

Antes de editar, identifique el tipo de implementación y registre la URL de la documentación que utiliza su conector. Genere una clave secreta larga e impredecible con un gestor de contraseñas o un generador criptográficamente seguro. Trátela como una credencial y guárdela en un almacén de configuración restringido.

Configurar una instalación de Linux

Para una instalación de Linux basada en paquetes, edite /etc/onlyoffice/documentserver/local.json. Conserve cualquier configuración existente: combine las siguientes claves en el JSON existente en lugar de reemplazar todo el archivo. El ejemplo muestra la estructura de validación de tokens y las tres ubicaciones secretas coincidentes descritas en la guía de configuración oficial:

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

Reemplace cada marcador de posición con el mismo valor secreto. No pegue el marcador de posición de ejemplo. Los interruptores browser, inbox, y outboxson independientes; habilitar solo uno no habilita toda la validación de solicitudes. La documentación 7.2 y posteriores tienen JWT habilitado de forma predeterminada, pero verificar explícitamente estas configuraciones ayuda al auditar una configuración existente o al alinear el comportamiento entre nodos. Para versiones anteriores a la 7.2, la guía oficial indica que se deben habilitar los tres interruptores.

Valide la sintaxis JSON antes de reiniciar. A continuación, reinicie los servicios del servidor de documentos para que se carguen los cambios.

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

Ejecute el comando con una cuenta autorizada para administrar los servicios del sistema. En Windows, el archivo de configuración es %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json; utilice las instrucciones de reinicio de Windows que se encuentran en la guía oficial en lugar del comando de Linux.

Configura Docker sin editar el archivo de configuración generado.

Para la imagen oficial de Docker del servidor de documentos, configure JWT mediante variables de entorno del contenedor. La guía oficial advierte que los cambios manuales generados local.jsonpueden deshacerse al reiniciar el contenedor. Configure JWT_ENABLED=truey JWT_SECRETen el comando de creación del contenedor o en el servicio Compose, y luego vuelva a crear el contenedor para que el entorno surta efecto. Guarde el secreto en un archivo de entorno protegido o en un gestor de secretos y restrinja los permisos de ese archivo; evite incluirlo en el control de versiones.

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

Defina ONLYOFFICE_JWT_SECRETel entorno de despliegue o .envel archivo protegido. Fije una etiqueta de imagen probada en lugar de depender de latest, y consulte la documentación para la etiqueta exacta que utiliza. Después de cambiar los valores del entorno, recree el contenedor con su proceso de despliegue habitual. Un simple reinicio puede dejar el entorno anterior.

Actualiza el conector y protege el secreto.

Abra la configuración de integración en la plataforma que se conecta a ONLYOFFICE Docs, como Nextcloud u otro conector compatible. Introduzca la misma clave secreta JWT en el campo correspondiente y guarde. Confirme también la URL del servidor de documentos configurada y, si el conector la expone, el encabezado de autorización. El encabezado predeterminado en ONLYOFFICE Docs es Authorization; cámbielo solo si ambas partes están configuradas para usar la misma alternativa.

Un error de coincidencia de clave secreta suele manifestarse como un token no válido o un error de autorización al abrir o guardar un documento. Este error también puede ocurrir cuando solo se actualiza un nodo de Docs detrás de un balanceador de carga. Si utiliza varios nodos, sincronice la misma configuración de clave secreta y token en todos ellos antes de enviarles tráfico. Implemente los cambios de forma gradual: actualice Docs y el conector simultáneamente, y tenga en cuenta que las sesiones de edición existentes o las solicitudes firmadas con el valor anterior podrían fallar durante la transición.

Cualquier persona que pueda leer la clave secreta puede crear tokens que el servidor podría aceptar. Limite el acceso a los archivos de configuración y las variables de despliegue, utilice un transporte cifrado para la conexión entre el conector y Docs, y rote la clave secreta si existe la posibilidad de que haya quedado expuesta. La rotación requiere actualizar todos los nodos de Docs y el conector con el nuevo valor; no deje credenciales antiguas en archivos ni registros.

Verificar la configuración

• Confirme que el servicio o contenedor de Docs se esté ejecutando después del cambio de configuración.
• Para una implementación de Docker, ejecute este comando sudo docker exec <container_name> sudo documentserver-jwt-status.shpara inspeccionar el estado de JWT. Utilice el nombre real del contenedor. Esta herramienta auxiliar está documentada para Docker; no asuma que está disponible en todas las instalaciones de paquetes.
• Abra un documento a través de la plataforma conectada, realice una pequeña modificación inofensiva y guárdelo. Confirme que el editor se abre y que la plataforma recibe el cambio guardado.
• Si la autenticación falla, compare carácter por carácter la clave secreta del servidor y del conector, compruebe que todos los interruptores de token relevantes estén habilitados y verifique la configuración del encabezado de la solicitud.

La guía de configuración oficial es la fuente de referencia para la configuración compatible y el comportamiento de las versiones. Consulte la documentación de configuración JWT de ONLYOFFICE y los parámetros de instalación oficiales de Docker para la versión específica que implemente.