Como corrigir o erro “Falha na validação da prova WOPI” no Collabora Online

Comece pelo sistema que registrou a falha.

“Falha na validação da prova WOPI” significa que um host WOPI não conseguiu verificar uma solicitação assinada do Collabora Online. Em uma configuração típica do Nextcloud Office, o Nextcloud é o host WOPI e o Collabora é o cliente WOPI: o Collabora envia a solicitação assinada e o host a verifica. A redação exata varia de acordo com a integração e a versão, portanto, primeiro identifique qual componente emitiu a mensagem e qual solicitação falhou.

A prova é uma verificação de segurança, não um teste geral de conectividade. Ela associa uma solicitação ao token de acesso, à URL completa da solicitação e a um registro de data e hora, e então assina esses dados com a chave de prova privada da Collabora. O host verifica a assinatura usando uma chave de prova pública publicada no XML de descoberta da Collabora. A definição do protocolo WOPI descreve os campos e cabeçalhos assinados.

Primeira ação: reproduza a falha uma vez, anote o horário, a ação do arquivo, o status HTTP e o ID da solicitação ou correlação e, em seguida, inspecione os logs da plataforma de armazenamento e do Collabora coolwsdem busca do mesmo evento. Não publique tokens de acesso, cabeçalhos de prova ou chaves privadas em um ticket.

Tabela de diagnóstico rápido

1. A confirmação da descoberta expõe a chave pública atual.

A Collabora publica suas funcionalidades WOPI e informações de chave de prova no endpoint de descoberta. A partir de uma máquina que possa acessar a URL da Collabora usada pelo seu servidor de armazenamento, inspecione:

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

Procure no XML um proof-keyelemento com um `current` valuee, quando presente, um `private` oldvalue. Não confunda este material público com a chave privada armazenada no servidor Collabora. A comparação mais útil é a resposta de descoberta obtida pelo próprio host WOPI, pois um navegador ou a estação de trabalho de um administrador podem receber uma resposta diferente por meio de DNS, um proxy ou um cache.

Verificado: a integração WOPI do Collabora usa assinaturas de prova e a chave pública é disponibilizada por meio da descoberta. Ação: busque a descoberta no host/container que valida as solicitações e, em seguida, confirme se o XML é válido e corresponde ao endpoint do Collabora configurado na plataforma de armazenamento. O guia de vinculação do Collabora ao SharePoint descreve a geração da chave de prova e o comportamento da descoberta.

2. Verifique se a chave privada existe e é legível.

No Collabora, verifique o log de inicialização em busca de avisos de que o arquivo de chave de prova está ausente ou ilegível. O serviço Collabora precisa conseguir ler a chave privada para assinatura. Para implantações empacotadas, o caminho de configuração e a conta de serviço podem variar; verifique o diretório configurado do serviço e as montagens de volume do contêiner em vez de assumir um caminho de host.

Consulte a documentação do Collabora coolconfig generate-proof-keypara casos em que a configuração automática de chaves não funcionou. Não execute este comando como uma solução de problemas de rotina em um cluster em funcionamento. A geração de uma nova chave altera a identidade de assinatura. Se o lado do armazenamento ainda confiar em uma resposta de descoberta antiga, as solicitações poderão continuar falhando até que o host atualize a chave pública que utiliza.

sudo coolconfig generate-proof-key

Use esse comando somente após confirmar que a chave está ausente ou é inválida e após planejar como cada nó do Collabora e host do WOPI receberá as informações da chave correspondente. Em seguida, siga o procedimento de recarregamento de serviço documentado para o seu pacote ou implantação de contêiner e busque novamente a descoberta no caminho de rede do validador.

3. Procure por incompatibilidades de chave entre nós ou caches.

Um único servidor Collabora pode funcionar enquanto uma implementação com balanceamento de carga apresenta falhas intermitentes. Por exemplo, um nó pode ter uma chave privada recém-gerada enquanto outro ainda assina com a chave antiga; um host com dados de descoberta em cache pode não confiar em nenhuma das duas chaves de forma consistente. Essa é uma causa dependente da implementação, e não uma prova de que todo erro intermitente seja causado pela rotação de chaves.

Ação: busque os dados /hosting/discoveryatravés do balanceador de carga e diretamente de cada backend, se permitido. Compare os valores das chaves públicas e verifique se o cache de descoberta do host WOPI está atualizado. Se os nós utilizarem chaves separadas intencionalmente, verifique se a integração de armazenamento suporta essa topologia; caso contrário, mantenha a configuração da chave de prova consistente em todo o cluster. A atualização da descoberta deve utilizar o mecanismo suportado pela integração. Evite editar o cache do banco de dados ou reiniciar serviços não relacionados sem evidências.

