Collabora Online에서 "WOPI 증명 유효성 검사 실패" 오류를 해결하는 방법

오류가 기록된 시스템부터 시작하세요.

"WOPI 증명 유효성 검사 실패"는 WOPI 호스트가 Collabora Online에서 보낸 서명된 요청을 검증할 수 없음을 의미합니다. 일반적인 Nextcloud Office 구성에서 Nextcloud는 WOPI 호스트이고 Collabora는 WOPI 클라이언트입니다. Collabora가 서명된 요청을 보내면 호스트가 이를 확인합니다. 정확한 메시지 문구는 통합 및 릴리스에 따라 다를 수 있으므로 먼저 어떤 구성 요소에서 메시지가 발생했고 어떤 요청이 실패했는지 확인해야 합니다.

이 인증 절차는 일반적인 연결 테스트가 아닌 보안 검사입니다. 요청을 액세스 토큰, 전체 요청 URL 및 타임스탬프에 연결한 다음 Collabora의 개인 인증 키로 해당 데이터에 서명합니다. 호스트는 Collabora의 검색 XML에 게시된 공개 인증 키를 사용하여 서명을 확인합니다. WOPI 프로토콜 정의는 서명된 필드와 헤더를 설명합니다.

첫 번째 조치: 오류를 한 번 재현하고 시간, 파일 작업, HTTP 상태 및 요청 또는 상관 관계 ID를 기록한 다음 스토리지 플랫폼의 로그와 Collabora의 coolwsd로그에서 동일한 이벤트를 확인하십시오. 티켓에 액세스 토큰, 증명 헤더 또는 개인 키를 게시하지 마십시오.

빠른 진단표

1. 검색을 통해 현재 공개 키가 노출되는지 확인합니다.

Collabora는 검색 엔드포인트에 WOPI 기능 및 증명 키 정보를 게시합니다. 스토리지 서버에서 사용하는 Collabora URL에 접근할 수 있는 컴퓨터에서 다음을 확인하십시오.

curl -fsS https://office.example.com/hosting/discovery

XML에서 proof-key현재 상태 value와 (있는 경우) 값을 가진 요소를 찾으십시오 oldvalue. 이 공개 자료를 Collabora 서버에 저장된 개인 키와 혼동하지 마십시오. 가장 유용한 비교 대상은 WOPI 호스트 자체에서 가져온 검색 응답입니다. 브라우저나 관리자 워크스테이션은 DNS, 프록시 또는 캐시를 통해 다른 응답을 받을 수 있기 때문입니다.

확인됨: Collabora의 WOPI 통합은 증명 서명을 사용하며, 공개 키는 검색을 통해 제공됩니다. 조치: 요청 유효성 검사를 수행하는 실제 호스트/컨테이너에서 검색 정보를 가져온 다음, XML이 유효하고 스토리지 플랫폼에 구성된 Collabora 엔드포인트와 일치하는지 확인합니다. Collabora SharePoint 바인딩 가이드에서 증명 키 생성 및 검색 동작에 대한 설명을 확인할 수 있습니다.

2. 개인 키가 존재하고 읽을 수 있는지 확인합니다.

Collabora에서 시작 로그를 검사하여 인증 키 파일이 없거나 읽을 수 없다는 경고가 있는지 확인하십시오. Collabora 서비스는 서명을 위해 개인 키를 읽을 수 있어야 합니다. 패키지 배포의 경우 구성 경로와 서비스 계정이 다를 수 있으므로 호스트 경로를 가정하지 말고 서비스가 구성된 디렉터리와 컨테이너 볼륨 마운트를 확인하십시오.

Collabora 문서에서 coolconfig generate-proof-key자동 키 설정이 작동하지 않는 경우를 설명합니다. 정상 작동 중인 클러스터에서 일상적인 문제 해결 명령으로 실행하지 마십시오. 새 키를 생성하면 서명 ID가 변경됩니다. 스토리지 측에서 이전 검색 응답을 여전히 신뢰하는 경우 호스트가 사용하는 공개 키를 갱신할 때까지 요청이 계속 실패할 수 있습니다.

