Corrigir erro "Token inválido" na integração do ONLYOFFICE com o Nextcloud

A mensagem "Token inválido" do ONLYOFFICE geralmente significa que os dois lados da integração não estão validando o mesmo JSON Web Token (JWT). Em uma configuração do Nextcloud, o ponto importante é que existem vários caminhos de token: a configuração do editor enviada ao navegador, as solicitações recebidas pelo ONLYOFFICE Docs e as solicitações enviadas, como callbacks para o Nextcloud. Uma falha em qualquer um deles pode parecer semelhante para o usuário.

Um detalhe importante a considerar antes de começar a alterar as configurações: o JWT está habilitado por padrão no ONLYOFFICE Docs desde a versão 7.2 , e o Servidor de Documentos pode gerar um segredo automaticamente. Isso torna um tutorial antigo que dizia "deixe o JWT desabilitado" uma base inadequada para uma instalação moderna. A recomendação atual da ONLYOFFICE é configurar seu próprio segredo e usá-lo no conector. Consulte o guia de configuração de JWT da ONLYOFFICE .

Guia rápido: o que verificar primeiro

1. Confirme se o segredo compartilhado é realmente o mesmo.

A validação de JWT depende de um segredo compartilhado. O ONLYOFFICE Docs assina os tokens com esse segredo, e o destinatário verifica a assinatura usando o mesmo valor. Uma diferença de um único caractere, um espaço em branco no final, uma variável de ambiente antiga ou um segredo do Docker regenerado são suficientes para fazer com que um token aparentemente válido falhe na verificação.

No Nextcloud, o conector suporta essa jwt_secretconfiguração. O conector oficial também fornece uma occinterface de configuração, permitindo que você verifique o valor que o Nextcloud está realmente usando, em vez de depender de um arquivo de configuração que você acredita estar ativo. As configurações atuais do conector estão documentadas no arquivo README do conector ONLYOFFICE para Nextcloud .

sudo -u www-data php occ config:app:get onlyoffice jwt_secret
sudo -u www-data php occ config:app:get onlyoffice jwt_header

Não cole a chave secreta em tickets de suporte, capturas de tela, histórico do shell compartilhado com outros ou relatórios de problemas públicos. Compare-a localmente.

Para uma instalação nativa do ONLYOFFICE Docs no Linux, o arquivo de configuração compatível é:

/etc/onlyoffice/documentserver/local.json

Documentos do ONLYOFFICE separam as configurações de tokens para navegador, caixa de entrada e caixa de saída. Os valores secretos usados ​​para validação devem ser consistentes com a configuração do seu conector. Não edite o arquivo default.json; o ONLYOFFICE avisa explicitamente que os valores padrão podem ser sobrescritos na reinicialização ou atualização. Use local.jsonpara instalações de pacotes.

Se você executar o ONLYOFFICE Docs no Docker

Use variáveis ​​de ambiente do Docker em vez de editá-las manualmente local.jsondentro do contêiner. A ONLYOFFICE afirma que o Docker pode regenerar a configuração JWT durante a inicialização; sua imagem oficial suporta `java.jwt` JWT_ENABLED, JWT_SECRET`java.jwt`, JWT_HEADER`java.jwt` e ` java.jwt` JWT_IN_BODY. A documentação atual da imagem do Docker lista `java.jwt` Authorizationcomo o cabeçalho JWT padrão. Consulte o repositório oficial do Docker DocumentServer .

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=replace-with-a-long-random-secret
  - JWT_HEADER=Authorization

Após alterar as variáveis ​​de ambiente do Docker, recrie o contêiner para que o serviço em execução as receba. Editar um arquivo Compose sem recriar o contêiner não altera seu ambiente existente.

2. Certifique-se de que o cabeçalho JWT corresponda exatamente.

Um equívoco comum é achar que o nome do cabeçalho é apenas cosmético. Não é. O ONLYOFFICE Docs possui cabeçalhos de token de caixa de entrada e saída configuráveis, e o conector Nextcloud também possui uma jwt_headerconfiguração para isso. Ambos devem descrever o mesmo caminho de requisição.

