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.

커넥터에 "비밀 키", "JWT 비밀" 또는 이와 유사한 레이블이 있는 필드가 있는 경우, 해당 필드에 별도의 비밀 키를 생성하지 마십시오. 기존 비밀 키 값을 그대로 복사하십시오.

6. 사용자 지정 통합을 위해서는 서버에서 전체 편집기 구성 파일에 서명하십시오.

사용자 지정 애플리케이션의 경우 먼저 편집기 구성을 빌드하고 백엔드에서 해당 구성에 서명한 다음 생성된 JWT를 최상위 token속성에 할당합니다.

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"
});

ONLYOFFICE의 브라우저 서명 관련 문서에 따르면 파일을 열기 위한 토큰 페이로드는 편집기 구성과 동일한 구조를 가져야 합니다. 버전 7.1부터 유효성 검사에 사용되는 매개변수 집합이 이 작업에 대해 엄격하게 규제되므로, 오래되었거나 불완전한 구조에 서명하는 것은 실패의 일반적인 원인입니다. 브라우저 토큰 서명을 참조하십시오 .

결과적으로 전달되는 구성에는 DocsAPI.DocEditor토큰이 포함됩니다.

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

공식 API 참조에서는 config.tokenONLYOFFICE Docs가 편집기 구성을 검증하는 데 사용하는 암호화된 서명을 다음과 같이 정의합니다.

7. 헤더 토큰과 본문 토큰의 차이점을 이해하세요

ONLYOFFICE에서 JWT는 브라우저 편집기 설정뿐만 아니라 명령, 변환 및 콜백 트래픽과 같은 서비스 간 요청에도 사용됩니다.

ONLYOFFICE는 요청 토큰을 본문과 헤더 모두에 지원합니다. 보안 FAQ에 따르면 헤더는 서버별 길이 제한에 걸릴 수 있으므로 수신 요청에는 본문 토큰을 사용하는 것이 좋습니다. 문서 7.1부터는 수신 본문 토큰이 있는 경우 우선적으로 사용되며, 그렇지 않은 경우 헤더 토큰이 사용됩니다. 발신 측에서는 본문 토큰과 헤더 토큰을 모두 전송할 수 있습니다. 자세한 내용은 ONLYOFFICE 요청 토큰 문서를 참조하십시오 .

Docker 변수의 JWT_IN_BODY기본값은 이므로 false, 단순히 존재한다는 이유만으로 활성화하지 마십시오. 통합 기능이 본문 토큰을 일관되게 전송하고 검증하도록 설계된 경우에만 이 변수를 변경하십시오.

8. 실제 편집자 요청으로 테스트해 보세요.

유용한 검증 순서는 다음과 같습니다.

1. 실제 통합을 통해 문서를 엽니다.
2. 토큰 오류 없이 에디터가 제대로 로드되는지 확인하십시오.
3. 약간의 수정을 해보세요.
4. 편집기를 닫거나 일반 저장 경로를 실행하세요.
5. 스토리지 애플리케이션이 콜백을 수신하고 수락하는지 확인합니다.

문서 서버 환영 페이지가 성공적으로 표시된다고 해서 두 애플리케이션 간에 JWT가 올바르게 구성되었다는 것을 의미하지는 않습니다 . JWT 오류는 통합 과정에서 편집기 구성, 명령, 변환 요청 또는 콜백을 전송할 때만 나타나는 경우가 많습니다.

공식 보안 개요에서는 예상되는 동작을 설명합니다. ONLYOFFICE는 토큰을 검증하고 서명된 페이로드 값을 사용합니다. 검증이 필요한 시점에 토큰이 없거나 유효하지 않으면 요청이 거부됩니다. 자세한 내용은 ONLYOFFICE 문서의 보안 개요를 참조하십시오 .

9. 인증 실패 시 JWT 상태 및 로그를 확인하십시오.

현재 Docker 시작 코드는 관리자에게 JWT 상태 도우미를 안내합니다. 올바른 컨테이너 이름을 사용하여 다음 명령을 실행하세요.

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

로그를 확인할 수도 있습니다.

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

비밀 키를 변경한 직후 통합이 실패하는 경우 다음 항목들을 순서대로 비교하십시오.

• JWT_ENABLED재생성된 컨테이너에서 실제로 활성화되어 있습니까 ?
• 통합 과정에서 대소문자와 구두점을 포함하여 완전히 동일한 비밀 키를 사용합니까?
• 커넥터가 동일한 JWT 헤더 이름을 사용합니까?
• 사용자 지정 편집기의 경우, 브라우저로 전송하는 구성 객체와 동일한 객체에 서명을 하고 있습니까?
• 콜백 및 명령 요청도 요구 사항에 따라 서명 및 유효성 검사를 거치나요?
• 셸이나 Compose 파일에 저장된 비밀 키가 환경 변수 확장에 의해 잘리거나, 해석되거나, 대체되었습니까?

일반적인 실패 패턴

"유효하지 않은 토큰" 또는 "유효하지 않은 서명"

