How to Configure ONLYOFFICE JWT Secret Key Authentication

ONLYOFFICE JWT authentication works only when the Document Server and the integrating application use the same secret key. On current Docker deployments, JWT validation is enabled by default. For a stable integration, set your own persistent JWT_SECRET instead of relying on the container's automatically generated value, then configure the same secret in Nextcloud, your custom document manager, or whichever connector talks to ONLYOFFICE Docs.

This practical reference focuses on the configuration you are most likely to need: Docker and Docker Compose, custom integrations that sign editor configuration, header/body behavior, verification, rotation, and common errors. It is based on current ONLYOFFICE documentation checked in October 2026.

Quick reference

Starting with ONLYOFFICE Docs 7.2, Docker deployments enable JWT by default and generate a random secret when you do not supply one. The official Docker documentation warns that an automatically generated secret can change after a reboot or container recreation and break integrations. Set an explicit secret for any real deployment. See Configuring JWT for ONLYOFFICE Docs and the official Docker installation guide.

1. Identify the ONLYOFFICE container and deployment method

For a Docker host, start with:

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
docker images | grep onlyoffice

Determine whether the instance was launched with docker run, Docker Compose, a control panel, or another orchestration layer. You need to change the source configuration that creates the container. Editing a generated file inside the container is not the persistent solution.

For Docker specifically, ONLYOFFICE tells administrators to use environment variables rather than manually editing /etc/onlyoffice/documentserver/local.json. If you edit JWT values directly in that file, the Docker startup process can restore or regenerate them when the container restarts.

2. Generate a strong secret and store it securely

A convenient shell command is:

openssl rand -hex 32

This produces 32 random bytes represented as 64 hexadecimal characters. ONLYOFFICE does not require this exact format; the important requirement is that both sides share the same secret and that it is difficult to guess.

Treat JWT_SECRET like a password or API credential:

• Do not commit it to a public Git repository.
• Do not put it in frontend JavaScript shipped to browsers.
• Restrict access to the Compose environment file or secret store that contains it.
• Use a different secret for separate environments such as production and staging.

ONLYOFFICE's signature documentation explicitly warns that token signing must happen on the server because any browser-side code that contains the secret exposes it to users. The official examples use HMAC-SHA256 (HS256). See ONLYOFFICE JWT signature documentation.

3. Configure JWT in Docker Compose

A minimal Compose service can include:

services:
  documentserver:
    image: onlyoffice/documentserver:latest
    restart: unless-stopped
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: "${ONLYOFFICE_JWT_SECRET}"
      JWT_HEADER: "Authorization"
      JWT_IN_BODY: "false"
    ports:
      - "8080:80"

Keep the actual secret outside the Compose file when practical. For example, put it in a permission-restricted .env file:

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

Then ensure that file is excluded from version control and readable only by the administrators or service account that needs it.

The official ONLYOFFICE Docker-DocumentServer repository documents JWT_ENABLED, JWT_SECRET, JWT_HEADER, and JWT_IN_BODY. Current Docker startup code defaults JWT validation to enabled, uses Authorization as the default header, and generates a random secret when an explicit one is not supplied.

4. Recreate the container so the new environment is applied

For Compose:

docker compose up -d --force-recreate
docker compose ps

For a container originally created with docker run, the official JWT guide instructs administrators to stop and remove the old container, then create a new one with the JWT environment variables. Do not remove persistent volumes or bind-mounted data while doing this.

You can also inspect the running container's environment without printing the secret itself:

docker inspect onlyoffice-documentserver \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep '^JWT_' \
  | sed 's/^JWT_SECRET=.*/JWT_SECRET=[REDACTED]/'

If the container name differs, replace onlyoffice-documentserver accordingly.

5. Configure the same secret in the integration

This is the part most often missed. Enabling JWT on ONLYOFFICE Docs without configuring the document-management side causes rejected editor requests. The connector or custom application must sign requests with exactly the same secret.

Nextcloud example

In the ONLYOFFICE settings for Nextcloud, enter the same secret key used by the Document Server. The header name must also match. ONLYOFFICE's current Nextcloud integration documentation lists jwt_secret and jwt_header as connector settings, with Authorization as the normal default header. See the official Nextcloud connector documentation.

Se o seu conector tiver um campo com a etiqueta “Chave secreta”, “Segredo JWT” ou similar, não gere um segundo segredo independente nesse campo. Copie o mesmo valor de segredo.

