Comment configurer l'authentification par clé secrète JWT d'ONLYOFFICE

L'authentification JWT d'ONLYOFFICE fonctionne uniquement si le serveur de documents et l'application intégrée utilisent la même clé secrète. Sur les déploiements Docker actuels, la validation JWT est activée par défaut. Pour une intégration stable, définissez votre propre clé secrète persistante JWT_SECRETau lieu d'utiliser la valeur générée automatiquement par le conteneur, puis configurez cette même clé dans Nextcloud, votre gestionnaire de documents personnalisé ou tout autre connecteur communiquant avec ONLYOFFICE Docs.

Ce guide pratique se concentre sur la configuration dont vous aurez probablement le plus besoin : Docker et Docker Compose, les intégrations personnalisées qui signent la configuration de l’éditeur, le comportement des en-têtes et du corps des fichiers, la vérification, la rotation et les erreurs courantes. Il est basé sur la documentation ONLYOFFICE mise à jour en octobre 2026.

Guide de référence rapide

À partir de ONLYOFFICE Docs 7.2, les déploiements Docker activent JWT par défaut et génèrent un secret aléatoire si vous n'en fournissez pas. La documentation officielle de Docker indique qu'un secret généré automatiquement peut changer après un redémarrage ou la recréation d'un conteneur, ce qui peut perturber les intégrations. Il est donc recommandé de définir un secret explicite pour tout déploiement réel. Consultez la section « Configuration de JWT pour ONLYOFFICE Docs » et le guide d'installation officiel de Docker .

1. Identifier le conteneur ONLYOFFICE et la méthode de déploiement

Pour un hôte Docker, commencez par :

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

Déterminez si l'instance a été lancée avec docker runDocker Compose, un panneau de contrôle ou une autre couche d'orchestration. Vous devez modifier la configuration source qui crée le conteneur. Modifier un fichier généré à l'intérieur du conteneur n'est pas une solution durable.

Concernant Docker, ONLYOFFICE recommande aux administrateurs d'utiliser les variables d'environnement plutôt que de modifier manuellement les fichiers de configuration /etc/onlyoffice/documentserver/local.json. Si vous modifiez directement les valeurs JWT dans ce fichier, le processus de démarrage de Docker peut les restaurer ou les régénérer lors du redémarrage du conteneur.

2. Créez un secret robuste et conservez-le en toute sécurité.

Une commande shell pratique est :

openssl rand -hex 32

Cela produit 32 octets aléatoires représentés par 64 caractères hexadécimaux. ONLYOFFICE n'exige pas ce format précis ; l'important est que les deux parties partagent le même secret et qu'il soit difficile à deviner.

À traiter JWT_SECRETcomme un mot de passe ou un identifiant API :

• Ne l'enregistrez pas dans un dépôt Git public.
• Ne l'intégrez pas dans le JavaScript frontend distribué aux navigateurs.
• Limiter l'accès au fichier d'environnement Compose ou au magasin de secrets qui le contient.
• Utilisez un secret différent pour chaque environnement, comme la production et la préproduction.

La documentation d'ONLYOFFICE relative aux signatures indique clairement que la signature des jetons doit être effectuée côté serveur, car tout code côté navigateur contenant le secret l'expose aux utilisateurs. Les exemples officiels utilisent HMAC-SHA256 HS256. Consultez la documentation d'ONLYOFFICE sur les signatures JWT .

3. Configurer JWT dans Docker Compose

Un service Compose minimal peut inclure :

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"

Dans la mesure du possible, conservez le secret en dehors du fichier Compose. Par exemple, placez-le dans un .envfichier dont l'accès est restreint.

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

Ensuite, assurez-vous que ce fichier est exclu du contrôle de version et qu'il ne soit lisible que par les administrateurs ou le compte de service qui en a besoin.

Le dépôt officiel ONLYOFFICE Docker-DocumentServer documente JWT_ENABLED, JWT_SECRET, JWT_HEADER, et JWT_IN_BODY. Le code de démarrage Docker actuel active par défaut la validation JWT, utilise Authorizationcomme en-tête par défaut et génère un secret aléatoire lorsqu'aucun secret explicite n'est fourni.

4. Recréez le conteneur pour que le nouvel environnement soit appliqué.

Pour composer :

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

Pour un conteneur créé initialement avec docker runJWT, le guide officiel recommande aux administrateurs d'arrêter et de supprimer l'ancien conteneur, puis d'en créer un nouveau avec les variables d'environnement JWT. Il est important de ne pas supprimer les volumes persistants ni les données montées par liaison lors de cette opération.

Vous pouvez également inspecter l'environnement du conteneur en cours d'exécution sans afficher le secret lui-même :

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

