Resolvendo o erro "Token inválido" do ONLYOFFICE no Nextcloud.

Se o Nextcloud reportar a mensagem “Token inválido” ao se conectar ao ONLYOFFICE Docs, certifique-se de que o segredo JWT do conector corresponda ao segredo que o Document Server está utilizando. No ONLYOFFICE Docs 7.2 e versões posteriores, a validação JWT está ativada por padrão e um segredo é gerado automaticamente; alterar apenas a configuração do Nextcloud ou editar o arquivo de configuração gerado por um contêiner Docker pode causar a dessincronização entre os dois sistemas.

Mantenha o JWT ativado. Primeiro, identifique o segredo ativo e o tipo de implantação, atualize a configuração correta e, em seguida, execute a verificação de conexão do conector. A verificação deve indicar uma conexão bem-sucedida; a simples abertura do editor do navegador não comprova que os downloads de documentos e os retornos de chamada funcionam.

O que o erro indica?

O JWT (JSON Web Token) é um token assinado usado para verificar se uma solicitação entre o Nextcloud e o ONLYOFFICE Docs é confiável. O conector assina as solicitações com seu segredo configurado, enquanto o Servidor de Documentos as valida usando seu próprio segredo configurado. Se os segredos de assinatura forem diferentes, a assinatura do token não poderá ser validada e a solicitação será rejeitada.

As causas mais comuns são um segredo copiado de uma instalação antiga, um segredo gerado automaticamente que nunca foi inserido no Nextcloud, uma variável de ambiente do Docker alterada que não foi aplicada ao recriar o contêiner ou valores de segredo inconsistentes na configuração do Servidor de Documentos. Um cabeçalho JWT personalizado também pode causar uma incompatibilidade se o conector e o Servidor de Documentos não usarem o mesmo nome de cabeçalho.

Este artigo aborda a incompatibilidade do JWT. Se, em vez disso, o erro indicar que o servidor não pode ser acessado, que o certificado é inválido ou que um documento não pode ser baixado, investigue separadamente os endereços do servidor, o certificado TLS e o caminho de rede entre o Nextcloud e o servidor de documentos. Uma correção do JWT não resolverá esses problemas.

1. Encontre a chave secreta ativa do Servidor de Documentos.

Utilize a configuração pertencente ao Servidor de Documentos em execução. Não assuma que um segredo memorizado de um contêiner ou servidor anterior ainda esteja ativo.

• Linux: inspecionar /etc/onlyoffice/documentserver/local.json.
• Windows: inspecionar %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json.
• Docker: leia o segredo do contêiner em execução. A imagem oficial também suporta a leitura do segredo da sessão com este comando:

sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

Substitua <containerID>pelo nome ou ID real do contêiner. Trate o valor retornado como uma credencial: não o copie e cole em fóruns de suporte, capturas de tela ou registros públicos.

Em local.json, compare os valores em services.CoAuthoring.secret.inbox.string, services.CoAuthoring.secret.outbox.string, e services.CoAuthoring.secret.session.string. Eles devem ser idênticos para esta configuração padrão. Confirme também se a validação de token está habilitada para o navegador, a caixa de entrada de solicitações e a caixa de saída de solicitações. Versões da documentação anteriores à 7.2 exigem que a validação de token seja habilitada explicitamente; versões posteriores a habilitam por padrão.

2. Atualize o conector ONLYOFFICE do Nextcloud.

1. Faça login como administrador do Nextcloud e abra Configurações > Administração > ONLYOFFICE .
2. Nas configurações do servidor, insira a chave secreta exata encontrada no Servidor de Documentos em execução no campo Chave secreta . Evite espaços no início ou no final e não adicione aspas, a menos que façam parte da própria chave secreta.
3. Verifique a configuração do cabeçalho JWT se sua implementação usa um cabeçalho personalizado. A jwt_headerconfiguração do conector e o cabeçalho de token configurado no Servidor de Documentos devem coincidir. Se você não personalizou o cabeçalho intencionalmente, não o altere como parte deste reparo.
4. Salve as configurações. Mantenha o JWT ativado em ambas as extremidades.

A configuração do conector documentada também pode ser alterada com occo comando do Nextcloud a partir do diretório de instalação do Nextcloud:

sudo -u www-data php occ config:app:set onlyoffice jwt_secret --value='YOUR_SECRET'

