Cómo solucionar el error “WOPI Proof Validation Failed” en Collabora Online

Comience con el sistema que registró el fallo.

El mensaje "Error de validación de prueba de WOPI" significa que un host de WOPI no pudo verificar una solicitud firmada de Collabora Online. En una configuración típica de Nextcloud Office, Nextcloud actúa como host de WOPI y Collabora como cliente: Collabora envía la solicitud firmada y el host la verifica. La redacción exacta varía según la integración y la versión, por lo que primero debe identificar qué componente emitió el mensaje y qué solicitud falló.

La prueba es una verificación de seguridad, no una prueba de conectividad general. Vincula una solicitud con el token de acceso, la URL completa de la solicitud y una marca de tiempo, y luego firma esos datos con la clave de prueba privada de Collabora. El host verifica la firma utilizando una clave de prueba pública publicada en el XML de descubrimiento de Collabora. La definición del protocolo WOPI describe los campos y encabezados firmados.

Primera acción: reproduzca el fallo una vez, anote la hora, la acción del archivo, el estado HTTP y el ID de la solicitud o correlación; luego, revise los registros de la plataforma de almacenamiento y de Collabora coolwsdpara detectar el mismo evento. No publique tokens de acceso, encabezados de prueba ni claves privadas en un ticket.

Tabla de diagnóstico rápido

1. Confirmar el descubrimiento expone la clave pública actual.

Collabora publica sus capacidades WOPI e información de clave de prueba en el punto final de descubrimiento. Desde una máquina que pueda acceder a la URL de Collabora utilizada por su servidor de almacenamiento, inspeccione:

curl -fsS https://office.example.com/hosting/discovery

Busque en el XML un proof-keyelemento con un valor actual valuey, si está presente, un valor oldvalue. No confunda este material público con la clave privada almacenada en el servidor de Collabora. La comparación más útil es la respuesta de descubrimiento obtenida por el propio host WOPI, ya que un navegador o la estación de trabajo de un administrador pueden recibir una respuesta diferente a través de DNS, un proxy o una caché.

Verificado: La integración WOPI de Collabora utiliza firmas de prueba y la clave pública se obtiene mediante descubrimiento. Acción: Obtener el descubrimiento del host/contenedor que valida las solicitudes y, a continuación, confirmar que el XML es válido y coincide con el punto final de Collabora configurado en la plataforma de almacenamiento. La guía de enlace de Collabora SharePoint describe la generación de claves de prueba y el comportamiento del descubrimiento.

2. Compruebe si la clave privada existe y es legible.

En Collabora, revise el registro de inicio para detectar advertencias sobre la ausencia o ilegibilidad del archivo de clave de prueba. El servicio de Collabora debe poder leer la clave privada para la firma. En implementaciones empaquetadas, la ruta de configuración y la cuenta de servicio pueden variar; verifique el directorio configurado del servicio y los puntos de montaje del volumen del contenedor en lugar de asumir una ruta de host.

Collabora documenta coolconfig generate-proof-keylos casos en los que la configuración automática de claves no funcionó. No ejecute este comando como una herramienta de solución de problemas rutinaria en un clúster en funcionamiento. Generar una nueva clave cambia la identidad de firma. Si el sistema de almacenamiento aún confía en una respuesta de descubrimiento anterior, las solicitudes pueden seguir fallando hasta que el host actualice la clave pública que utiliza.

sudo coolconfig generate-proof-key

Utilice ese comando solo después de confirmar que la clave no existe o es inválida y tras planificar cómo cada nodo de Collabora y host WOPI recibirá la información de la clave correspondiente. A continuación, siga el procedimiento de recarga del servicio documentado para su paquete o implementación de contenedor y vuelva a obtener la información de detección desde la ruta de red del validador.

3. Busque discrepancias de claves entre nodos o cachés.

Un único servidor Collabora puede funcionar correctamente mientras que una implementación con balanceo de carga falla intermitentemente. Por ejemplo, un nodo puede tener una clave privada recién generada, mientras que otro sigue firmando con la clave antigua; un host con datos de descubrimiento en caché puede no confiar en ninguna de las dos de forma consistente. Esta es una causa que depende de la implementación, no una prueba de que todos los errores intermitentes se deban a la rotación de claves.

Acción: obtenga los datos /hosting/discoverya través del balanceador de carga y directamente desde cada servidor backend, si está permitido. Compare los valores de la clave pública y verifique que la caché de descubrimiento del host WOPI esté actualizada. Si los nodos usan claves separadas intencionalmente, verifique que la integración de almacenamiento admita esa topología; de lo contrario, mantenga la configuración de la clave de prueba consistente en todo el clúster. La actualización del descubrimiento debe usar el mecanismo compatible con la integración. Evite editar la caché de la base de datos o reiniciar servicios no relacionados sin evidencia.