A documentação atual da API do ONLYOFFICE lista Authorizationo Document Server como o padrão para solicitações JWT de entrada, e a documentação oficial de integração com o Nextcloud também o identifica Authorizationcomo o padrão normal do conector. Exemplos mais antigos e instalações existentes podem usar `<nome_do_servidor>` AuthorizationJWTou outro valor configurado explicitamente. Portanto, a regra de segurança não é "sempre usar uma string específica"; é garantir que a configuração ativa corresponda em ambas as extremidades .

O formato da requisição também é importante. A documentação da API da ONLYOFFICE mostra os tokens de cabeçalho enviados usando o esquema Bearer. Para detalhes sobre o protocolo subjacente, consulte a documentação de token no cabeçalho da ONLYOFFICE .

Se você usar um cabeçalho personalizado intencionalmente, configure o mesmo valor em ambos os produtos. Caso contrário, usar o valor padrão atual Authorizationreduz o número de componentes necessários.

3. Verifique se um proxy reverso está alterando o caminho do token.

Se as configurações do Nextcloud e do ONLYOFFICE coincidirem, mas o erro persistir, verifique o caminho entre eles. Um proxy reverso, gateway de autenticação, WAF ou controlador de entrada pode afetar os cabeçalhos de autorização. Isso depende da sua infraestrutura, portanto, não assuma que o proxy seja o culpado sem evidências.

Utilize esta sequência de testes práticos:

• Confirme se o URL público do servidor de documentos está acessível a partir do host do Nextcloud.
• Confirme se o URL do servidor de documentos interno, se configurado, é resolvido a partir do servidor ou contêiner Nextcloud.
• Confirme se o URL interno do Nextcloud/armazenamento é resolvido a partir do host ou contêiner do ONLYOFFICE Docs.
• Inspecione os registros de acesso/erro do proxy durante a execução da verificação do conector.
• Se o seu proxy tiver regras explícitas para isso Authorization, confirme se ele encaminha o cabeçalho em vez de substituí-lo ou removê-lo.

Não desative o JWT apenas para fazer o erro desaparecer. Isso remove o mecanismo de validação em vez de corrigi-lo. Da mesma forma, não desative a verificação TLS como uma solução para o JWT: a verificação de certificado e a validação da assinatura JWT são controles separados. Se você tiver um problema com o certificado, corrija a cadeia de certificados ou a configuração de confiança separadamente.

4. Use a verificação de integridade do próprio conector.

O conector oficial ONLYOFFICE inclui um comando de diagnóstico específico:

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

A documentação do conector afirma que essa verificação reporta uma conexão bem-sucedida ou a causa de um erro. Ela é mais útil do que testar apenas a página inicial do Servidor de Documentos, pois exercita a integração da perspectiva do Nextcloud.

Se a verificação indicar que o servidor de documentos está acessível, mas a validação do token falhar, retorne ao segredo e ao cabeçalho. Se não for possível acessar o servidor de forma alguma, resolva problemas de DNS, roteamento, firewall, TLS ou URLs internas antes de investir mais tempo no JWT.

5. Verifique o horário somente quando as evidências apontarem para isso.

Os JWTs podem incluir declarações relacionadas ao tempo, e o conector do Nextcloud expõe jwt_leewaye jwt_expirationconfigura isso. Isso não significa que você deva aumentar a margem de erro primeiro. Um relógio significativamente desajustado pode fazer com que tokens válidos falhem; aumentar a margem de erro pode mascarar o problema de infraestrutura.

Compare o horário UTC nos hosts ou contêineres do Nextcloud e do ONLYOFFICE:

date -u
timedatectl status

Certifique-se de que ambos os sistemas sincronizem o tempo de forma confiável. Somente após confirmar uma pequena diferença legítima entre os relógios, considere uma margem de tolerância estreita. As configurações JWT suportadas pelo conector estão listadas na referência oficial de configuração do conector .

Como funciona a validação JWT nesta integração

