ONLYOFFICE JWTシークレットキー認証の設定方法

ONLYOFFICEのJWT認証は、ドキュメントサーバーと連携アプリケーションが同じ秘密鍵を使用している場合にのみ機能します。現在のDocker環境では、JWT検証はデフォルトで有効になっています。安定した連携を実現するには、コンテナの自動生成値に頼るのではなく、独自の永続的な秘密鍵を設定しJWT_SECRET、Nextcloud、カスタムドキュメントマネージャー、またはONLYOFFICE Docsと通信するコネクタで同じ秘密鍵を設定してください。

この実用的なリファレンスでは、DockerとDocker Compose、署名付きエディタ構成、ヘッダー/ボディの動作、検証、ローテーション、および一般的なエラーなど、最も必要となる可能性の高い構成に焦点を当てています。これは、2026年10月に確認された最新のONLYOFFICEドキュメントに基づいています。

クイックリファレンス

ONLYOFFICE Docs 7.2以降、DockerデプロイメントではデフォルトでJWTが有効になり、シークレットを指定しない場合はランダムなシークレットが生成されます。公式のDockerドキュメントでは、自動生成されたシークレットは再起動やコンテナの再作成後に変更され、統合が壊れる可能性があると警告しています。実際のデプロイメントでは、明示的にシークレットを設定してください。詳細については、「ONLYOFFICE DocsのJWTの設定」および公式のDockerインストールガイドを参照してください。

1. ONLYOFFICEコンテナとデプロイ方法を特定する

Dockerホストの場合、まずは以下から始めます。

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
docker images | grep onlyoffice

インスタンスがdocker runDocker Compose、コントロールパネル、またはその他のオーケストレーションレイヤーのいずれを使用して起動されたかを確認してください。コンテナを作成するソース構成を変更する必要があります。コンテナ内の生成ファイルを編集することは、永続的な解決策ではありません。

特にDockerに関しては、ONLYOFFICEは管理者に対し、JWTファイルを直接編集するのではなく、環境変数を使用するよう指示しています/etc/onlyoffice/documentserver/local.json。JWT値をそのファイル内で直接編集した場合、コンテナの再起動時にDockerの起動プロセスによってJWT値が復元または再生成される可能性があります。

2. 強力な秘密鍵を生成し、安全に保管する

便利なシェルコマンドは次のとおりです。

openssl rand -hex 32

これにより、64文字の16進数で表される32バイトのランダムなデータが生成されます。ONLYOFFICEはこの形式を厳密に要求するわけではありません。重要なのは、両者が同じ秘密情報を共有し、それが推測しにくいものであることです。

JWT_SECRETパスワードやAPI認証情報のように扱う：

• 公開のGitリポジトリにはコミットしないでください。
• ブラウザに配布されるフロントエンドJavaScriptには含めないでください。
• Compose環境ファイル、またはそれを含むシークレットストアへのアクセスを制限します。
• 本番環境とステージング環境など、異なる環境にはそれぞれ異なるシークレットを使用してください。

ONLYOFFICE の署名に関するドキュメントでは、トークンの署名はサーバー側で行う必要があると明示的に警告しています。これは、秘密情報を含むブラウザ側のコードがあると、秘密情報がユーザーに公開されてしまうためです。公式の例では HMAC-SHA256 ( HS256) を使用しています。ONLYOFFICE JWT 署名に関するドキュメントを参照してください。

3. Docker ComposeでJWTを設定する

Composeの最小限のサービスには以下が含まれます。

services:
  documentserver:
    image: onlyoffice/documentserver:latest
    restart: unless-stopped
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: "${ONLYOFFICE_JWT_SECRET}"
      JWT_HEADER: "Authorization"
      JWT_IN_BODY: "false"
    ports:
      - "8080:80"

可能な限り、実際の秘密情報はComposeファイルの外に保管してください。例えば、アクセス権限が制限された.envファイルに保存するなどです。

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

次に、そのファイルがバージョン管理から除外され、必要な管理者またはサービスアカウントのみが読み取り可能であることを確認してください。

ONLYOFFICE の公式Docker-DocumentServer リポジトリにはJWT_ENABLED、、、、およびに関するドキュメントがあります。現在の Docker 起動コードではJWT_SECRET、JWT 検証がデフォルトで有効になっており、デフォルトのヘッダーとしてが使用され、明示的なシークレットが指定されていない場合はランダムなシークレットが生成されます。JWT_HEADERJWT_IN_BODYAuthorization

4. 新しい環境が適用されるようにコンテナを再作成します。

作曲の場合：

docker compose up -d --force-recreate
docker compose ps

で作成されたコンテナの場合docker run、公式の JWT ガイドでは、管理者は古いコンテナを停止して削除し、JWT 環境変数を使用して新しいコンテナを作成するように指示しています。この操作中に、永続ボリュームやバインドマウントされたデータを削除しないでください。

シークレット自体を表示せずに、実行中のコンテナの環境を検査することもできます。