Si le nom du conteneur diffère, remplacez- onlyoffice-documentserverle en conséquence.

5. Configurez le même secret dans l'intégration.

C’est l’étape la plus souvent négligée. Activer JWT sur ONLYOFFICE Docs sans configurer la gestion documentaire entraîne le rejet des requêtes de l’éditeur. Le connecteur ou l’application personnalisée doit signer les requêtes avec exactement le même secret.

Exemple Nextcloud

Dans les paramètres ONLYOFFICE pour Nextcloud, saisissez la même clé secrète que celle utilisée par le serveur de documents. Le nom de l'en-tête doit également correspondre. La documentation actuelle d'intégration Nextcloud d'ONLYOFFICE indique jwt_secretque jwt_headerles paramètres du connecteur sont définis, avec Authorizationl'en-tête par défaut. Consultez la documentation officielle du connecteur Nextcloud .

Si votre connecteur comporte un champ intitulé « Clé secrète », « Secret JWT » ou similaire, ne générez pas de deuxième secret indépendant à cet emplacement. Copiez la même valeur secrète.

6. Pour une intégration personnalisée, signez la configuration complète de l'éditeur sur le serveur.

tokenPour une application personnalisée, commencez par créer la configuration de l'éditeur, signez cette configuration sur le serveur, puis affectez le JWT résultant à la propriété de niveau supérieur .

Exemple 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"
});

La documentation d'ONLYOFFICE relative à la signature de fichiers par navigateur indique que le jeton utilisé pour ouvrir un fichier doit avoir la même structure que la configuration de l'éditeur. Depuis la version 7.1, l'ensemble des paramètres de validation est strictement réglementé pour cette opération ; par conséquent, la signature d'une structure obsolète ou incomplète est une cause fréquente d'échec. Voir Signature de jetons par navigateur .

La configuration résultante transmise DocsAPI.DocEditorcontient le jeton :

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

La documentation officielle de l'API définit config.tokencette signature chiffrée comme étant celle utilisée par ONLYOFFICE Docs pour valider la configuration de l'éditeur.

7. Comprendre la différence entre les jetons d'en-tête et les jetons de corps

Dans ONLYOFFICE, JWT ne se limite pas à la configuration de l'éditeur de navigateur. Il est également utilisé pour les requêtes entre services, telles que les commandes, les conversions et les rappels.

ONLYOFFICE prend en charge les jetons de requête dans le corps et l'en-tête. Sa FAQ sur la sécurité indique que la longueur des en-têtes peut être limitée par le serveur ; il est donc recommandé d'utiliser les jetons dans le corps des requêtes entrantes concernées. À partir de la version 7.1 de la documentation, le jeton du corps entrant est prioritaire ; sinon, c'est le jeton d'en-tête qui est utilisé. Le serveur peut envoyer les deux. Consultez la documentation ONLYOFFICE relative aux jetons de requête .

La variable Docker JWT_IN_BODYest définie par défaut sur false, il est donc inutile de l'activer simplement parce qu'elle existe. Modifiez-la uniquement si votre intégration est conçue pour envoyer et valider les jetons du corps de manière cohérente.

8. Test avec une véritable demande d'éditeur

Une séquence de validation utile est :

1. Ouvrez un document via votre intégration réelle.
2. Vérifiez que l'éditeur se charge sans erreurs de jeton.
3. Apportez une petite modification.
4. Fermez l'éditeur ou déclenchez la procédure de sauvegarde normale.
5. Vérifiez que l'application de stockage reçoit et accepte le rappel.

L'affichage correct de la page d'accueil du serveur de documents ne garantit pas la configuration correcte de JWT entre les deux applications. Les erreurs JWT apparaissent souvent uniquement lorsque l'intégration envoie la configuration de l'éditeur, une commande, une requête de conversion ou un rappel.

La présentation officielle de sécurité explique le comportement attendu : ONLYOFFICE valide un jeton et utilise les valeurs de la charge utile signées ; si le jeton est manquant ou invalide lors de la validation requise, la requête est rejetée. Voir la présentation de sécurité de la documentation ONLYOFFICE .

9. Vérifiez l'état et les journaux JWT en cas d'échec d'authentification.

Le code de démarrage Docker actuel redirige les administrateurs vers l'utilitaire d'état JWT. Avec le nom de conteneur correct, exécutez :

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

Vous pouvez également consulter les journaux :

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

Si une intégration échoue immédiatement après la modification du secret, comparez les éléments suivants dans l'ordre :