가장 가능성이 높은 원인은 비밀 키 불일치 또는 유효성 검사를 수행하는 요청과 다른 페이로드로 서명된 토큰입니다. 관련 설정을 변경한 후에는 토큰을 다시 생성하십시오. 문서에 있는 예제 토큰을 재사용하지 마십시오. 해당 예제 토큰은 데모용 비밀 키로 서명되었으며 서버에서 유효하지 않습니다.

Docker가 재시작될 때까지는 작동합니다.

이는 일반적으로 배포가 자동으로 생성된 JWT 비밀 키에 의존하고 있음을 의미합니다. ONLYOFFICE는 재부팅 또는 컨테이너 재구축 후 임의의 비밀 키가 다시 생성될 수 있음을 명시적으로 경고합니다. 비밀 키를 JWT_SECRET직접 설정하고 통합에 동일한 값을 입력하십시오.

Nextcloud에서 연결 또는 토큰 오류가 표시됩니다.

먼저 양쪽의 비밀 키와 헤더를 확인하세요. ONLYOFFICE의 Nextcloud 문서에서는 커넥터의 헤더가 jwt_headerDocument Server에 구성된 헤더와 일치해야 한다고 명시하고 있습니다. 현재 기본값은 다음과 같습니다 Authorization.

서명된 대용량 요청은 HTTP 오류를 반환합니다.

프록시 또는 웹 서버의 헤더 크기 제한을 초과하는 헤더에 JWT가 전송되는지 조사하십시오. ONLYOFFICE의 보안 FAQ에 따르면 이것이 해당 POST 요청에 본문 토큰을 사용하는 것이 더 바람직한 이유 중 하나입니다.

JWT 비밀 키를 안전하게 회전시키기

JWT 비밀 키 교체는 반드시 조정되어야 합니다. 커넥터가 이전 비밀 키로 계속 서명하는 동안 문서 서버만 변경하는 것은 아무런 이점이 없습니다.

간단한 단일 인스턴스 배포의 경우:

1. 새로운 비밀 키를 생성하여 안전하게 보관하십시오.
2. 활성 편집 사용자에게 영향을 줄 수 있는 경우 짧은 점검 시간을 예약하세요.
3. 통합의 비밀 키와 문서 서버의 비밀 키를 JWT_SECRET하나의 통합된 변경 사항으로 업데이트하십시오.
4. 문서 서버 컨테이너를 다시 생성합니다.
5. 테스트 문서를 열고, 편집하고, 저장합니다.
6. 서비스를 정상적으로 사용하기 전에 콜백이 제대로 작동하는지 확인하십시오.

로드 밸런서 뒤에 여러 Document Server 인스턴스가 있는 경우, 동일한 통합 서비스를 제공하는 모든 인스턴스는 변경 시 호환 가능한 JWT 구성을 갖춰야 합니다. 즉흥적으로 노드를 하나씩 교체하는 대신, 배포 계획을 수립하십시오.

생산 체크리스트

• 영구 비밀 키: 명시적으로 설정하십시오 JWT_SECRET. 임의로 생성된 값에 의존하지 마십시오.
• 어디에서나 동일한 비밀이 적용됩니다. 문서 서버와 통합 시스템은 동일한 값을 공유해야 합니다.
• 백엔드 서명: 프런트엔드/브라우저 코드에 비밀 키를 절대 노출하지 마십시오.
• HS256: ONLYOFFICE의 공식 코드 샘플에 나와 있는 HMAC-SHA256 방식을 사용하십시오.
• 헤더 일치: 커넥터가 명명된 헤더를 통해 JWT를 전송하는 경우 해당 이름은 Document Server와 일치해야 합니다.
• 컨테이너 재구축: Docker 환경이 변경되면 컨테이너를 재구축해야 합니다.
• 실제 통합 테스트: 열기, 편집, 저장 및 콜백 동작 검증.
• 비밀 저장소: 비밀 정보는 공개 저장소나 로그에 노출되지 않도록 합니다.
• 제어된 회전: 양쪽을 동시에 업데이트하고 유지 보수를 종료하기 전에 확인합니다.

결론적으로

Docker 기반 ONLYOFFICE 설치의 경우, 안정적인 구성은 간단합니다. 강력한 비밀 키를 생성하고, 컨테이너 환경 변수를 통해 설정한 다음 JWT_ENABLED=true, JWT_SECRET컨테이너를 다시 생성하고 커넥터 또는 백엔드에 동일한 비밀 키를 구성하면 됩니다. 사용자 지정 통합은 브라우저 코드가 아닌 서버에서 HS256으로 편집기 구성 및 서비스 요청에 서명해야 합니다.

JWT가 재시작 후 갑자기 작동하지 않는 경우, 비밀 키가 영구적으로 저장되었는지 확인하십시오. 구성 변경 직후에 오류가 발생하는 경우, 다른 부분을 확인하기 전에 비밀 키, 헤더 및 서명된 페이로드를 비교하십시오. 이 세 가지 검사를 통해 인증 수준을 낮추지 않고 대부분의 JWT 설정 오류를 해결할 수 있습니다.