ONLYOFFICE Nextcloud 연동 시 "토큰이 유효하지 않습니다" 오류 해결 방법

ONLYOFFICE에서 "토큰이 유효하지 않습니다" 라는 메시지가 표시되는 것은 일반적으로 통합의 양쪽에서 동일한 JSON 웹 토큰(JWT)을 검증하지 않았기 때문입니다. Nextcloud 환경에서는 토큰을 사용하는 경로가 여러 가지라는 점이 중요합니다. 브라우저로 전송되는 에디터 구성, ONLYOFFICE Docs로 들어오는 요청, 그리고 Nextcloud로 나가는 콜백과 같은 요청 등이 있습니다. 이러한 경로 중 어느 하나라도 오류가 발생하면 사용자 입장에서는 비슷한 오류 메시지가 나타날 수 있습니다.

설정을 변경하기 전에 알아두어야 할 중요한 사항이 하나 있습니다. ONLYOFFICE Docs에서는 버전 7.2부터 JWT가 기본적으로 활성화되어 있으며 , 문서 서버에서 자동으로 비밀 키를 생성할 수 있습니다. 따라서 "JWT를 비활성화 상태로 유지하세요"라고 안내하는 이전 튜토리얼은 최신 설치 환경에서는 적절하지 않습니다. ONLYOFFICE는 현재 자체 비밀 키를 구성하고 커넥터에서 동일한 비밀 키를 사용하도록 권장합니다. 자세한 내용은 ONLYOFFICE의 JWT 구성 가이드를 참조하십시오 .

빠른 참조: 먼저 확인해야 할 사항

1. 공유 비밀 키가 실제로 동일한지 확인합니다.

JWT 유효성 검사는 공유 비밀 키에 따라 달라집니다. ONLYOFFICE Docs는 해당 비밀 키로 토큰에 서명하고, 수신 측은 동일한 값을 사용하여 서명을 검증합니다. 문자 하나 차이, 후행 공백, 이전 환경 변수 또는 새로 생성된 Docker 비밀 키만으로도 유효해 보이는 토큰이라도 검증에 실패할 수 있습니다.

Nextcloud에서 커넥터는 해당 jwt_secret설정을 지원합니다. 공식 커넥터는 구성 인터페이스도 제공하므로 활성화되어 있다고 생각하는 구성 파일에 의존하는 대신 Nextcloud에서 실제로 사용하는 값을 확인할 수 있습니다. 커넥터의 현재 설정은 공식 ONLYOFFICE Nextcloud 커넥터 READMEocc 에 설명되어 있습니다 .

sudo -u www-data php occ config:app:get onlyoffice jwt_secret
sudo -u www-data php occ config:app:get onlyoffice jwt_header

비밀 키를 지원 티켓, 스크린샷, 다른 사람과 공유하는 셸 기록 또는 공개 문제 보고서에 붙여넣지 마십시오. 로컬에서 비교하십시오.

ONLYOFFICE Docs의 네이티브 Linux 설치에서 지원되는 구성 파일은 다음과 같습니다.

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE 문서에서는 브라우저, 받은 편지함, 보낸 편지함 토큰 설정을 별도로 지정합니다. 유효성 검사에 사용되는 비밀 값은 커넥터 구성과 일치해야 합니다. 이 설정은 편집하지 마십시오 default.json. ONLYOFFICE는 재시작 또는 업그레이드 시 기본값이 덮어쓰여질 수 있음을 명시적으로 경고합니다. local.json패키지 설치 시에만 사용하십시오.

ONLYOFFICE Docs를 Docker에서 실행하는 경우

local.json컨테이너 내부에서 직접 편집하는 대신 Docker 환경 변수를 사용하세요 . ONLYOFFICE는 Docker가 시작 시 JWT 구성을 다시 생성할 수 있다고 명시하고 있으며, 공식 이미지는 JWT_ENABLED, JWT_SECRET, JWT_HEADER, 를 지원합니다 JWT_IN_BODY. 현재 Docker 이미지 문서에는 Authorization가 기본 JWT 헤더로 나열되어 있습니다. 공식 Docker DocumentServer 저장소를 참조하세요 .

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=replace-with-a-long-random-secret
  - JWT_HEADER=Authorization

Docker 환경 변수를 변경한 후에는 컨테이너를 다시 생성하여 실행 중인 서비스가 변경된 변수를 적용받도록 해야 합니다. 컨테이너를 다시 생성하지 않고 Compose 파일만 편집하는 것은 기존 환경 변수를 변경하지 않습니다.

2. JWT 헤더가 정확히 일치하도록 하십시오.

흔히 헤더 이름이 단순히 형식적인 것이라고 오해하는데, 그렇지 않습니다. ONLYOFFICE Docs는 수신함 및 발신함 토큰 헤더를 구성할 수 있으며, Nextcloud 커넥터에도 jwt_header설정이 있습니다. 이 헤더들은 동일한 요청 경로를 설명해야 합니다.