Substitua YOUR_SECRETpelo valor real. O uso de aspas no shell ajuda a preservar a pontuação, mas segredos que contêm uma única aspa exigem um método mais seguro do que inseri-los diretamente na linha de comando. Os argumentos da linha de comando também podem ser visíveis para inspeção de processos privilegiados ou para o histórico do shell. Sempre que possível, prefira a interface administrativa e verifique o valor armazenado sem expô-lo.

3. Aplique a alteração da maneira correta para a sua instalação.

Docker ou Docker Compose

Para implantações Docker, configure o JWT por meio do ambiente do contêiner, em vez de editar manualmente o arquivo gerado automaticamente local.json. Defina o mesmo segredo na definição do serviço do Servidor de Documentos:

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

Após alterar o arquivo Compose, recrie o contêiner do Document Server para que o ambiente entre em vigor. Por exemplo, a partir do diretório que contém o arquivo Compose:

docker compose up -d --force-recreate <documentserver-service>

Substitua o nome do serviço pelo nome do seu próprio arquivo Compose. Uma reinicialização simples não aplica uma alteração no valor do ambiente a um contêiner existente. Se você usar o comando `compose restart` docker run, recrie o contêiner com os valores atualizados de `environment` JWT_ENABLEDe JWT_SECRET`ports`, preservando as portas, volumes e outras opções necessárias existentes. Não exclua um contêiner de produção até confirmar essas configurações e as montagens de dados persistentes.

Ao iniciar o contêiner, releia seu segredo ativo com o comando acima e certifique-se de que o valor ainda corresponda ao do Nextcloud. Evite colocar um segredo de produção em um arquivo Compose ou repositório de código-fonte compartilhado publicamente.

Pacote Linux ou instalação do Windows

Se você definir intencionalmente um segredo personalizado em local.json, certifique-se de que os três campos do segredo correspondam e que os valores de validação de token necessários estejam habilitados. Aplique a alteração reiniciando os serviços relevantes do Document Server. As instruções atuais do ONLYOFFICE listam ds-converter, ds-docservicee ds-metricsno Linux; instalações gerenciadas por um supervisor de serviço diferente podem exigir o método de reinicialização apropriado para essa configuração. No Windows, reinicie os serviços do ONLYOFFICE após salvar a configuração.

Uma incompatibilidade que persiste após a reinicialização geralmente significa que uma configuração gerada ou um ambiente de implantação está sobrescrevendo o arquivo editado. Para o Docker, mova a correção para variáveis ​​de ambiente e recrie o contêiner. Para implantações empacotadas, inspecione a configuração ativa e a configuração de inicialização do serviço antes de alterar outras configurações.

Verifique o reparo

1. No diretório de instalação do Nextcloud, execute a verificação oficial do conector:

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

Use a conta do servidor web apropriada para sua instalação, caso ainda não esteja configurada www-data. O comando deve reportar uma conexão bem-sucedida. Se ainda assim reportar um token inválido, confirme novamente se o segredo ativo do Servidor de Documentos em execução corresponde exatamente ao do Nextcloud e se qualquer cabeçalho JWT personalizado está de acordo.

2. Abra um pequeno documento de teste do Nextcloud com o ONLYOFFICE. Confirme se o editor carrega, faça uma pequena alteração, salve, feche o editor e abra o arquivo novamente para confirmar se a alteração foi aplicada.
3. Se a verificação agora reportar um erro de rede ou de certificado, pare de alterar os valores do JWT. Verifique se o Nextcloud consegue acessar o endereço do Servidor de Documentos e se o Servidor de Documentos consegue acessar o endereço de retorno de chamada do Nextcloud. Use um certificado TLS confiável sempre que possível; desativar a verificação de certificado é uma solução paliativa insegura e não corrige a validação do token.

Essas verificações comprovam que a conexão configurada e um caminho de salvamento básico funcionam. Elas não garantem que todas as rotas de proxy reverso, configurações de armazenamento externo ou topologias com vários servidores estejam corretas; teste esses caminhos separadamente se sua implementação os utilizar.

Referências oficiais

• ONLYOFFICE: Integração com Nextcloud e configuração de JWT
• ONLYOFFICE: Configurar JWT para servidor de documentos
• Conector ONLYOFFICE Nextcloud: opções de configuração e comandos occ

Os detalhes de configuração foram verificados em relação à documentação oficial do ONLYOFFICE e ao repositório de conectores em 9 de outubro de 2026. Os rótulos da interface do usuário e o gerenciamento de serviços podem variar de acordo com o conector, o sistema operacional e o método de implantação.