4. Compare la URL firmada con la URL que valida el host.

La prueba abarca la URL de la solicitud WOPI en mayúsculas, así como el token y la marca de tiempo. Esto hace que la reescritura de URL sea relevante. Un proxy inverso puede cambiar el nombre de host, el esquema, el puerto, la ruta o el escape visibles externamente. Si Collabora firma una solicitud para una URL, pero el host WOPI reconstruye una URL diferente para su verificación, una firma correcta puede parecer inválida.

Acción: correlacione una solicitud fallida en las capas de proxy y aplicación. Compare el esquema, el nombre de host, el puerto explícito, la ruta y los caracteres codificados que ve el validador con la URL utilizada en el código de prueba-validación. Verifique el manejo de forwarded-host y forwarded-proto solo si la aplicación depende de esos encabezados. Conserve la URL de solicitud real; no "solucione" el problema deshabilitando las comprobaciones de firma ni confiando en encabezados reenviados arbitrarios.

5. Validar la marca de tiempo y el manejo de bytes.

La prueba WOPI incluye X-WOPI-TimeStamp. En la especificación WOPI de Microsoft, este encabezado es un entero de 64 bits medido en intervalos de 100 nanosegundos desde el 1 de enero de 0001, no una marca de tiempo Unix en segundos. Un validador personalizado que lo interprete como segundos Unix, omita dígitos, cambie la codificación o ensamble incorrectamente los bytes firmados puede rechazar solicitudes válidas.

La desviación horaria es una posible causa cuando un host impone un período de validez, pero la tolerancia exacta depende de la implementación de validación. La guía de Microsoft para Microsoft 365 para la web utiliza una comprobación de antigüedad de 20 minutos; no asuma que este valor se aplica a todas las integraciones de Collabora. Acción: compruebe la sincronización NTP y la hora UTC en los sistemas de Collabora y almacenamiento, y luego inspeccione la regla de marca de tiempo documentada y el código de análisis del host.

Verifique también la estructura a nivel de bytes si administra un host WOPI personalizado. El token está en UTF-8; las longitudes se expresan en bytes; la URL es la URL absoluta completa en mayúsculas; y el valor de la marca de tiempo debe representarse exactamente como se especifica. La clave pública debe corresponder a la clave privada utilizada por la instancia de Collabora que envió la solicitud.

6. Separe los fallos de prueba de los errores de la lista de permitidos y de TLS.

Una lista de hosts permitidos de WOPI determina con qué hosts de almacenamiento puede conectarse Collabora. La validación TLS determina si el certificado de un par de red es de confianza. La validación de prueba comprueba la firma de una solicitud WOPI. Estos controles están relacionados con la integración segura, pero no son intercambiables. Agregar un host a una lista de hosts permitidos no solucionará una discrepancia en la firma; desactivar las comprobaciones TLS no corregirá una clave de prueba pública obsoleta.

Para implementaciones de Nextcloud, la guía oficial de solución de problemas recomienda verificar las rutas HTTP(S) requeridas en ambas direcciones, revisar los registros de Nextcloud y Collabora, y confirmar las entradas de la lista de permitidos de hosts de WOPI para detectar advertencias de la lista de permitidos. Acción: siga la categoría de error en el registro. Pruebe el punto final de descubrimiento y la accesibilidad de la red por separado del validador de prueba. No amplíe una lista de permitidos como *solución alternativa.

Secuencia de recuperación segura

1. Capture la hora exacta en que falló la solicitud e identifique qué servicio registró el fallo de validación de la prueba.
2. Compruebe los registros de Collabora en busca de advertencias de claves faltantes; inspeccione el XML de descubrimiento desde la ruta de red del host WOPI.
3. Compare la clave pública en el proceso de descubrimiento con la clave privada y la configuración del nodo utilizadas para firmar la solicitud.
4. Verifique la coherencia del balanceador de carga, el almacenamiento en caché de descubrimiento y cualquier cambio reciente en la clave, el nombre de host, el proxy o TLS.
5. Compare la URL de la solicitud firmada y el manejo de la marca de tiempo sin exponer los tokens ni los encabezados de prueba.
6. Vuelva a realizar la prueba con un documento y confirme en los registros del host que la misma solicitud se realiza correctamente antes de restablecer el tráfico normal.

Si el fallo persiste, recopile los registros anonimizados de ambos extremos, las versiones de Collabora y del almacenamiento, el tipo de implementación, si intervienen uno o varios nodos, el XML de descubrimiento sin secretos y la ruta del proxy para la solicitud fallida. Comparta esta información con el proveedor o los responsables del mantenimiento de la integración. La cadena de error exacta por sí sola no permite determinar si la causa es un descubrimiento obsoleto, la canonización de la URL, un problema de reloj o un error del validador personalizado; la evidencia a nivel de solicitud determina qué camino seguir.