Résoudre l'erreur « Jeton non valide » d'ONLYOFFICE dans Nextcloud

Si Nextcloud signale « Jeton invalide » lors de la connexion à ONLYOFFICE Docs, assurez-vous que le secret JWT du connecteur corresponde à celui utilisé par le serveur de documents. Dans ONLYOFFICE Docs 7.2 et versions ultérieures, la validation JWT est activée par défaut et un secret est généré automatiquement ; modifier uniquement le paramètre Nextcloud ou le fichier de configuration généré par un conteneur Docker peut entraîner une désynchronisation entre les deux systèmes.

Laissez JWT activé. Commencez par identifier le secret actif et le type de déploiement, mettez à jour la configuration, puis exécutez le test de connexion du connecteur. Le test doit indiquer une connexion réussie ; l’ouverture d’un éditeur de navigateur ne garantit pas le bon fonctionnement du téléchargement des documents et des rappels.

Que vous indique ce message d'erreur ?

JWT (JSON Web Token) est un jeton signé utilisé pour vérifier la fiabilité des requêtes entre Nextcloud et ONLYOFFICE Docs. Le connecteur signe les requêtes avec son secret configuré, tandis que le serveur de documents les valide avec le sien. Si les secrets de signature diffèrent, la signature du jeton ne peut être validée et la requête est rejetée.

Les causes les plus fréquentes sont : un secret copié depuis une ancienne installation, un secret généré automatiquement et jamais saisi dans Nextcloud, une variable d’environnement Docker modifiée et non prise en compte lors de la recréation du conteneur, ou des valeurs de secret incohérentes dans la configuration du serveur de documents. Un en-tête JWT personnalisé peut également provoquer une incompatibilité si le connecteur et le serveur de documents n’utilisent pas le même nom d’en-tête.

Cet article traite des problèmes de compatibilité JWT. Si l'erreur indique que le serveur est inaccessible, que le certificat est invalide ou qu'un document ne peut être téléchargé, vérifiez séparément les adresses du serveur, le certificat TLS et le chemin réseau entre Nextcloud et le serveur de documents. La correction du JWT ne résoudra pas ces problèmes.

1. Trouvez le secret actif du serveur de documents

Utilisez la configuration du serveur de documents en cours d'exécution. Ne présumez pas qu'un secret conservé d'un conteneur ou serveur précédent soit toujours actif.

• Linux : inspecter /etc/onlyoffice/documentserver/local.json.
• Windows : inspecter %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json.
• Docker : lire le secret depuis le conteneur en cours d’exécution. L’image officielle prend également en charge la lecture du secret de session avec cette commande :

sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

Remplacez <containerID>par le nom ou l'identifiant réel du conteneur. Considérez la valeur renvoyée comme une information d'identification : ne la collez pas dans les forums d'assistance, les captures d'écran ou les journaux publics.

Dans local.json, comparez les valeurs de services.CoAuthoring.secret.inbox.string, services.CoAuthoring.secret.outbox.string, et services.CoAuthoring.secret.session.string. Elles doivent toutes être identiques pour cette configuration standard. Vérifiez également que la validation du jeton est activée pour le navigateur, la boîte de réception des requêtes et la boîte d'envoi des requêtes. Les versions de la documentation antérieures à la version 7.2 nécessitent l'activation explicite de la validation du jeton ; les versions ultérieures l'activent par défaut.

2. Mettez à jour le connecteur ONLYOFFICE de Nextcloud

1. Connectez-vous en tant qu'administrateur Nextcloud et ouvrez Paramètres > Administration > ONLYOFFICE .
2. Dans les paramètres du serveur, saisissez la clé secrète exacte figurant sur le serveur de documents en cours d'exécution dans le champ « Clé secrète » . Évitez les espaces en début et en fin de ligne et n'ajoutez pas de guillemets, sauf s'ils font partie intégrante de la clé secrète.
3. Vérifiez le paramètre d'en-tête JWT si votre déploiement utilise un en-tête personnalisé. Le jwt_headerparamètre du connecteur et l'en-tête de jeton configuré sur Document Server doivent correspondre. Si vous n'avez pas intentionnellement personnalisé l'en-tête, ne le modifiez pas dans le cadre de cette réparation.
4. Enregistrez les paramètres. Laissez JWT activé des deux côtés.

Le paramètre de connecteur documenté peut également être modifié à l'aide de la commande Nextcloud occdepuis le répertoire d'installation de Nextcloud :

sudo -u www-data php occ config:app:set onlyoffice jwt_secret --value='YOUR_SECRET'

