ONLYOFFICE Nextcloud連携における「トークンが無効です」エラーを修正する

ONLYOFFICEのメッセージ「トークンが無効です」は通常、連携する両側で同じJSON Webトークン（JWT）が検証されていないことを意味します。Nextcloudの設定では、ブラウザに送信されるエディタ設定、ONLYOFFICE Docsへの受信リクエスト、Nextcloudへのコールバックなどの送信リクエストといった、複数のトークンパスが存在することが重要です。これらのパスのいずれかでエラーが発生すると、ユーザー側からは同様のエラーメッセージが表示される可能性があります。

設定を変更する前に、重要な点が1つあります。ONLYOFFICE Docsではバージョン7.2以降、JWTがデフォルトで有効になっており、ドキュメントサーバーがシークレットを自動的に生成できます。そのため、「JWTを無効のままにする」という古いチュートリアルは、最新のインストール環境では適切な基準とは言えません。ONLYOFFICEの現在の推奨事項は、独自のシークレットを設定し、コネクタで同じシークレットを使用することです。詳しくは、ONLYOFFICEのJWT設定ガイドをご覧ください。

クイックリファレンス：最初に確認すべきこと

1. 共有シークレットが実際に同じであることを確認する

JWTの検証は、共有シークレットに依存します。ONLYOFFICE Docsはこのシークレットを使用してトークンに署名し、受信側は同じ値を使用して署名を検証します。1文字の違い、末尾の空白、古い環境変数、または再生成されたDockerシークレットなどによって、一見有効に見えるトークンでも検証に失敗する可能性があります。

Nextcloudでは、コネクタがこのjwt_secret設定をサポートしています。公式コネクタにはocc設定インターフェースも用意されているため、有効になっていると思われる設定ファイルに頼るのではなく、Nextcloudが実際に使用している値を確認できます。コネクタの現在の設定については、公式のONLYOFFICE NextcloudコネクタのREADMEファイルに記載されています。

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、、、、をサポートしています。現在のDockerイメージのドキュメントでは、がデフォルトのJWTヘッダーとして記載されていますJWT_SECRET。公式のDocker DocumentServerリポジトリを参照してください。JWT_HEADERJWT_IN_BODYAuthorization

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通常のコネクタのデフォルトとして識別されています。古い例や既存のインストールでは、 または明示的に構成された別の値を使用する場合があります。したがって、安全なルールは「常に 1 つの特定の文字列を使用する」ことではなく、アクティブな構成を両側で一致させることAuthorizationJWTです。

リクエストのフォーマットも重要です。ONLYOFFICEのAPIドキュメントでは、Bearerスキームを使用して送信されるヘッダートークンについて説明しています。基盤となるプロトコルの詳細については、ONLYOFFICEのトークンインヘッダーに関するドキュメントを参照してください。

意図的にカスタムヘッダーを使用する場合は、両方の製品で同じ値を設定してください。カスタマイズする理由がない場合は、現在のデフォルト値を使用することで、Authorization可動部品を減らすことができます。

3. リバースプロキシがトークンパスを変更していないか確認する

NextcloudとONLYOFFICEの設定が一致しているにもかかわらずエラーが解消されない場合は、両者間の経路を調べてください。リバースプロキシ、認証ゲートウェイ、WAF、またはイングレスコントローラーが認証ヘッダーに影響を与える可能性があります。これは使用しているシステム構成によって異なるため、証拠なしにプロキシが原因だと決めつけないでください。

以下の実技試験手順を使用してください。

• Nextcloudホストから公開ドキュメントサーバーのURLにアクセスできることを確認してください。
• 内部ドキュメントサーバーのURLが設定されている場合は、Nextcloudサーバーまたはコンテナから解決されることを確認してください。
• ONLYOFFICE Docsのホストまたはコンテナから、内部のNextcloud/storage 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 はヘッダーベースのトークン処理についてドキュメント化しています。公式の request-signature ドキュメントを参照してください。

これは、ある操作は成功するのに、別の操作が失敗する理由を説明しています。例えば、片方の方向のみに正しいトークン設定がある場合、エディタを開く操作は成功しても、後続のコールバックやダウンロード要求が失敗する可能性があります。

よくある誤解

「/healthcheckがtrueを返す場合、JWTは正しいはずです。」

いいえ。ヘルスエンドポイントはサービスが応答していることを証明しますが、Nextcloudコネクタとドキュメントサーバーが同じJWTシークレットとヘッダーを共有していることを証明するものではありません。対処方法：occ onlyoffice:documentserver --check有効なコネクタ設定を実行して確認してください。

「Dockerコンテナ内でlocal.jsonを編集すれば完了です。」

これはDockerデプロイメントにとって脆弱です。ONLYOFFICEは、起動時に構成が再生成される可能性があるため、Docker環境変数を介してJWTを設定することを推奨します。対処方法：コンテナ構成で、必要に応じて、、をJWT_ENABLED定義し、コンテナを再作成してください。JWT_SECRETJWT_HEADER

「AuthorizationJWTは常に必須のヘッダーです。」

いいえ。現在の公式ドキュメントサーバー構成では、Authorizationデフォルトのヘッダーとしてリストされていますが、既存のデプロイメントや古い例では、明示的に構成された別のヘッダーが使用されている場合があります。対処方法：アクティブな両方の構成を読み込み、同じ内容にしてください。

「JWTを無効にするのが最も手っ取り早い解決策です。」

即時の検証エラーは解消されるかもしれませんが、セキュリティ制御が失われ、根本的な不一致が隠蔽される可能性があります。対処法： JWTを使用せずに運用する明確な理由が文書化されていない限り、共有シークレット/ヘッダーを修正してください。

最終検証チェックリスト

• NextcloudとONLYOFFICEのドキュメントでは、同じJWTシークレットが設定されています。
• JWTヘッダー名は両側で一致しています。
• Dockerデプロイメントでは、コンテナ内部での一時的な編集ではなく、永続的な環境変数が使用されます。
• 公開サーバーおよび内部サーバーのURLは、それらが使用される方向からアクセス可能です。
• プロキシルールがJWTヘッダーを予期せず削除または書き換えることはありません。
• NextcloudとONLYOFFICEのシステムは時計が同期されています。
• occ onlyoffice:documentserver --check成功する。
• 実際の文書は、開いて編集し、自動保存し、閉じて、保存された変更内容で再度開きます。

トークンエラーがまだ残っている場合

シークレットとヘッダーが一致し、クロックが同期され、コネクタのチェックが成功しているにもかかわらず、特定の操作で無効なトークンが報告される場合は、設定を変更する前に、失敗したリクエストの正確な方向と対応するログを取得してください。ONLYOFFICE はブラウザ、受信トレイ、送信トレイの検証を区別するため、次の問題は、エラーがエディタの初期化中、ドキュメント サーバーに送信されるコマンド中、または Nextcloud に返されるコールバック/ダウンロード中に発生したかどうかです。

ドキュメントサーバーのログは、同じタイムスタンプのNextcloudログおよびプロキシログと併せて使用してください。完全なJWTやシークレットを公開することは避けてください。トークン構造を比較する必要がある場合は、署名と機密性の高いクレームを削除してください。署名と検証の参照動作については、ONLYOFFICEの署名ドキュメントを参照してください。