• Est -ce JWT_ENABLEDréellement activé dans le conteneur recréé ?
• L'intégration utilise-t-elle exactement le même secret, y compris la mise en majuscules et la ponctuation ?
• Le connecteur utilise-t-il le même nom d'en-tête JWT ?
• Pour un éditeur personnalisé, signez-vous le même objet de configuration que celui que vous envoyez au navigateur ?
• Les rappels et les requêtes de commandes sont-ils également signés et validés comme requis ?
• Un secret stocké dans un fichier shell ou Compose a-t-il été tronqué, interprété ou remplacé par l'expansion d'une variable d'environnement ?

Modèles de défaillance courants

« Jeton invalide » ou « Signature invalide »

La cause la plus probable est une incompatibilité de clé secrète ou un jeton signé avec une charge utile différente de celle de la requête en cours de validation. Régénérez le jeton après toute modification de configuration pertinente. N'utilisez pas les exemples de jetons de la documentation ; ces exemples sont signés avec des clés secrètes de démonstration et ne sont pas valides pour votre serveur.

Cela fonctionne jusqu'au redémarrage de Docker.

Cela signifie généralement que le déploiement s'appuyait sur le secret JWT généré automatiquement. ONLYOFFICE avertit explicitement qu'un secret aléatoire peut être régénéré après un redémarrage ou la recréation du conteneur. Configurez JWT_SECRETvous-même ce secret et utilisez la même valeur dans l'intégration.

Nextcloud affiche une erreur de connexion ou de jeton

Vérifiez d'abord le secret et l'en-tête des deux côtés. La documentation Nextcloud d'ONLYOFFICE exige que l'en-tête du connecteur jwt_headercorresponde à celui configuré dans Document Server. La valeur par défaut actuelle estAuthorization : .

Une requête signée de grande taille renvoie une erreur HTTP

Vérifiez si le jeton JWT est envoyé dans un en-tête dont la taille dépasse la limite imposée par le proxy ou le serveur web. La FAQ sécurité d'ONLYOFFICE explique que c'est l'une des raisons pour lesquelles les jetons de corps sont préférables pour les requêtes POST concernées.

Rotation du secret JWT en toute sécurité

La rotation des clés secrètes JWT doit être coordonnée. Il est inutile de modifier uniquement le serveur de documents si le connecteur continue de signer avec l'ancienne clé secrète.

Pour un déploiement simple à instance unique :

1. Générez le nouveau secret et stockez-le en lieu sûr.
2. Planifiez une courte fenêtre de maintenance si des éditeurs actifs risquent d'être affectés.
3. Mettez à jour le secret de l'intégration et celui du serveur de documents JWT_SECRETen une seule modification coordonnée.
4. Recréez le conteneur du serveur de documents.
5. Ouvrez, modifiez et enregistrez un document de test.
6. Vérifiez que les fonctions de rappel fonctionnent avant de remettre le service en service normal.

Pour plusieurs instances de serveur de documents derrière un équilibreur de charge, toutes les instances assurant la même intégration doivent avoir une configuration JWT compatible lors de la modification. Il est préférable de planifier le déploiement plutôt que de faire pivoter un nœud au cas par cas.

Liste de contrôle de production

• Secret persistant : à définir JWT_SECRETexplicitement ; ne pas se fier à une valeur générée aléatoirement.
• Le même secret partout : Document Server et l’intégration doivent partager la même valeur.
• Signature côté serveur : ne jamais exposer le secret dans le code côté client/navigateur.
• HS256 : utilisez l’approche HMAC-SHA256 présentée dans les exemples de code officiels d’ONLYOFFICE.
• Accord d'en-tête : si un connecteur envoie un JWT via un en-tête nommé, ce nom doit correspondre à celui du serveur de documents.
• Recréation du conteneur : les modifications de l’environnement Docker nécessitent la recréation du conteneur.
• Test d'intégration réel : ouvrir, modifier, enregistrer et vérifier le comportement du rappel.
• Stockage des données confidentielles : ne stockez pas les données confidentielles dans des répertoires et des journaux publics.
• Rotation contrôlée : mettre à jour les deux côtés simultanément et vérifier avant de terminer la maintenance.

En résumé

Pour une installation ONLYOFFICE basée sur Docker, la configuration durable est simple : générez un secret fort, définissez JWT_ENABLED=true-le JWT_SECRETvia les variables d’environnement du conteneur, recréez le conteneur et configurez exactement le même secret dans votre connecteur ou votre backend. Les intégrations personnalisées doivent signer la configuration de l’éditeur et les requêtes de service sur le serveur avec HS256, jamais dans le code du navigateur.

Si le JWT cesse soudainement de fonctionner après un redémarrage, vérifiez si le secret a été rendu persistant. S'il échoue immédiatement après une modification de configuration, comparez le secret, l'en-tête et la charge utile signée avant d'explorer d'autres pistes. Ces trois vérifications permettent de corriger la plupart des erreurs de configuration JWT sans compromettre l'authentification.