Configurer les secrets JWT ONLYOFFICE sur le serveur et le connecteur

Utilisez systématiquement une seule et unique clé secrète JWT robuste : configurez-la dans ONLYOFFICE Docs, copiez cette même valeur dans les paramètres ONLYOFFICE de la plateforme connectée et laissez la validation JWT activée. Docs 7.2 et versions ultérieures activent JWT par défaut et génèrent une clé secrète automatiquement ; toute modification de cette clé secrète implique la mise à jour de chaque intégration. La méthode exacte côté serveur dépend du système d’exploitation de Docs : package Linux ou conteneur Docker.

Qu'est-ce qui doit correspondre ?

JWT (JSON Web Token) permet à ONLYOFFICE Docs de vérifier les requêtes signées. La plateforme documentaire et OnlyOffice Docs doivent utiliser le même secret et des paramètres d'en-tête compatibles. Le serveur utilise des paramètres de jeton distincts pour la configuration du navigateur et les requêtes de service entrantes et sortantes ; les valeurs secrètes partagées protègent ces échanges. Ne publiez pas ce secret sur une page web publique, dans un fichier JavaScript côté client, dans un ticket d'assistance ou dans un dépôt de code source accessible publiquement.

Avant toute modification, identifiez votre type de déploiement et notez l'URL de la documentation utilisée par votre connecteur. Générez un secret long et complexe à l'aide d'un gestionnaire de mots de passe ou d'un générateur cryptographique sécurisé. Considérez-le comme une authentification et stockez-le dans un répertoire de configuration restreint.

Configurer une installation Linux

Pour une installation Linux basée sur un paquet, modifiez le fichier /etc/onlyoffice/documentserver/local.json. Conservez les paramètres existants : fusionnez les clés suivantes dans le fichier JSON existant plutôt que de remplacer l’intégralité du fichier. L’exemple illustre la structure de validation des jetons et les trois emplacements secrets correspondants décrits dans le guide de configuration officiel :

{
  "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" }
      }
    }
  }
}

Remplacez chaque espace réservé par la même valeur secrète. Ne collez pas l'espace réservé d'exemple. Les options `--jw` browser, inbox`--jw` et outbox`--jw` sont indépendantes ; n'en activer qu'une seule n'active pas la validation de toutes les requêtes. Dans la documentation 7.2 et les versions ultérieures, JWT est activé par défaut, mais vérifier explicitement ces paramètres est utile lors de l'audit d'une configuration existante ou de l'harmonisation du comportement entre les nœuds. Pour les versions antérieures à 7.2, le guide officiel recommande d'activer les trois options.

Vérifiez la syntaxe JSON avant de redémarrer. Redémarrez ensuite les services du serveur de documents pour que les modifications soient prises en compte.

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

Exécutez la commande avec un compte disposant des droits d'administration des services système. Sous Windows, le fichier de configuration se trouve ici%ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json ; suivez les instructions de redémarrage Windows du guide officiel au lieu de la commande Linux.

Configurer Docker sans modifier la configuration générée

Pour l'image Docker officielle du serveur de documents, configurez le JWT via les variables d'environnement du conteneur. Le guide officiel avertit que toute modification manuelle du JWT généré local.jsonpeut être annulée au redémarrage du conteneur. Configurez JWT_ENABLED=truele JWT JWT_SECRETdans la commande de création du conteneur ou le service Compose, puis recréez le conteneur pour que les modifications soient prises en compte. Conservez le secret dans un fichier d'environnement protégé ou un gestionnaire de secrets et limitez les permissions de ce fichier ; évitez de l'intégrer à un système de contrôle de version.

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

Définissez les variables ONLYOFFICE_JWT_SECRETd'environnement dans le fichier de déploiement ou le fichier protégé .env. Utilisez une étiquette d'image testée plutôt que de vous fier à une valeur quelconque latestet consultez la documentation relative à l'étiquette exacte que vous utilisez. Après avoir modifié les variables d'environnement, recréez le conteneur en suivant votre procédure de déploiement habituelle. Un simple redémarrage peut laisser l'ancien environnement en place.

Mettez à jour le connecteur et protégez le secret

Ouvrez les paramètres d'intégration de la plateforme connectée à ONLYOFFICE Docs, telle que Nextcloud ou un autre connecteur compatible. Saisissez la même clé secrète JWT dans le champ correspondant et enregistrez. Vérifiez également l'URL du serveur de documents configurée et, si le connecteur l'expose, l'en-tête d'autorisation. L'en-tête par défaut dans ONLYOFFICE Docs estAuthorization ; ne le modifiez que si les deux plateformes sont configurées pour utiliser la même alternative.

Une incohérence de clé secrète se manifeste généralement par une erreur de jeton invalide ou d'autorisation lors de l'ouverture ou de l'enregistrement d'un document. Ce problème peut également survenir lorsqu'un seul nœud Docs, derrière un équilibreur de charge, a été mis à jour. Si vous utilisez plusieurs nœuds, synchronisez les mêmes paramètres de clé secrète et de jeton sur l'ensemble des nœuds avant d'y acheminer le trafic. Déployez les modifications progressivement : mettez à jour Docs et le connecteur simultanément, et prévoyez que les sessions d'édition ou les requêtes existantes signées avec l'ancienne valeur échoueront pendant la transition.

Quiconque connaît le secret peut créer des jetons que le serveur peut accepter. Limitez l'accès aux fichiers de configuration et aux variables de déploiement, utilisez un protocole de transport chiffré pour la connexion entre le connecteur et la documentation, et changez le secret s'il a été divulgué. Le changement nécessite la mise à jour de tous les nœuds de documentation et du connecteur avec la nouvelle valeur ; ne conservez pas d'anciennes informations d'identification dans les fichiers archivés ou les journaux.

Vérifier la configuration

• Vérifiez que le service ou le conteneur Docs est en cours d'exécution après la modification de la configuration.
• Pour un déploiement Docker, exécutez la commande sudo docker exec <container_name> sudo documentserver-jwt-status.shpermettant d'inspecter l'état du JWT. Utilisez le nom réel du conteneur. Cet outil est documenté pour Docker ; ne présumez pas qu'il soit disponible dans toutes les installations de paquets.
• Ouvrez un document via la plateforme connectée, effectuez une modification mineure et sans conséquence, puis enregistrez-le. Vérifiez que l'éditeur s'ouvre bien et que la plateforme reçoit la modification enregistrée.
• En cas d'échec de l'authentification, comparez caractère par caractère le secret du serveur et celui du connecteur, vérifiez que tous les commutateurs de jeton pertinents sont activés et vérifiez la configuration de l'en-tête de la requête.

Le guide de configuration officiel fait foi pour les paramètres pris en charge et le comportement des versions. Consultez la documentation de configuration JWT d'ONLYOFFICE et les paramètres d'installation Docker officiels pour connaître la version exacte que vous déployez.