Nextcloud에서 ONLYOFFICE의 "토큰이 유효하지 않습니다" 오류 해결 방법

Nextcloud가 ONLYOFFICE Docs에 연결할 때 "토큰이 유효하지 않습니다"라는 오류 메시지를 표시하는 경우, 커넥터의 JWT 비밀 키가 문서 서버에서 실제로 사용하는 비밀 키와 일치하는지 확인하십시오. ONLYOFFICE Docs 7.2 이상 버전에서는 JWT 유효성 검사가 기본적으로 활성화되어 있고 비밀 키가 자동으로 생성됩니다. Nextcloud 설정만 변경하거나 Docker 컨테이너에서 생성된 구성 파일을 편집하면 양쪽의 비밀 키가 일치하지 않을 수 있습니다.

JWT를 활성화 상태로 유지하십시오. 먼저 활성 비밀 키와 배포 유형을 확인하고, 올바른 구성을 업데이트한 다음 커넥터의 연결 확인을 실행하십시오. 확인 결과 연결이 성공해야 합니다. 브라우저 편집기가 열리는 것만으로는 문서 다운로드 및 콜백이 제대로 작동하는 것을 보장할 수 없습니다.

오류 메시지는 무엇을 알려주나요?

JWT(JSON Web Token)는 Nextcloud와 ONLYOFFICE Docs 간의 요청이 신뢰할 수 있는지 확인하는 데 사용되는 서명된 토큰입니다. 커넥터는 구성된 비밀 키로 요청에 서명하고, 문서 서버는 구성된 비밀 키를 사용하여 서명을 검증합니다. 서명에 사용된 비밀 키가 서로 다르면 토큰 서명을 검증할 수 없으므로 요청이 거부됩니다.

가장 일반적인 원인은 이전 설치에서 복사한 비밀 키, Nextcloud에 입력되지 않은 자동 생성된 비밀 키, 컨테이너를 다시 생성할 때 적용되지 않은 변경된 Docker 환경 변수, 또는 문서 서버 구성의 일관성 없는 비밀 키 값입니다. 커넥터와 문서 서버에서 동일한 헤더 이름을 사용하지 않는 경우 사용자 지정 JWT 헤더로 인해 불일치가 발생할 수도 있습니다.

이 문서에서는 JWT 불일치 문제를 다룹니다. 만약 서버에 연결할 수 없거나, 인증서가 유효하지 않거나, 문서를 다운로드할 수 없다는 오류 메시지가 표시된다면, 서버 주소, TLS 인증서, Nextcloud와 문서 서버 간의 네트워크 경로를 각각 조사하십시오. JWT를 수정해도 이러한 문제는 해결되지 않습니다.

1. 활성 문서 서버 암호를 찾으십시오.

실행 중인 문서 서버의 구성을 사용하십시오. 이전 컨테이너 또는 서버에서 저장된 비밀 키가 여전히 활성화되어 있다고 가정하지 마십시오.

• Linux: 검사 /etc/onlyoffice/documentserver/local.json.
• 윈도우: 검사 %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json.
• Docker: 실행 중인 컨테이너에서 시크릿을 읽습니다. 공식 이미지에서도 다음 명령어를 사용하여 세션 시크릿을 읽을 수 있습니다.

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

컨테이너 이름 또는 ID를 실제 값으로 바꾸십시오 <containerID>. 반환된 값은 자격 증명으로 간주하므로 지원 포럼, 스크린샷 또는 공개 로그에 붙여넣지 마십시오.

에서 , , 및 local.json의 값을 비교하십시오 . 표준 설정에서는 이 값들이 모두 동일해야 합니다. 또한 브라우저, 요청 수신함 및 요청 발신함에 대해 토큰 유효성 검사가 활성화되어 있는지 확인하십시오. Docs 7.2 이전 버전에서는 토큰 유효성 검사를 명시적으로 활성화해야 하지만, 이후 버전에서는 기본적으로 활성화되어 있습니다.services.CoAuthoring.secret.inbox.stringservices.CoAuthoring.secret.outbox.stringservices.CoAuthoring.secret.session.string

2. Nextcloud의 ONLYOFFICE 커넥터를 업데이트하세요

1. Nextcloud 관리자로 로그인한 다음 설정 > 관리 > ONLYOFFICE를 엽니다 .
2. 서버 설정에서 실행 중인 문서 서버에 있는 정확한 비밀 키를 '비밀 키' 필드에 입력하십시오. 앞뒤에 공백을 넣지 말고, 비밀 키 자체에 포함된 경우가 아니면 따옴표를 추가하지 마십시오.
3. 배포 환경에서 사용자 지정 헤더를 사용하는 경우 JWT 헤더 설정을 확인하십시오. 커넥터 jwt_header설정과 문서 서버에 구성된 토큰 헤더가 일치해야 합니다. 의도적으로 헤더를 사용자 지정하지 않은 경우 이 복구 과정에서 헤더를 변경하지 마십시오.
4. 설정을 저장하세요. 양쪽 모두 JWT를 활성화된 상태로 유지하세요.

occ문서화된 커넥터 설정은 Nextcloud 설치 디렉터리에서 Nextcloud 명령어를 사용하여 변경할 수도 있습니다 .

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

