서버와 커넥터 간에 ONLYOFFICE JWT 비밀 키를 설정하는 방법

강력한 JWT 비밀 키를 일관되게 사용하세요. ONLYOFFICE Docs에서 비밀 키를 구성하고, 연결된 플랫폼의 ONLYOFFICE 설정에도 동일한 값을 복사하여 붙여넣고, JWT 유효성 검사를 활성화 상태로 유지하세요. Docs 7.2 이상 버전에서는 JWT가 기본적으로 활성화되어 있으며 비밀 키가 자동으로 생성됩니다. 비밀 키를 변경하면 모든 통합 설정을 업데이트해야 합니다. 서버 측에서 사용하는 정확한 방법은 Docs가 Linux 패키지로 실행되는지 Docker 컨테이너로 실행되는지에 따라 다릅니다.

무엇이 일치해야 합니까?

JWT(JSON Web Token)는 ONLYOFFICE Docs에서 서명된 요청을 확인할 수 있도록 합니다. 문서 플랫폼과 Docs는 동일한 비밀 키와 호환되는 헤더 설정을 사용해야 합니다. 서버는 브라우저 구성과 수신 및 발신 서비스 요청에 대해 별도의 토큰 설정을 사용하며, 공유 비밀 키 값은 이러한 정보 교환을 보호합니다. 비밀 키를 공개 웹 페이지, 클라이언트 측 JavaScript 번들, 지원 티켓 또는 공개적으로 읽을 수 있는 소스 저장소에 저장하지 마십시오.

편집하기 전에 배포 유형을 확인하고 커넥터에서 사용하는 Docs URL을 기록해 두세요. 암호 관리자 또는 암호학적으로 안전한 생성기를 사용하여 길고 예측 불가능한 비밀 키를 생성하세요. 이 키를 자격 증명처럼 취급하고 접근이 제한된 구성 저장소에 저장하세요.

Linux 설치를 구성합니다.

패키지 기반 Linux 설치의 경우, 파일을 편집하세요 /etc/onlyoffice/documentserver/local.json. 기존 설정을 유지하려면 전체 파일을 교체하는 대신 다음 키를 기존 JSON 파일에 병합하세요. 예시는 토큰 유효성 검사 구조와 공식 구성 가이드에 설명된 세 개의 일치하는 비밀 위치를 보여줍니다.

{
  "services": {
    "CoAuthoring": {
      "token": {
        "enable": {
          "request": {
            "inbox": true,
            "outbox": true
          },
          "browser": true
        }
      },
      "secret": {
        "inbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "outbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "session": { "string": "REPLACE_WITH_YOUR_SECRET" }
      }
    }
  }
}

모든 자리 표시자를 정확히 동일한 비밀 값으로 바꾸십시오. 샘플 자리 표시자 자체는 붙여넣지 마십시오. browser, inbox, 및 outbox스위치는 별개이며, 하나만 활성화한다고 해서 모든 요청 유효성 검사가 활성화되는 것은 아닙니다. 문서 7.2 이상 버전에서는 JWT가 기본적으로 활성화되어 있지만, 이러한 설정을 명시적으로 확인하면 기존 구성을 감사하거나 노드 간 동작을 일관되게 유지하는 데 도움이 됩니다. 7.2 이전 버전의 경우 공식 가이드에서는 세 가지 스위치를 모두 활성화하도록 권장합니다.

재시작하기 전에 JSON 구문의 유효성을 검사하십시오. 그런 다음 변경 사항이 적용되도록 문서 서버 서비스를 다시 시작하십시오.

sudo systemctl restart ds-converter ds-docservice ds-metrics

시스템 서비스를 관리할 수 있는 권한이 있는 계정으로 명령을 실행하십시오. Windows에서는 구성 파일이 입니다 %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json. Linux 명령 대신 공식 가이드의 Windows 재시작 지침을 사용하십시오.

생성된 설정 파일을 수정하지 않고 Docker를 구성합니다.