현재 ONLYOFFICE API 문서에는 Authorization수신 JWT 요청에 대한 문서 서버 기본값으로 가 명시되어 있으며, Nextcloud 공식 통합 문서에서도 마찬가지로 Authorization일반 커넥터 기본값으로 를 지정합니다. 이전 예제 및 기존 설치 환경에서는 또는 다른 명시적으로 구성된 값을 사용할 수 있습니다 . 따라서 안전한 규칙은 "항상 특정 문자열 하나만 사용"하는 것이 아니라 양쪽에서 활성 구성이 일치하도록 하는AuthorizationJWT 것입니다 .

요청 형식 또한 중요합니다. ONLYOFFICE의 API 문서에 따르면 헤더 토큰은 Bearer 스키마를 사용하여 전송됩니다. 기본 프로토콜에 대한 자세한 내용은 ONLYOFFICE 헤더 토큰 문서를 참조하십시오 .

의도적으로 사용자 지정 헤더를 사용하는 경우 두 제품 모두에 동일한 값을 설정하십시오. 사용자 지정할 이유가 없다면 현재 기본값을 사용하는 것이 Authorization설정을 간소화하는 데 도움이 됩니다.

3. 리버스 프록시가 토큰 경로를 변경하는지 확인하십시오.

Nextcloud와 ONLYOFFICE 설정이 일치하는데도 오류가 계속 발생하면 두 시스템 간의 경로를 점검하십시오. 리버스 프록시, 인증 게이트웨이, WAF 또는 인그레스 컨트롤러가 인증 헤더에 영향을 줄 수 있습니다. 이는 사용하는 스택에 따라 다르므로 증거 없이 프록시가 원인이라고 단정짓지 마십시오.

다음 실용적인 테스트 순서를 활용하세요:

• Nextcloud 호스트에서 공개 문서 서버 URL에 접속 가능한지 확인하십시오.
• 구성된 경우 내부 문서 서버 URL이 Nextcloud 서버 또는 컨테이너에서 제대로 확인되는지 확인하십시오.
• ONLYOFFICE Docs 호스트 또는 컨테이너에서 내부 Nextcloud/스토리지 URL이 제대로 확인되는지 확인하십시오.
• 커넥터 검사를 실행하는 동안 프록시 액세스/오류 로그를 검사하십시오.
• 프록시에 명시적인 규칙이 있는 경우 Authorization, 헤더를 대체하거나 제거하는 대신 전달하는지 확인하십시오.

오류를 없애기 위해 JWT를 비활성화하지 마십시오. 그렇게 하면 오류를 수정하는 것이 아니라 유효성 검사 메커니즘 자체가 제거됩니다. 또한 JWT 문제를 해결하기 위해 TLS 검증을 비활성화하지 마십시오. 인증서 검증과 JWT 서명 유효성 검사는 별개의 제어 기능입니다. 인증서에 문제가 있는 경우 인증서 체인 또는 신뢰 구성을 각각 수정하십시오.

4. 커넥터 자체의 상태 점검 기능을 사용하십시오.

공식 ONLYOFFICE 커넥터에는 특별히 고안된 진단 명령이 포함되어 있습니다.

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

커넥터 설명서에 따르면 이 검사는 연결 성공 여부 또는 오류 원인을 보고합니다. 이 검사는 문서 서버 랜딩 페이지만 테스트하는 것보다 Nextcloud 관점에서 통합 기능을 테스트하기 때문에 더 유용합니다.

문서 서버에 연결할 수 있지만 토큰 유효성 검사에 실패하면 비밀 키와 헤더로 돌아가십시오. 서버에 전혀 연결할 수 없는 경우 JWT에 더 많은 시간을 투자하기 전에 DNS, 라우팅, 방화벽, TLS 또는 내부 URL 문제를 해결하십시오.

5. 증거가 가리키는 경우에만 시간을 확인하십시오.

JWT에는 시간 관련 클레임이 포함될 수 있으며 Nextcloud 커넥터는 관련 설정 jwt_leeway및 기능을 제공합니다 jwt_expiration. 하지만 그렇다고 해서 먼저 시간 여유를 늘려야 한다는 의미는 아닙니다. 시계가 심각하게 잘못된 경우, 다른 부분은 정확한 토큰이라도 오류가 발생할 수 있으며, 시간 여유를 늘리면 인프라 문제를 숨길 수 있습니다.

Nextcloud 및 ONLYOFFICE 호스트 또는 컨테이너의 UTC 시간을 비교하십시오.

date -u
timedatectl status

두 시스템의 시간이 안정적으로 동기화되는지 확인하십시오. 작고 합법적인 시계 차이를 확인한 후에만 제한된 오차 범위를 고려하십시오. 커넥터에서 지원하는 JWT 설정은 공식 커넥터 구성 참조 에서 확인할 수 있습니다 .