docker inspect onlyoffice-documentserver \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep '^JWT_' \
  | sed 's/^JWT_SECRET=.*/JWT_SECRET=[REDACTED]/'

コンテナ名が異なる場合は、onlyoffice-documentserverそれに応じて置き換えてください。

5. 統合設定で同じシークレットを設定します

これは最も見落とされがちな部分です。ONLYOFFICE DocsでJWTを有効にする際に、文書管理側の設定を行わないと、エディターのリクエストが拒否されます。コネクタまたはカスタムアプリケーションは、リクエストにまったく同じ秘密鍵で署名する必要があります。

Nextcloudの例

ONLYOFFICEのNextcloud設定で、ドキュメントサーバーで使用されているものと同じ秘密鍵を入力してください。ヘッダー名も一致させる必要があります。ONLYOFFICEの現在のNextcloud統合ドキュメントではjwt_secret、jwt_headerコネクタ設定として と が記載されており、 が通常のデフォルトヘッダーとして使用されています。公式のNextcloudコネクタドキュメントをAuthorization参照してください。

コネクタに「秘密鍵」、「JWTシークレット」などのラベルが付いたフィールドがある場合は、そこに2つ目の独立したシークレットを生成しないでください。同じシークレット値をコピーしてください。

6. カスタム統合の場合は、サーバー上でエディター構成全体に署名します。

カスタムアプリケーションの場合は、まずエディタ構成を作成し、バックエンドでその構成に署名してから、生成されたJWTを最上位tokenプロパティに割り当てます。

Node.jsの例：

import jwt from "jsonwebtoken";

const config = {
  documentType: "word",
  document: {
    fileType: "docx",
    key: "document-2026-001",
    title: "Project Plan.docx",
    url: "https://files.example.com/project-plan.docx"
  },
  editorConfig: {
    callbackUrl: "https://app.example.com/onlyoffice/callback"
  }
};

config.token = jwt.sign(config, process.env.ONLYOFFICE_JWT_SECRET, {
  algorithm: "HS256"
});

ONLYOFFICEのブラウザ署名に関するドキュメントによると、ファイルを開くためのトークンペイロードは、エディタの設定と同じ構造でなければなりません。バージョン7.1以降、この操作の検証に関わるパラメータセットは厳密に規制されているため、古い構造や不完全な構造に署名すると、エラーが発生することがよくあります。詳しくは「ブラウザトークン署名」を参照してください。

結果として渡される設定にはDocsAPI.DocEditorトークンが含まれています。

new DocsAPI.DocEditor("placeholder", config);

公式APIリファレンスでは、config.tokenONLYOFFICE Docsがエディター構成を検証するために使用する暗号化された署名として定義されています。

7. ヘッダートークンとボディトークンの違いを理解する

ONLYOFFICEにおけるJWTは、ブラウザエディタの設定だけでなく、コマンド、変換、コールバックなどのサービス間通信にも使用されます。

ONLYOFFICEは、リクエストトークンを本文とヘッダーの両方でサポートしています。セキュリティに関するFAQでは、ヘッダーの長さがサーバー固有の制限に達する可能性があるため、該当する受信リクエストには本文トークンの使用を推奨しています。Docs 7.1以降では、受信本文トークンが存在する場合はそれが優先され、存在しない場合はヘッダートークンが使用されます。送信側では両方を送信できます。ONLYOFFICEのリクエストトークンに関するドキュメントを参照してください。

Docker変数のJWT_IN_BODYデフォルト値はfalseなので、存在するからといって安易に有効にしないでください。統合設計でボディトークンの送信と検証を一貫して行う必要がある場合にのみ変更してください。

8. 実際の編集者からのリクエストでテストする

有用な検証手順は次のとおりです。

1. 実際のシステム連携を通じてドキュメントを開きます。
2. エディタがトークンエラーなしで読み込まれることを確認してください。
3. 少し修正してください。
4. エディタを閉じるか、通常の保存処理を実行してください。
5. ストレージアプリケーションがコールバックを受信し、受け入れることを確認します。

Document Serverのウェルカムページが正常に表示されたとしても、2つのアプリケーション間でJWTが正しく設定されているとは限りません。JWTエラーは、統合処理がエディタの設定、コマンド、変換リクエスト、またはコールバックを送信したときにのみ発生することがよくあります。

公式のセキュリティ概要では、想定される動作について説明しています。ONLYOFFICEはトークンを検証し、署名付きペイロード値を使用します。検証が必要な時点でトークンが存在しない場合、または無効な場合は、リクエストは拒否されます。ONLYOFFICEドキュメントのセキュリティ概要を参照してください。

9. 認証が失敗した場合は、JWT の状態とログを確認してください。

現在のDocker起動コードは、管理者にJWTステータスヘルパーを参照するように指示しています。正しいコンテナ名を指定して、以下を実行してください。

docker exec onlyoffice-documentserver \
  sudo documentserver-jwt-status.sh

ログを検査することもできます。