공식 문서 서버 Docker 이미지의 경우 컨테이너 환경 변수를 통해 JWT를 설정하세요. 공식 가이드에서는 생성된 환경 변수를 수동으로 변경하면 local.json컨테이너가 재시작될 때 변경 사항이 초기화될 수 있다고 경고합니다. 컨테이너 생성 명령 또는 Compose 서비스에서 환경 변수를 설정한 JWT_ENABLED=true다음 JWT_SECRET컨테이너를 다시 생성하여 환경 변수가 적용되도록 하세요. 비밀 키는 보호된 환경 파일이나 비밀 관리자에 보관하고 해당 파일의 권한을 제한하세요. 버전 관리 시스템에 커밋하지 마세요.

services:
  onlyoffice:
    image: onlyoffice/documentserver:YOUR_PINNED_TAG
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: ${ONLYOFFICE_JWT_SECRET}

ONLYOFFICE_JWT_SECRET배포 환경 또는 보호된 파일에서 정의하십시오 .env. `<tag>`에 의존하는 대신 테스트를 거친 이미지 태그를 고정하고 latest, 실행하는 정확한 태그에 대한 문서를 확인하십시오. 환경 값을 변경한 후에는 일반적인 배포 프로세스를 사용하여 컨테이너를 다시 생성하십시오. 단순히 재시작하면 이전 환경이 유지될 수 있습니다.

커넥터를 업데이트하고 비밀 정보를 보호하세요.

Nextcloud 또는 기타 지원되는 커넥터와 같이 ONLYOFFICE Docs에 연결하는 플랫폼에서 통합 설정을 엽니다. 비밀 키 필드에 동일한 JWT 비밀 키를 입력하고 저장합니다. 구성된 문서 서버 URL과 커넥터에서 제공하는 경우 인증 헤더도 확인합니다. ONLYOFFICE Docs의 기본 헤더는 입니다. Authorization양쪽 모두 동일한 대체 헤더를 사용하도록 구성된 경우에만 변경하십시오.

비밀 키 불일치는 일반적으로 문서를 열거나 저장할 때 유효하지 않은 토큰 또는 권한 오류로 나타납니다. 또한 로드 밸런서 뒤에 있는 Docs 노드 중 하나만 업데이트된 경우에도 불일치가 발생할 수 있습니다. 여러 노드를 운영하는 경우, 모든 노드로 트래픽을 전송하기 전에 동일한 비밀 키 및 토큰 설정을 동기화해야 합니다. 변경 사항은 단계적으로 배포하십시오. Docs와 커넥터를 동시에 업데이트하고, 전환 기간 동안 이전 값으로 서명된 기존 편집기 세션이나 요청이 실패할 수 있음을 예상하십시오.

비밀 키를 읽을 수 있는 사람은 누구나 서버에서 허용하는 토큰을 생성할 수 있습니다. 구성 파일 및 배포 변수에 대한 접근을 제한하고, 커넥터와 Docs 간 연결에는 암호화된 전송 방식을 사용하며, 비밀 키가 노출되었을 가능성이 있는 경우 정기적으로 교체하십시오. 비밀 키 교체 시에는 모든 Docs 노드와 커넥터를 새 값으로 업데이트해야 합니다. 체크인된 파일이나 로그에 이전 자격 증명을 남겨두지 마십시오.

구성을 확인하세요

• 구성 변경 후 Docs 서비스 또는 컨테이너가 실행 중인지 확인하십시오.
• Docker 배포 환경에서는 sudo docker exec <container_name> sudo documentserver-jwt-status.shJWT 상태를 확인하려면 다음 명령을 실행하세요. 실제 컨테이너 이름을 사용해야 합니다. 이 헬퍼는 Docker 환경을 기준으로 작성되었으므로 모든 패키지 설치 환경에서 사용 가능하다고 가정하지 마세요.
• 연결된 플랫폼을 통해 문서를 열고 간단한 편집을 한 후 저장하세요. 편집기가 제대로 열리고 플랫폼에 저장된 변경 사항이 반영되었는지 확인하세요.
• 인증에 실패하면 서버와 커넥터의 비밀 키를 문자 단위로 비교하고, 관련 토큰 스위치가 모두 활성화되어 있는지 확인하고, 요청 헤더 구성을 검증하십시오.

공식 구성 가이드는 지원되는 설정 및 버전 동작에 대한 가장 권위 있는 자료입니다. 배포하려는 정확한 버전에 대해서는 ONLYOFFICE의 JWT 구성 문서 와 공식 Docker 설치 매개변수를 참조하십시오.