O ONLYOFFICE Docs usa JWT para proteger a inicialização do editor e as requisições entre servidores. Sua API separa os tokens do navegador dos tokens de requisição HTTP de entrada e saída. Para requisições de entrada, o token pode ser transportado em um cabeçalho ou, para requisições POST suportadas, no corpo da requisição. Para requisições GET, o ONLYOFFICE documenta o tratamento de tokens baseado em cabeçalho. Consulte a documentação oficial sobre assinatura de requisição .

Isso explica por que uma operação pode funcionar enquanto outra falha. Por exemplo, abrir o editor pode ser bem-sucedido, mas uma solicitação de retorno de chamada ou download posterior pode falhar se apenas uma das direções tiver as configurações de token corretas.

Conceitos errôneos comuns

“Se /healthcheck retornar verdadeiro, o JWT deve estar correto.”

Não. Um endpoint de saúde comprova que o serviço está respondendo; não comprova que o conector do Nextcloud e o Servidor de Documentos compartilham o mesmo segredo e cabeçalho JWT. Ação: execute occ onlyoffice:documentserver --checke inspecione as configurações efetivas do conector.

"Posso editar o arquivo local.json dentro de um contêiner Docker e pronto."

Isso é frágil para implantações do Docker. A ONLYOFFICE recomenda definir o JWT por meio de variáveis ​​de ambiente do Docker, pois a inicialização pode regenerar a configuração. Ação: defina JWT_ENABLED` JWT_SECRET<JWT_HOME>`, `<JWT_SERVER>` e, quando necessário, ` JWT_HEADER<JWT_SERVER>` na configuração do seu contêiner e recrie o contêiner.

“O cabeçalho AuthorizationJWT é sempre obrigatório.”

Não. A configuração oficial atual do Document Server lista Authorizationo cabeçalho padrão, embora implantações existentes e exemplos mais antigos possam usar outro cabeçalho configurado explicitamente. Ação: leia ambas as configurações ativas e torne-as idênticas.

“Desativar o JWT é a solução mais rápida.”

Isso pode corrigir o erro de validação imediato, mas também remove um controle de segurança e pode mascarar a incompatibilidade subjacente. Ação: corrija o segredo/cabeçalho compartilhado, a menos que você tenha um motivo deliberado e documentado para operar sem JWT.

Lista de verificação de validação final

• O mesmo segredo JWT está configurado no Nextcloud e no ONLYOFFICE Docs.
• O nome do cabeçalho JWT corresponde em ambas as extremidades.
• As implementações do Docker usam variáveis ​​de ambiente persistentes, e não edições pontuais dentro do contêiner.
• Os URLs dos servidores públicos e internos são acessíveis na direção em que são utilizados.
• Nenhuma regra de proxy remove ou reescreve o cabeçalho JWT inesperadamente.
• Os sistemas Nextcloud e ONLYOFFICE têm relógios sincronizados.
• occ onlyoffice:documentserver --checkconsegue.
• Um documento real abre, edita, salva automaticamente, fecha e reabre com as alterações salvas.

Quando o erro de token persistir

Se os segredos e cabeçalhos coincidirem, os relógios estiverem sincronizados e a verificação do conector for bem-sucedida, mas uma operação específica ainda reportar um token inválido, capture a direção exata da solicitação com falha e os logs correspondentes antes de alterar mais configurações. O ONLYOFFICE distingue a validação do navegador, da caixa de entrada e da caixa de saída; portanto, a próxima questão é se a falha ocorre durante a inicialização do editor, um comando enviado ao Servidor de Documentos ou um retorno de chamada/download enviado de volta ao Nextcloud.

Utilize os logs do Servidor de Documentos juntamente com os logs do Nextcloud e do proxy para o mesmo registro de data e hora. Evite publicar JWTs ou segredos completos publicamente. Se precisar comparar a estrutura do token, oculte a assinatura e as declarações confidenciais. O comportamento de referência para assinatura e validação é descrito na documentação de assinatura do ONLYOFFICE .