실제 값으로 대체하십시오 YOUR_SECRET. 셸 따옴표는 구두점을 유지하는 데 도움이 되지만, 작은따옴표가 포함된 비밀 값은 명령줄에 직접 삽입하는 것보다 더 안전한 방법이 필요합니다. 명령줄 인수는 권한 있는 프로세스의 검사 또는 셸 기록에 노출될 수도 있습니다. 가능하면 관리자 인터페이스를 사용한 다음, 값을 노출하지 않고 저장된 값을 확인하십시오.

3. 설치 환경에 맞게 변경 사항을 적용하세요.

도커 또는 도커 컴포즈

Docker 배포의 경우, 자동으로 생성된 파일을 수동으로 편집하는 대신 컨테이너 환경을 통해 JWT를 구성하십시오 local.json. 문서 서버 서비스 정의에도 동일한 비밀 키를 설정하십시오.

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

작성 파일을 변경한 후에는 환경 설정이 적용되도록 문서 서버 컨테이너를 다시 생성해야 합니다. 예를 들어, 작성 파일이 있는 디렉터리에서 다음과 같이 하면 됩니다.

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

Compose 파일에서 서비스 이름을 바꿔 사용하십시오. 단순히 재시작하는 것만으로는 기존 컨테이너에 변경된 환경 변수 값이 적용되지 않습니다. `return` 명령어를 사용하는 경우 , 기존 포트, 볼륨 및 기타 필수 옵션을 유지하면서 업데이트된 값 으로 docker run컨테이너를 다시 생성하십시오 . 이러한 설정과 영구 데이터 마운트를 확인하기 전까지는 프로덕션 컨테이너를 삭제하지 마십시오.JWT_ENABLEDJWT_SECRET

컨테이너가 시작되면 위 명령어를 사용하여 활성 시크릿을 다시 읽고 값이 Nextcloud와 일치하는지 확인하십시오. 프로덕션 시크릿을 공개적으로 공유되는 Compose 파일이나 소스 저장소에 두지 마십시오.

리눅스 패키지 또는 윈도우 설치

의도적으로 사용자 지정 암호를 설정한 경우 local.json, 세 가지 암호 필드가 일치하고 필수 토큰 유효성 검사 값이 활성화되어 있는지 확인하십시오. 변경 사항을 적용하려면 관련 문서 서버 서비스를 다시 시작하십시오. 현재 ONLYOFFICE 지침에는 Linux에서 ds-converter, ds-docservice, 및 를 ds-metrics사용하는 방법이 나와 있습니다. 다른 서비스 관리자가 관리하는 설치 환경에서는 해당 설정에 맞는 다시 시작 방법이 필요할 수 있습니다. Windows에서는 구성을 저장한 후 ONLYOFFICE 서비스를 다시 시작하십시오.

재시작 후에도 불일치가 발생하는 경우는 일반적으로 생성된 구성 또는 배포 환경이 편집된 파일을 덮어쓰고 있음을 의미합니다. Docker의 경우, 수정된 내용을 환경 변수로 이동한 후 컨테이너를 다시 생성하십시오. 패키지 배포의 경우, 추가 설정을 변경하기 전에 활성 구성과 서비스 시작 구성을 확인하십시오.

수리를 확인하세요

1. Nextcloud 설치 디렉터리에서 공식 커넥터 검사를 실행하세요.

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

설치 환경에 맞는 웹 서버 계정을 사용하십시오 www-data. 명령 실행 후 연결이 성공적으로 완료되었다는 메시지가 표시되어야 합니다. 만약 여전히 유효하지 않은 토큰 오류가 발생한다면, 실행 중인 문서 서버의 활성 비밀 키가 Nextcloud와 정확히 일치하는지, 그리고 사용자 지정 JWT 헤더가 일치하는지 다시 한번 확인하십시오.

2. Nextcloud에서 ONLYOFFICE를 사용하여 간단한 테스트 문서를 엽니다. 편집기가 제대로 로드되는지 확인하고, 간단한 변경을 한 후 저장하고 편집기를 닫은 다음 파일을 다시 열어 변경 사항이 저장되었는지 확인합니다.
3. 네트워크 또는 인증서 오류가 보고되면 JWT 값 변경을 중지하십시오. Nextcloud가 문서 서버 주소에 연결할 수 있는지, 그리고 문서 서버가 Nextcloud 콜백 주소에 연결할 수 있는지 확인하십시오. 가능한 경우 신뢰할 수 있는 TLS 인증서를 사용하십시오. 인증서 확인을 비활성화하는 것은 안전하지 않은 임시 해결책이며 토큰 유효성 검사 문제를 해결하지 못합니다.

이러한 검사는 구성된 연결과 기본 저장 경로가 제대로 작동하는지 확인합니다. 하지만 모든 리버스 프록시 경로, 외부 스토리지 구성 또는 다중 서버 토폴로지가 올바르다는 것을 증명하는 것은 아닙니다. 배포 환경에서 이러한 경로를 사용하는 경우 별도로 테스트해야 합니다.

공식 참조

• ONLYOFFICE: Nextcloud 연동 및 JWT 설정
• ONLYOFFICE: 문서 서버용 JWT 구성
• ONLYOFFICE Nextcloud 커넥터: 구성 옵션 및 occ 명령

구성 세부 정보는 2026년 10월 9일에 ONLYOFFICE 공식 문서 및 커넥터 저장소를 기준으로 확인되었습니다. 사용자 인터페이스 레이블 및 서비스 관리는 커넥터, 운영 체제 및 배포 방법에 따라 다를 수 있습니다.