6. Para uma integração personalizada, assine a configuração completa do editor no servidor.

Para uma aplicação personalizada, primeiro crie a configuração do editor, assine essa configuração no backend e, em seguida, atribua o JWT resultante à tokenpropriedade de nível superior.

Exemplo em Node.js:

import jwt from "jsonwebtoken";

const config = {
  documentType: "word",
  document: {
    fileType: "docx",
    key: "document-2026-001",
    title: "Project Plan.docx",
    url: "https://files.example.com/project-plan.docx"
  },
  editorConfig: {
    callbackUrl: "https://app.example.com/onlyoffice/callback"
  }
};

config.token = jwt.sign(config, process.env.ONLYOFFICE_JWT_SECRET, {
  algorithm: "HS256"
});

A documentação de assinatura de navegador do ONLYOFFICE afirma que o payload do token para abrir um arquivo deve ter a mesma estrutura que a configuração do editor. Desde a versão 7.1, o conjunto de parâmetros envolvidos na validação é estritamente regulamentado para essa operação, portanto, assinar uma estrutura desatualizada ou parcial é uma causa comum de falhas. Consulte Assinatura de token do navegador .

A configuração resultante passada para DocsAPI.DocEditorcontém o token:

new DocsAPI.DocEditor("placeholder", config);

A referência oficial da API define config.tokencomo a assinatura criptografada usada pelo ONLYOFFICE Docs para validar a configuração do editor.

7. Compreenda a diferença entre tokens de cabeçalho e tokens de corpo.

O JWT no ONLYOFFICE abrange mais do que a configuração do editor do navegador. Ele também é usado para solicitações de serviço para serviço, como comandos, conversões e tráfego de retorno de chamada.

O ONLYOFFICE suporta tokens de requisição tanto no corpo quanto no cabeçalho. Seu FAQ de segurança observa que os cabeçalhos podem atingir limites de comprimento específicos do servidor e, portanto, recomenda o uso de tokens no corpo para requisições de entrada aplicáveis. A partir da documentação 7.1, um token de corpo de requisição tem precedência quando presente; caso contrário, o token de cabeçalho é utilizado. O lado de saída pode enviar ambos. Consulte a documentação de tokens de requisição do ONLYOFFICE .

A variável do Docker JWT_IN_BODYtem como valor padrão false, portanto, não a habilite apenas porque ela existe. Altere-a somente quando sua integração for projetada para enviar e validar tokens no corpo da requisição de forma consistente.

8. Teste com uma solicitação real do editor

Uma sequência de validação útil é:

1. Abra um documento através da sua integração real.
2. Verifique se o editor carrega sem erros de token.
3. Faça uma pequena alteração.
4. Feche o editor ou inicie o processo normal de salvamento.
5. Verifique se o aplicativo de armazenamento recebe e aceita o retorno de chamada.

Uma página de boas-vindas do Document Server exibida corretamente não comprova que o JWT está configurado corretamente entre duas aplicações. Erros de JWT geralmente ocorrem somente quando a integração envia a configuração do editor, o comando, a solicitação de conversão ou o retorno de chamada.

A visão geral de segurança oficial explica o comportamento esperado: o ONLYOFFICE valida um token e usa os valores da carga útil assinada; se o token estiver ausente ou inválido quando a validação for necessária, a solicitação será rejeitada. Consulte a visão geral de segurança da documentação do ONLYOFFICE .

9. Verifique o status e os registros do JWT quando a autenticação falhar.

O código de inicialização atual do Docker direciona os administradores para o auxiliar de status JWT. Com o nome de contêiner correto, execute:

docker exec onlyoffice-documentserver \
  sudo documentserver-jwt-status.sh

Você também pode inspecionar os registros:

docker logs --tail 200 onlyoffice-documentserver
docker exec onlyoffice-documentserver \
  find /var/log/onlyoffice/documentserver -type f -maxdepth 3 -print

Se uma integração falhar imediatamente após a alteração da chave secreta, compare estes itens nesta ordem:

• Está JWT_ENABLEDrealmente habilitado no contêiner recriado?
• A integração utiliza exatamente o mesmo segredo, incluindo maiúsculas e pontuação?
• O conector usa o mesmo nome de cabeçalho JWT?
• Para um editor personalizado, você está assinando o mesmo objeto de configuração que envia para o navegador?
• Os retornos de chamada e as solicitações de comando também são assinados e validados conforme exigido?
• Algum segredo armazenado em um arquivo shell ou Compose foi truncado, interpretado ou substituído pela expansão de variáveis ​​de ambiente?

