ONLYOFFICE JWTシークレットをサーバーとコネクタ間で設定する

一貫して強力な JWT シークレットを使用してください。ONLYOFFICE Docs でそのシークレットを設定し、接続先のプラットフォームの ONLYOFFICE 設定に同じ値をコピーして、JWT 検証を有効にしたままにします。Docs 7.2 以降では、JWT がデフォルトで有効になり、シークレットが自動的に生成されます。シークレットを変更すると、すべての統合を更新してシークレットを一致させる必要があります。サーバー側の具体的な方法は、Docs が Linux パッケージとして実行されるか、Docker コンテナとして実行されるかによって異なります。

何が一致しなければならないか？

JWT（JSON Web Token）を使用すると、ONLYOFFICE Docsは署名付きリクエストを検証できます。ドキュメントプラットフォームとDocsは、同じシークレットと互換性のあるヘッダー設定を使用する必要があります。サーバーは、ブラウザの設定、受信および送信サービスリクエストにそれぞれ別のトークン設定を使用します。共有シークレット値は、これらのやり取りを保護します。シークレットを公開Webページ、クライアント側のJavaScriptバンドル、サポートチケット、または公開可能なソースリポジトリに含めないでください。

編集を行う前に、デプロイメントの種類を特定し、コネクタが使用するドキュメントのURLを記録してください。パスワードマネージャーまたは暗号的に安全なジェネレータを使用して、長く予測不可能なシークレットを生成します。これを認証情報として扱い、制限付き構成ストアに保存してください。

Linuxのインストールを構成する

パッケージベースの Linux インストールの場合、 を編集します/etc/onlyoffice/documentserver/local.json。既存の設定を保持するには、ファイル全体を置き換えるのではなく、以下のキーを既存の JSON にマージします。この例は、公式設定ガイドで説明されているトークン検証構造と、それに一致する 3 つのシークレットの場所を示しています。

{
  "services": {
    "CoAuthoring": {
      "token": {
        "enable": {
          "request": {
            "inbox": true,
            "outbox": true
          },
          "browser": true
        }
      },
      "secret": {
        "inbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "outbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "session": { "string": "REPLACE_WITH_YOUR_SECRET" }
      }
    }
  }
}

すべてのプレースホルダーをまったく同じ秘密の値に置き換えてください。サンプルプレースホルダー自体を貼り付けないでください。browser、、inboxおよびoutboxスイッチは別々です。いずれか1つだけを有効にしても、すべてのリクエスト検証が有効になるわけではありません。ドキュメント7.2以降では、JWTはデフォルトで有効になっていますが、これらの設定を明示的に確認すると、既存の構成を監査したり、ノード間で動作を統一したりする際に役立ちます。7.2より前のバージョンでは、公式ガイドでは3つのスイッチすべてを有効にするように指示されています。

再起動する前にJSON構文を検証してください。その後、変更を反映させるためにドキュメントサーバーサービスを再起動してください。

sudo systemctl restart ds-converter ds-docservice ds-metrics

システムサービスを管理する権限を持つアカウントでコマンドを実行してください。Windows の場合、設定ファイルは です%ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json。Linux コマンドの代わりに、公式ガイドに記載されている Windows の再起動手順に従ってください。

生成された設定ファイルを編集せずにDockerを設定する

公式のドキュメントサーバーDockerイメージの場合、コンテナ環境変数を使用してJWTを設定します。公式ガイドでは、生成されたJWTを手動で変更すると、local.jsonコンテナの再起動時に元に戻ってしまう可能性があると警告しています。コンテナ作成コマンドまたはComposeサービスでJWTJWT_ENABLED=trueとJWTを設定しJWT_SECRET、コンテナを再作成して環境を有効にします。JWTは保護された環境ファイルまたはシークレットマネージャに保存し、そのファイルのアクセス許可を制限してください。バージョン管理にコミットすることは避けてください。

services:
  onlyoffice:
    image: onlyoffice/documentserver:YOUR_PINNED_TAG
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: ${ONLYOFFICE_JWT_SECRET}

ONLYOFFICE_JWT_SECRETデプロイ環境または保護ファイルで定義します.env。 に依存するのではなく、テスト済みのイメージタグを固定しlatest、実行する正確なタグについてはドキュメントを確認してください。環境値を変更した後は、通常のデプロイプロセスを使用してコンテナを再作成します。単純な再起動では、古い環境がそのまま残る場合があります。

コネクタを更新して秘密を保護します

ONLYOFFICE Docsに接続するプラットフォーム（Nextcloudなど、サポートされているコネクタ）で統合設定を開きます。同じJWTシークレットをシークレットキーフィールドに入力して保存します。また、設定済みのドキュメントサーバーURLと、コネクタが公開している場合は認証ヘッダーも確認してください。ONLYOFFICE Docsのデフォルトのヘッダーは です。Authorization両方の側で同じ代替ヘッダーを使用するように設定されている場合にのみ変更してください。

シークレットの不一致は、ドキュメントを開いたり保存したりする際に、無効なトークンまたは認証エラーとして発生することがよくあります。また、ロードバランサーの背後にある Docs ノードのうち 1 つだけが更新された場合にも、不一致が発生する可能性があります。複数のノードを運用している場合は、トラフィックを送信する前に、すべてのノードで同じシークレットとトークンの設定を同期してください。変更は段階的に展開してください。Docs とコネクタを同時に更新し、移行中は古い値で署名された既存のエディターセッションやリクエストが失敗する可能性があることを想定してください。

秘密情報を読み取ることができる人は誰でも、サーバーが受け入れる可能性のあるトークンを作成できます。設定ファイルとデプロイメント変数へのアクセスを制限し、コネクタとDocs間の接続には暗号化されたトランスポートを使用し、秘密情報が漏洩した可能性がある場合は、秘密情報をローテーションしてください。ローテーションには、すべてのDocsノードとコネクタを新しい値に更新する必要があります。チェックイン済みのファイルやログに古い認証情報を残さないでください。

設定を確認してください

• 設定変更後、Docsサービスまたはコンテナが実行されていることを確認してください。
• Docker環境では、sudo docker exec <container_name> sudo documentserver-jwt-status.shJWTの状態を確認するために以下のコマンドを実行してください。実際のコンテナ名を使用してください。このヘルパーはDocker向けにドキュメント化されています。すべてのパッケージインストールで利用できるとは限りません。
• 接続されたプラットフォーム経由でドキュメントを開き、簡単な編集を行い、保存します。エディタが開き、プラットフォームが保存された変更を認識していることを確認してください。
• 認証に失敗した場合は、サーバーとコネクタの秘密鍵を文字ごとに比較し、関連するすべてのトークンスイッチが有効になっていることを確認し、リクエストヘッダーの設定を検証してください。

公式設定ガイドは、サポートされている設定とバージョン動作に関する公式情報です。デプロイする正確なバージョンについては、ONLYOFFICEのJWT設定ドキュメントと公式のDockerインストールパラメータを参照してください。