Collabora Onlineで「WOPI認証検証失敗」を修正する方法

障害を記録したシステムから始めましょう

「WOPI 証明検証失敗」とは、WOPI ホストが Collabora Online からの署名付きリクエストを検証できなかったことを意味します。一般的な Nextcloud Office の設定では、Nextcloud が WOPI ホスト、Collabora が WOPI クライアントです。Collabora が署名付きリクエストを送信し、ホストがそれを検証します。メッセージの文言は統合やリリースによって異なるため、まずどのコンポーネントがメッセージを発信し、どのリクエストが失敗したかを特定してください。

この証明はセキュリティチェックであり、一般的な接続テストではありません。リクエストをアクセストークン、完全なリクエストURL、タイムスタンプに紐付け、そのデータをCollaboraの秘密証明鍵で署名します。ホストは、Collaboraの検出XMLに公開されている公開証明鍵を使用して署名を検証します。WOPIプロトコル定義では、署名されるフィールドとヘッダーについて説明しています。

まず最初に、障害を一度再現し、発生時刻、ファイル操作、HTTPステータス、リクエストIDまたは相関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サーバーが1台だけなら正常に動作するのに、ロードバランシングされたデプロイメントでは断続的に障害が発生する場合があります。例えば、あるノードが新しく生成された秘密鍵を使用している一方で、別のノードは古い鍵で署名している場合、キャッシュされた検出データを持つホストはどちらの鍵も信頼できない可能性があります。これはデプロイメントに依存する原因であり、断続的なエラーがすべて鍵のローテーションによって引き起こされているという証拠にはなりません。

アクション：/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 ビット整数であり、秒単位の Unix タイムスタンプではありません。これを Unix 秒として解析したり、桁を削除したり、エンコーディングを変更したり、署名付きバイトを誤って組み立てたりするカスタムバリデーターは、有効な要求を拒否する可能性があります。

クロックのずれは、ホストが鮮度ウィンドウを強制する場合に考えられる原因の1つですが、正確な許容範囲は検証の実装によって異なります。Microsoft の Web 版 Microsoft 365 のガイダンスでは、20 分経過のチェックを使用していますが、この数値がすべての Collabora 統合に適用されるとは限りません。対処方法: Collabora とストレージシステムの NTP 同期と UTC 時刻を確認し、ホスト独自のタイムスタンプ規則と解析コードを調べます。

カスタムWOPIホストを使用している場合は、バイトレベルの構造も確認してください。トークンはUTF-8、長さはバイト数、URLは完全な絶対URL（大文字）、タイムスタンプ値は指定されたとおりに正確に表現する必要があります。公開鍵は、リクエストを送信したCollaboraインスタンスで使用されている秘密鍵と一致している必要があります。

6. 証明失敗を許可リストエラーおよびTLSエラーから分離する

WOPIホスト許可リストは、Collaboraが接続を許可するストレージホストを決定します。TLS検証は、ネットワークピアの証明書が信頼できるかどうかを判断します。証明検証は、WOPIリクエストの署名をチェックします。これらの制御はセキュアな統合に関連していますが、互換性はありません。ホストを許可リストに追加しても署名の不一致は修復されません。TLSチェックを無効にしても、古い公開証明鍵は修正されません。

Nextcloud のデプロイメントの場合、公式のトラブルシューティング ガイドでは、双方向で必要な HTTP(S) パスを確認し、Nextcloud および Collabora のログを確認し、WOPI ホストの allow-list エントリで allow-list 警告を確認することを推奨しています。アクション:ログのエラー カテゴリに従います。検出エンドポイントとネットワーク到達可能性を、証明バリデーターとは別にテストします。回避策として allow-list を拡張しないでください*。

安全な復旧手順

1. リクエストが失敗した正確な時刻を記録し、どのサービスが証明検証の失敗をログに記録したかを特定します。
2. Collaboraのログでキーの欠落に関する警告を確認し、WOPIホストのネットワークパスから取得した検出XMLを調べてください。
3. 検出時に取得した公開鍵と、リクエストの署名に使用された秘密鍵およびノー​​ド構成を比較してください。
4. ロードバランサーの一貫性、検出キャッシュ、および最近のキー、ホスト名、プロキシ、またはTLSの変更を確認してください。
5. トークンや証明ヘッダーを公開せずに、署名付きリクエストURLとタイムスタンプの処理方法を比較します。
6. 1つのドキュメントで再テストを行い、通常のトラフィックを復元する前に、ホストログで同じリクエストが成功していることを確認してください。

障害が解消されない場合は、両端からサニタイズ済みのログ、Collaboraとストレージのバージョン、デプロイメントの種類、ノードが1つか複数か、シークレットを削除した検出XML、および障害が発生したリクエストのプロキシルートを収集してください。これらの情報を関係ベンダーまたはインテグレーションの保守担当者と共有してください。正確なエラー文字列だけでは、原因が古い検出、URLの正規化、クロックの問題、またはカスタムバリデーターのバグのいずれであるかを特定することはできません。どの経路をたどるべきかは、リクエストレベルの証拠によって判断されます。