Remplacez YOUR_SECRETpar la valeur réelle. L'utilisation des guillemets dans le shell permet de préserver la ponctuation, mais les secrets contenant une seule apostrophe nécessitent une méthode plus sûre que leur insertion directe dans la ligne de commande. Les arguments de la ligne de commande peuvent également être visibles lors de l'inspection des processus privilégiés ou dans l'historique du shell. Privilégiez l'interface d'administration lorsque cela est possible, puis vérifiez la valeur stockée sans l'exposer.

3. Appliquez la modification correctement à votre installation.

Docker ou Docker Compose

Pour les déploiements Docker, configurez JWT via l'environnement du conteneur plutôt que de modifier manuellement le fichier généré automatiquement local.json. Définissez le même secret dans la définition du service du serveur de documents :

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

Après avoir modifié le fichier Compose, recréez le conteneur du serveur de documents pour que les modifications soient prises en compte. Par exemple, depuis le répertoire contenant le fichier Compose :

docker compose up -d --force-recreate <documentserver-service>

Remplacez le nom du service par celui de votre fichier Compose. Un simple redémarrage ne met pas à jour les paramètres d'environnement d'un conteneur existant. Si vous utilisez docker runla commande `recreate`, recréez le conteneur avec les paramètres JWT_ENABLEDet JWT_SECRETles valeurs mis à jour, en conservant ses ports, volumes et autres options nécessaires. Ne supprimez pas un conteneur de production tant que vous n'avez pas validé ces paramètres et les points de montage de données persistants.

Au démarrage du conteneur, relisez son secret actif à l'aide de la commande ci-dessus et assurez-vous que sa valeur correspond toujours à celle de Nextcloud. Évitez de placer un secret de production dans un fichier Compose ou un dépôt de code source partagé publiquement.

Installation du package Linux ou Windows

Si vous définissez intentionnellement un secret personnalisé local.json, assurez-vous que les trois champs secrets correspondent et que les valeurs de validation des jetons requises sont activées. Appliquez la modification en redémarrant les services du serveur de documents concernés. Les instructions ONLYOFFICE actuelles mentionnent les étapes suivantes ds-convertersous Linux : redémarrage du serveur de documents, du serveur de documents ds-docserviceet ds-metricsdu serveur de documents. Les installations gérées par un autre superviseur de services peuvent nécessiter la méthode de redémarrage appropriée à leur configuration. Sous Windows, redémarrez les services ONLYOFFICE après avoir enregistré la configuration.

Une incohérence qui persiste après un redémarrage indique généralement qu'une configuration générée ou un environnement de déploiement remplace le fichier modifié. Pour Docker, déplacez la correction dans les variables d'environnement et recréez le conteneur. Pour les déploiements packagés, examinez la configuration active et la configuration de démarrage du service avant de modifier d'autres paramètres.

Vérifier la réparation

1. Dans le répertoire d'installation de Nextcloud, exécutez la vérification officielle du connecteur :

sudo -u www-data php occ onlyoffice:documentserver --check

Utilisez le compte serveur web approprié à votre installation s'il n'est pas déjà configuré www-data. La commande devrait indiquer une connexion réussie. Si elle signale toujours un jeton invalide, vérifiez que le secret actif du serveur de documents en cours d'exécution correspond exactement à celui de Nextcloud et que tout en-tête JWT personnalisé est conforme.

2. Ouvrez un petit document de test depuis Nextcloud avec ONLYOFFICE. Vérifiez que l'éditeur se charge, effectuez une modification mineure, enregistrez, fermez l'éditeur, puis rouvrez le fichier pour vérifier que la modification a bien été prise en compte.
3. Si la vérification signale une erreur de réseau ou de certificat, cessez de modifier les valeurs JWT. Vérifiez que Nextcloud peut accéder à l'adresse du serveur de documents et que ce dernier peut accéder à l'adresse de rappel de Nextcloud. Utilisez un certificat TLS de confiance lorsque cela est possible ; la désactivation de la vérification des certificats est une solution de contournement non sécurisée et ne résout pas le problème de la validation des jetons.

Ces vérifications permettent de s'assurer du bon fonctionnement de la connexion configurée et d'un chemin de sauvegarde de base. Elles ne garantissent pas la validité de chaque route de proxy inverse, configuration de stockage externe ou topologie multi-serveurs ; il est donc nécessaire de tester ces éléments séparément si votre déploiement les utilise.

Références officielles

• ONLYOFFICE : Intégration de Nextcloud et configuration JWT
• ONLYOFFICE : Configurer JWT pour le serveur de documents
• Connecteur ONLYOFFICE Nextcloud : options de configuration et commandes occ

Les détails de configuration ont été vérifiés par rapport à la documentation officielle ONLYOFFICE et au référentiel de connecteurs le 9 octobre 2026. Les libellés de l'interface utilisateur et la gestion des services peuvent varier selon le connecteur, le système d'exploitation et la méthode de déploiement.