docker logs --tail 200 onlyoffice-documentserver
docker exec onlyoffice-documentserver \
  find /var/log/onlyoffice/documentserver -type f -maxdepth 3 -print

シークレットを変更した直後に統合が失敗した場合は、以下の項目を順番に比較してください。

• JWT_ENABLED再作成されたコンテナで実際に有効になっていますか？
• 統合では、大文字小文字や句読点を含め、まったく同じ秘密鍵が使用されますか？
• コネクタは同じJWTヘッダー名を使用しますか？
• カスタムエディタの場合、ブラウザに送信する設定オブジェクトと同じものに署名していますか？
• コールバックとコマンドリクエストも、必要に応じて署名および検証されていますか？
• シェルファイルまたはComposeファイルに保存されたシークレットが、環境変数展開によって切り捨てられたり、解釈されたり、置き換えられたりしましたか？

一般的な故障パターン

「無効なトークン」または「無効な署名」

最も可能性の高い原因は、秘密鍵の不一致、または検証対象のリクエストとは異なるペイロードで署名されたトークンです。関連する設定変更後は、トークンを再生成してください。ドキュメントに記載されているサンプルトークンは再利用しないでください。これらのサンプルはデモ用の秘密鍵で署名されており、ご使用のサーバーでは有効ではありません。

Dockerが再起動するまでは動作します

これは通常、デプロイメントが自動生成された JWT シークレットに依存していたことを意味します。ONLYOFFICE は、再起動またはコンテナの再作成後にランダムなシークレットが再生成される可能性があることを明示的に警告しています。JWT_SECRETご自身で設定し、統合にも同じ値を設定してください。

Nextcloudで接続エラーまたはトークンエラーが表示されます

まず、両側のシークレットとヘッダーを確認してください。 ONLYOFFICE の Nextcloud ドキュメントでは、コネクタがjwt_headerDocument Server で構成されたヘッダーと一致することが必要です。 現在の通常のデフォルトは ですAuthorization。

大きな署名付きリクエストはHTTPエラーを返します

JWTがプロキシまたはWebサーバーのヘッダーサイズ制限を超えるヘッダーで送信されていないか確認してください。ONLYOFFICEのセキュリティに関するFAQでは、これが該当するPOSTリクエストでボディトークンが推奨される理由の一つであると説明されています。

JWTシークレットを安全にローテーションする

JWTシークレットのローテーションは調整が必要です。コネクタが古いシークレットで署名を続けるままドキュメントサーバーだけを変更してもメリットはありません。

シンプルなシングルインスタンス展開の場合：

1. 新しい秘密鍵を生成し、安全に保管してください。
2. アクティブな編集者に影響が出る可能性がある場合は、短いメンテナンス期間を設けてください。
3. 統合のシークレットとドキュメントサーバーのシークレットを、JWT_SECRET連携した変更として更新してください。
4. ドキュメントサーバーコンテナを再作成します。
5. テスト文書を開き、編集して保存します。
6. サービスを通常使用に戻す前に、コールバックが正常に機能することを確認してください。

ロードバランサーの背後に複数のドキュメントサーバーインスタンスがある場合、同じ統合機能を提供するすべてのインスタンスは、変更時に互換性のあるJWT構成が必要です。ノードをその都度切り替えるのではなく、計画的に展開してください。

生産チェックリスト

• 永続的な秘密情報：明示的に設定してくださいJWT_SECRET。ランダムに生成された値に依存しないでください。
• どこでも同じ秘密：ドキュメントサーバーと統合システムは、同一の値を共有しなければならない。
• バックエンド署名：フロントエンド／ブラウザのコードに秘密鍵を公開してはいけません。
• HS256: ONLYOFFICEの公式コードサンプルに示されているHMAC-SHA256方式を使用してください。
• ヘッダーの合意:コネクタが名前付きヘッダーを介して JWT を送信する場合、その名前はドキュメント サーバーと一致している必要があります。
• コンテナの再作成： Docker環境の変更には、コンテナの再作成が必要です。
• 実際の統合テスト：ファイルを開いて編集し、保存し、コールバックの動作を検証します。
• 秘密情報の保管：秘密情報は公開リポジトリやログには保存しない。
• 制御された回転：両側を同時に更新し、メンテナンスを終了する前に確認してください。

結論

Docker ベースの ONLYOFFICE インストールの場合、永続的な構成は簡単です。強力なシークレットを生成し、コンテナ環境変数で設定しJWT_ENABLED=true、JWT_SECRETコンテナを再作成し、コネクタまたはバックエンドでまったく同じシークレットを設定します。カスタム統合では、エディタ構成とサービス要求をサーバー上で HS256 で署名する必要があり、ブラウザコードで署名してはなりません。

再起動後にJWTが突然機能しなくなった場合は、秘密鍵が永続化されたことがあるかどうかを確認してください。設定変更直後に機能しなくなった場合は、他の原因を探す前に、秘密鍵、ヘッダー、署名付きペイロードを比較してください。これらの3つのチェックを行うことで、認証を弱めることなく、JWTの設定ミスの大半を解決できます。