sudo coolconfig generate-proof-key

해당 명령은 키가 없거나 유효하지 않음을 확인하고 모든 Collabora 노드와 WOPI 호스트가 일치하는 키 정보를 수신하는 방법을 계획한 후에만 사용하십시오. 그런 다음 패키지 또는 컨테이너 배포에 명시된 서비스 재로드 절차를 따르고 검증자의 네트워크 경로에서 검색 정보를 다시 가져오십시오.

3. 노드 또는 캐시 간 키 불일치를 확인합니다.

단일 Collabora 서버는 정상적으로 작동하는 반면, 로드 밸런싱된 배포 환경에서는 간헐적으로 오류가 발생할 수 있습니다. 예를 들어, 한 노드는 새로 생성된 개인 키를 사용하는 반면 다른 노드는 여전히 이전 키로 서명할 수 있으며, 캐시된 검색 데이터를 사용하는 호스트는 어느 키도 일관되게 신뢰하지 않을 수 있습니다. 이는 배포 환경에 따라 발생하는 원인이며, 모든 간헐적 오류가 키 순환으로 인해 발생한다는 것을 의미하지는 않습니다.

조치: 로드 밸런서를 통해 데이터 를 가져오고 /hosting/discovery, 허용되는 경우 각 백엔드에서 직접 데이터를 가져옵니다. 공개 키 값을 비교하고 WOPI 호스트의 검색 캐시가 최신 상태인지 확인합니다. 노드에서 의도적으로 별도의 키를 사용하는 경우 스토리지 통합이 해당 토폴로지를 지원하는지 확인하고, 그렇지 않으면 클러스터 전체에서 증명 키 구성을 일관되게 유지합니다. 검색 새로 고침은 통합에서 지원하는 메커니즘을 사용해야 합니다. 근거 없이 데이터베이스 캐시를 수정하거나 관련 없는 서비스를 재시작하지 마십시오.

4. 서명된 URL과 호스트가 유효성을 검사하는 URL을 비교합니다.

이 증명은 절대적인 WOPI 요청 URL(대문자)과 토큰 및 타임스탬프를 포함합니다. 따라서 URL 재작성이 중요합니다. 리버스 프록시는 외부에서 보이는 호스트 이름, 스키마, 포트, 경로 또는 이스케이핑을 변경할 수 있습니다. Collabora가 특정 URL에 대한 요청에 서명했지만 WOPI 호스트가 검증을 위해 다른 URL을 재구성하는 경우, 올바른 서명이라도 유효하지 않은 것으로 나타날 수 있습니다.

조치: 프록시 및 애플리케이션 계층에서 발생한 실패한 요청 하나를 연관시켜 분석합니다. 검증자가 확인한 스키마, 호스트 이름, 명시적 포트, 경로 및 인코딩된 문자를 증명 검증 코드에 사용된 URL과 비교합니다. 애플리케이션이 해당 헤더에 의존하는 경우에만 forwarded-host 및 forwarded-proto 헤더 처리를 확인합니다. 실제 요청 URL을 보존하고, 서명 검사를 비활성화하거나 임의의 전달된 헤더를 신뢰하는 방식으로 문제를 "해결"하지 마십시오.

5. 타임스탬프 및 바이트 처리 유효성 검사

WOPI 증명에는 이 헤더가 포함됩니다 X-WOPI-TimeStamp. Microsoft WOPI 사양에서 이 헤더는 0001년 1월 1일 이후 100나노초 간격으로 측정된 64비트 정수이며, 초 단위의 유닉스 타임스탬프가 아닙니다. 사용자 지정 검증기가 이를 유닉스 초로 파싱하거나, 소수점을 버리거나, 인코딩을 변경하거나, 서명된 바이트를 잘못 조합하는 경우 유효한 요청을 거부할 수 있습니다.