4. Compare a URL assinada com a URL validada pelo host.

A comprovação abrange o URL absoluto da solicitação WOPI em maiúsculas, bem como o token e o carimbo de data/hora. Isso torna a reescrita de URL relevante. Um proxy reverso pode alterar o nome do host, o esquema, a porta, o caminho ou o escape visíveis externamente. Se o Collabora assinar uma solicitação para um URL, mas o host WOPI reconstruir um URL diferente para verificação, uma assinatura correta poderá parecer inválida.

Ação: correlacione uma requisição com falha nas camadas de proxy e de aplicação. Compare o esquema, o nome do host, a porta explícita, o caminho e os caracteres codificados vistos pelo validador com a URL usada no código de validação de prova. Verifique o tratamento de cabeçalhos `forwarded-host` e `forwarded-proto` somente se a aplicação depender deles. Preserve a URL real da requisição; não "corrija" o problema desativando as verificações de assinatura ou confiando em cabeçalhos encaminhados arbitrários.

5. Validar o registro de data e hora e o tratamento de bytes.

A prova WOPI inclui o X-WOPI-TimeStampcabeçalho `<timestamp>`. Na especificação WOPI da Microsoft, esse cabeçalho é um inteiro de 64 bits medido em intervalos de 100 nanossegundos desde 1º de janeiro de 0001, e não um timestamp Unix em segundos. Um validador personalizado que o interprete como segundos Unix, omita dígitos, altere a codificação ou monte os bytes assinados incorretamente pode rejeitar solicitações válidas.

A discrepância de relógio é uma possível causa quando um host impõe um período de atualização, mas a tolerância exata depende da implementação de validação. As diretrizes da Microsoft para o Microsoft 365 para a Web usam uma verificação de idade de 20 minutos; não assuma que esse número se aplica a todas as integrações do Collabora. Ação: verifique a sincronização NTP e o horário UTC nos sistemas Collabora e de armazenamento e, em seguida, inspecione a regra de carimbo de data/hora e o código de análise documentados do host.

Verifique também a construção em nível de byte se você mantiver um host WOPI personalizado. O token é UTF-8; os comprimentos são contagens de bytes; a URL é a URL absoluta completa em maiúsculas; e o valor do carimbo de data/hora deve ser representado exatamente como especificado. A chave pública deve corresponder à chave privada usada pela instância do Collabora que enviou a solicitação.

6. Separe as falhas de comprovação dos erros de lista de permissões e TLS.

Uma lista de permissões de hosts WOPI define quais hosts de armazenamento o Collabora pode contatar. A validação TLS determina se o certificado de um par de rede é confiável. A validação de prova verifica a assinatura em uma solicitação WOPI. Esses controles estão relacionados à integração segura, mas não são intercambiáveis. Adicionar um host a uma lista de permissões não corrigirá uma incompatibilidade de assinatura; desativar as verificações TLS não corrigirá uma chave pública de prova desatualizada.

Para implantações do Nextcloud, o guia oficial de solução de problemas recomenda verificar os caminhos HTTP(S) necessários em ambas as direções, revisar os logs do Nextcloud e do Collabora e confirmar as entradas da lista de permissões do WOPI para avisos de lista de permissões. Ação: siga a categoria de erro no log. Teste o endpoint de descoberta e a acessibilidade da rede separadamente do validador de provas. Não amplie uma lista de permissões como *solução alternativa.

Sequência de recuperação segura

1. Registre o horário exato da solicitação com falha e identifique qual serviço registrou a falha na validação da prova.
2. Verifique os logs do Collabora em busca de avisos de chave ausente; inspecione o XML de descoberta no caminho de rede do host WOPI.
3. Compare a chave pública na descoberta com a chave privada e a configuração do nó usadas para assinar a solicitação.
4. Verifique a consistência do balanceador de carga, o cache de descoberta e quaisquer alterações recentes em chaves, nomes de host, proxies ou TLS.
5. Compare o tratamento do URL da solicitação assinada e do carimbo de data/hora sem expor tokens ou cabeçalhos de prova.
6. Realize o teste com um único documento e confirme se a mesma solicitação é bem-sucedida nos logs do host antes de restaurar o tráfego normal.

Se o problema persistir, colete logs anonimizados de ambas as extremidades, incluindo as versões do Collabora e do armazenamento, o tipo de implantação, se um ou vários nós estão envolvidos, o XML de descoberta com os segredos removidos e a rota do proxy para a solicitação com falha. Compartilhe essas informações com o fornecedor ou os responsáveis ​​pela integração. A string de erro exata, por si só, não determina se a causa é uma descoberta desatualizada, canonicalização de URL, um problema de relógio ou um bug no validador personalizado; as evidências no nível da solicitação determinam qual caminho seguir.