이 통합에서 JWT 유효성 검사가 작동하는 방식

ONLYOFFICE Docs는 JWT를 사용하여 에디터 초기화 및 서버 간 요청을 보호합니다. API는 브라우저 토큰을 수신 및 발신 HTTP 요청 토큰과 분리합니다. 수신 요청의 경우 토큰은 헤더에 포함되거나, 지원되는 POST 요청의 경우 요청 본문에 포함될 수 있습니다. GET 요청의 경우 ONLYOFFICE 문서에서 헤더 기반 토큰 처리 방식을 설명합니다. 자세한 내용은 공식 요청 서명 문서를 참조하십시오 .

이는 한 작업은 성공하지만 다른 작업은 실패하는 이유를 설명합니다. 예를 들어, 편집기 열기는 성공하지만 이후 콜백이나 다운로드 요청은 실패할 수 있는데, 이는 한쪽 방향에만 올바른 토큰 설정이 있는 경우입니다.

흔히 잘못 알려진 사실들

"/healthcheck가 true를 반환하면 JWT가 올바른 것입니다."

아니요. 상태 엔드포인트는 서비스가 응답하고 있음을 증명하는 것이지, Nextcloud 커넥터와 문서 서버가 동일한 JWT 비밀 키와 헤더를 공유한다는 것을 증명하는 것은 아닙니다. 조치:occ onlyoffice:documentserver --check 유효한 커넥터 설정을 실행 하고 검사하십시오.

"Docker 컨테이너 내부의 local.json 파일을 편집하면 됩니다."

Docker 배포 환경에서는 이러한 설정이 불안정할 수 있습니다. ONLYOFFICE는 시작 시 구성이 다시 생성될 수 있으므로 Docker 환경 변수를 통해 JWT를 설정하는 것을 권장합니다. 조치:JWT_ENABLED 컨테이너 구성에 , JWT_SECRET, 및 필요한 경우 를 정의하고 JWT_HEADER컨테이너를 다시 생성하십시오.

"AuthorizationJWT는 항상 필수 헤더입니다."

아니요. 현재 공식 문서 서버 구성에서는 Authorization기본 헤더로 지정되어 있지만, 기존 배포 및 이전 예제에서는 명시적으로 구성된 다른 헤더를 사용할 수 있습니다. 조치: 두 활성 구성을 모두 읽고 동일하게 만드십시오.

“JWT를 끄는 것이 가장 빠른 해결책입니다.”

이렇게 하면 즉각적인 유효성 검사 오류는 해결될 수 있지만, 보안 제어 기능이 제거되어 근본적인 불일치가 숨겨질 수 있습니다. 조치: JWT 없이 운영해야 하는 명확한 이유가 문서화되어 있지 않은 한, 공유 비밀 키/헤더를 수정하십시오.

최종 검증 체크리스트

• Nextcloud와 ONLYOFFICE Docs에 동일한 JWT 비밀 키가 구성되어 있습니다.
• JWT 헤더 이름이 양쪽에서 일치합니다.
• Docker 배포는 컨테이너 내부에서 임의로 환경 변수를 수정하는 방식이 아니라, 영구적인 환경 변수를 사용합니다.
• 공용 및 내부 서버 URL은 사용되는 방향으로 접속할 수 있습니다.
• 프록시 규칙이 예기치 않게 JWT 헤더를 삭제하거나 덮어쓰는 경우는 없습니다.
• Nextcloud와 ONLYOFFICE 시스템은 시계가 동기화되어 있습니다.
• occ onlyoffice:documentserver --check성공합니다.
• 실제 문서는 열리고, 편집되고, 자동 저장되고, 닫히고, 저장된 변경 사항으로 다시 열립니다.

토큰 오류가 여전히 남아 있는 경우

비밀 키와 헤더가 일치하고, 시계가 동기화되었으며, 커넥터 검사가 성공했지만 특정 작업에서 여전히 유효하지 않은 토큰 오류가 발생하는 경우, 추가 설정을 변경하기 전에 오류가 발생한 정확한 요청 방향과 관련 로그를 캡처하십시오. ONLYOFFICE는 브라우저, 받은 편지함, 보낸 편지함 유효성 검사를 구분하므로, 다음으로 확인해야 할 사항은 오류가 편집기 초기화 중, 문서 서버로 전송된 명령 중, 또는 Nextcloud로 전송된 콜백/다운로드 중 어느 과정에서 발생했는지입니다.

문서 서버 로그와 Nextcloud 로그 및 프록시 로그를 동일한 타임스탬프와 함께 사용하십시오. JWT 또는 비밀 키를 공개적으로 게시하지 마십시오. 토큰 구조를 비교해야 하는 경우 서명과 민감한 클레임을 삭제하십시오. 서명 및 유효성 검사에 대한 참조 동작은 ONLYOFFICE의 서명 관련 문서를 참조하십시오 .