호스트에서 최신성 보장 기간을 적용할 때 시간 편차가 문제의 원인 중 하나일 수 있지만, 정확한 허용 오차는 검증 구현에 따라 다릅니다. Microsoft 365 웹 버전에 대한 Microsoft의 지침에서는 20분의 시간 차이를 기준으로 검증을 수행하지만, 모든 Collabora 통합에 이 수치가 적용되는 것은 아닙니다. 조치: Collabora 및 스토리지 시스템의 NTP 동기화 및 UTC 시간을 확인한 다음, 호스트 자체의 문서화된 타임스탬프 규칙 및 구문 분석 코드를 검사하십시오.

사용자 지정 WOPI 호스트를 관리하는 경우 바이트 수준 구성도 확인하십시오. 토큰은 UTF-8 형식이고, 길이는 바이트 수이며, URL은 대문자로 된 전체 절대 URL이고, 타임스탬프 값은 지정된 대로 정확하게 표현되어야 합니다. 공개 키는 요청을 보낸 Collabora 인스턴스에서 사용한 개인 키와 일치해야 합니다.

6. 인증 실패와 허용 목록 오류 및 TLS 오류를 분리합니다.

WOPI 호스트 허용 목록은 Collabora가 연결할 수 있는 스토리지 호스트를 결정합니다. TLS 유효성 검사는 네트워크 피어의 인증서를 신뢰할 수 있는지 여부를 결정합니다. 증명 유효성 검사는 WOPI 요청의 서명을 확인합니다. 이러한 제어는 안전한 통합과 관련이 있지만 서로 대체할 수 없습니다. 호스트를 허용 목록에 추가해도 서명 불일치가 해결되지 않으며, TLS 검사를 비활성화해도 오래된 공개 증명 키가 수정되지 않습니다.

Nextcloud 배포의 경우 공식 문제 해결 가이드에서는 양방향 필수 HTTP(S) 경로 확인, Nextcloud 및 Collabora 로그 검토, WOPI 호스트 허용 목록 항목 확인(허용 목록 경고 확인)을 권장합니다. 조치: 로그의 오류 범주를 따르십시오. 검색 엔드포인트 및 네트워크 연결 가능성을 검증 도구와 별도로 테스트하십시오. 임시 해결책으로 허용 목록을 확장하지 마십시오 *.

안전 복구 시퀀스

1. 요청 실패의 정확한 시간을 기록하고 어떤 서비스에서 증명 유효성 검사 실패가 기록되었는지 확인하십시오.
2. Collabora 로그에서 키 누락 경고를 확인하고, WOPI 호스트의 네트워크 경로에서 검색 XML을 검사하십시오.
3. 검색 시 공개 키를 요청 서명에 사용된 개인 키 및 노드 구성과 비교합니다.
4. 로드 밸런서의 일관성, 검색 캐싱, 그리고 최근 키, 호스트 이름, 프록시 또는 TLS 변경 사항을 확인하십시오.
5. 토큰이나 증명 헤더를 노출하지 않고 서명된 요청 URL과 타임스탬프 처리 방식을 비교하십시오.
6. 하나의 문서로 다시 테스트하고 호스트 로그에서 동일한 요청이 성공했는지 확인한 후 정상적인 트래픽을 복원하십시오.

오류가 계속 발생하는 경우, 양쪽 끝에서 수집한 개인 정보가 삭제된 로그, Collabora 및 스토리지 버전, 배포 유형, 노드 수(하나 또는 여러 개), 비밀 키가 제거된 검색 XML, 그리고 오류가 발생한 요청에 대한 프록시 경로를 수집하십시오. 이 정보를 관련 공급업체 또는 통합 관리자에게 공유하십시오. 정확한 오류 문자열만으로는 검색 오류, URL 정규화 문제, 시간 문제 또는 사용자 지정 유효성 검사기 버그 등 원인을 파악할 수 없습니다. 요청 수준의 증거를 통해 어떤 방향으로 문제를 해결해야 할지 결정할 수 있습니다.