Padrões de falha comuns

“Token inválido” ou “Assinatura inválida”

A causa mais provável é uma incompatibilidade de segredo ou um token assinado com uma carga útil diferente da solicitação que está sendo validada. Regenere o token após qualquer alteração relevante na configuração. Não reutilize um token de exemplo da documentação; esses exemplos são assinados com segredos de demonstração e não são válidos para o seu servidor.

Funciona até o Docker reiniciar.

Isso geralmente significa que a implantação estava dependendo do segredo JWT gerado automaticamente. O ONLYOFFICE avisa explicitamente que um segredo aleatório pode ser regenerado após a reinicialização ou recriação do contêiner. Defina JWT_SECRETvocê mesmo e insira o mesmo valor na integração.

O Nextcloud exibe um erro de conexão ou de token.

Verifique primeiro o segredo e o cabeçalho em ambos os lados. A documentação do Nextcloud da ONLYOFFICE exige que o cabeçalho do conector jwt_headercorresponda ao cabeçalho configurado no Servidor de Documentos. O padrão atual normal é Authorization.

Uma solicitação assinada de grande porte retorna um erro HTTP.

Investigue se o JWT está sendo enviado em um cabeçalho que excede o limite de tamanho de cabeçalho do proxy ou do servidor web. As perguntas frequentes de segurança da ONLYOFFICE explicam que esse é um dos motivos pelos quais os tokens no corpo da requisição são preferidos para solicitações POST aplicáveis.

Girando o segredo JWT com segurança

É necessário coordenar a rotação do segredo JWT. Não há vantagem em alterar apenas o servidor de documentos enquanto o conector continua a assinar com o segredo antigo.

Para uma implementação simples de instância única:

1. Gere o novo segredo e armazene-o em local seguro.
2. Agende uma breve janela de manutenção caso os editores ativos possam ser afetados.
3. Atualize o segredo da integração e o do servidor de documentos JWT_SECRETcomo uma alteração coordenada.
4. Recrie o contêiner do Servidor de Documentos.
5. Abra, edite e salve um documento de teste.
6. Confirme se as funções de retorno de chamada estão funcionando antes de retornar o serviço ao uso normal.

Para várias instâncias do Document Server atrás de um balanceador de carga, todas as instâncias que servem a mesma integração precisam de uma configuração JWT compatível durante a alteração. Planeje a implementação em vez de rotacionar um nó de forma improvisada.

Lista de verificação de produção

• Segredo persistente: definido JWT_SECRETexplicitamente; não dependa do valor gerado aleatoriamente.
• O segredo é o mesmo em todos os lugares: o servidor de documentos e a integração devem compartilhar o mesmo valor.
• Assinatura no backend: nunca exponha o segredo no código do frontend/navegador.
• HS256: utilize a abordagem HMAC-SHA256 mostrada nos exemplos de código oficiais da ONLYOFFICE.
• Acordo de cabeçalho: se um conector enviar JWT por meio de um cabeçalho nomeado, esse nome deverá corresponder ao Servidor de Documentos.
• Recriação do contêiner: alterações no ambiente Docker exigem a recriação do contêiner.
• Teste de integração real: abrir, editar, salvar e verificar o comportamento de retorno de chamada.
• Armazenamento secreto: mantenha o segredo fora de repositórios e registros públicos.
• Rotação controlada: atualize ambos os lados simultaneamente e verifique antes de finalizar a manutenção.

Resumindo

Para uma instalação do ONLYOFFICE baseada em Docker, a configuração robusta é simples: gere um segredo forte, defina- JWT_ENABLED=trueo JWT_SECRETpor meio de variáveis ​​de ambiente do contêiner, recrie o contêiner e configure o mesmo segredo no seu conector ou backend. Integrações personalizadas devem assinar a configuração do editor e as solicitações de serviço no servidor com HS256, nunca no código do navegador.

Se o JWT parar de funcionar repentinamente após uma reinicialização, verifique se o segredo foi tornado persistente. Se a falha ocorrer imediatamente após uma alteração de configuração, compare o segredo, o cabeçalho e a carga útil assinada antes de investigar outras causas. Essas três verificações resolvem a maioria dos erros de configuração do JWT sem comprometer a autenticação.