Résolution de l'erreur « Jeton non valide » dans l'intégration ONLYOFFICE Nextcloud

Le message ONLYOFFICE « Jeton non valide » signifie généralement que les deux parties de l'intégration n'utilisent pas le même jeton Web JSON (JWT). Dans une configuration Nextcloud, il est important de noter qu'il existe plusieurs chemins d'accès au jeton : la configuration de l'éditeur envoyée au navigateur, les requêtes entrantes vers ONLYOFFICE Docs et les requêtes sortantes, telles que les rappels vers Nextcloud. Une erreur sur l'un de ces chemins peut être perçue de la même manière par l'utilisateur.

Un détail important à retenir avant de modifier vos paramètres : JWT est activé par défaut dans ONLYOFFICE Docs depuis la version 7.2 , et le serveur de documents peut générer automatiquement un secret. Par conséquent, un ancien tutoriel conseillant de « laisser JWT désactivé » n’est plus adapté à une installation moderne. ONLYOFFICE recommande désormais de configurer votre propre secret et de l’utiliser dans le connecteur. Consultez le guide de configuration JWT d’ONLYOFFICE .

Guide rapide : que vérifier en premier

1. Confirmer que le secret partagé est bien le même

La validation des jetons JWT repose sur un secret partagé. ONLYOFFICE Docs signe les jetons avec ce secret, et le destinataire vérifie la signature en utilisant la même valeur. Une différence d'un seul caractère, un espace en fin de chaîne, une ancienne variable d'environnement ou un secret Docker régénéré suffisent à faire échouer la validation d'un jeton pourtant valide en apparence.

Sur Nextcloud, le connecteur prend en charge ce jwt_secretparamètre. Le connecteur officiel fournit également une occinterface de configuration, vous permettant ainsi de vérifier la valeur réellement utilisée par Nextcloud au lieu de vous fier à un fichier de configuration supposé actif. Les paramètres actuels du connecteur sont documentés dans le fichier README du connecteur ONLYOFFICE Nextcloud officiel .

sudo -u www-data php occ config:app:get onlyoffice jwt_secret
sudo -u www-data php occ config:app:get onlyoffice jwt_header

Ne collez pas le secret dans les tickets d'assistance, les captures d'écran, l'historique de la console partagé avec d'autres personnes ou les rapports de problèmes publics. Comparez-le localement.

Pour une installation native Linux d'ONLYOFFICE Docs, le fichier de configuration pris en charge est :

/etc/onlyoffice/documentserver/local.json

ONLYOFFICE documente séparément les paramètres des jetons du navigateur, de la boîte de réception et de la boîte d'envoi. Les valeurs secrètes utilisées pour la validation doivent correspondre à la configuration de votre connecteur. Ne les modifiez pasdefault.json ; ONLYOFFICE avertit explicitement que les valeurs par défaut peuvent être écrasées lors d'un redémarrage ou d'une mise à jour. À utiliser local.jsonpour les installations de packages.

Si vous exécutez ONLYOFFICE Docs dans Docker

Utilisez les variables d'environnement Docker plutôt que de les modifier manuellement local.jsondans le conteneur. ONLYOFFICE indique que Docker peut régénérer la configuration JWT au démarrage ; son image officielle prend en charge les formats `JWT.NET` JWT_ENABLED, JWT_SECRET` JWT_HEADERJWT.NET` et `JWT.NET` JWT_IN_BODY. La documentation actuelle de l'image Docker mentionne ` AuthorizationJWT.NET` comme en-tête JWT par défaut. Consultez le dépôt officiel Docker DocumentServer .

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=replace-with-a-long-random-secret
  - JWT_HEADER=Authorization

Après avoir modifié les variables d'environnement Docker, recréez le conteneur pour que le service en cours d'exécution les prenne en compte. La simple modification d'un fichier Compose, sans recréer le conteneur, ne modifie pas son environnement existant.

2. Assurez-vous que l'en-tête JWT corresponde exactement.

On croit souvent à tort que le nom de l'en-tête est purement esthétique. Ce n'est pas le cas. ONLYOFFICE Docs propose des en-têtes de jetons de boîte de réception et d'envoi configurables, et le connecteur Nextcloud dispose d'un jwt_headerparamètre correspondant. Ces en-têtes doivent décrire le même chemin de requête.

La documentation actuelle de l'API ONLYOFFICE indique Authorizationque le serveur de documents reçoit par défaut les requêtes JWT entrantes, et la documentation officielle d'intégration Nextcloud identifie également Authorizationcette valeur comme valeur par défaut du connecteur. Les exemples plus anciens et les installations existantes peuvent utiliser AuthorizationJWTune autre valeur explicitement configurée. La règle à suivre n'est donc pas d'« utiliser systématiquement une chaîne de caractères spécifique », mais de s'assurer que la configuration active corresponde des deux côtés .

Le format de la requête est également important. La documentation de l'API ONLYOFFICE présente des jetons d'en-tête envoyés via le schéma Bearer. Pour plus de détails sur le protocole sous-jacent, consultez la documentation ONLYOFFICE relative aux jetons d'en-tête .

Si vous utilisez délibérément un en-tête personnalisé, configurez la même valeur dans les deux produits. Sinon, l'utilisation de la valeur par défaut actuelle Authorizationsimplifie le processus.

3. Vérifiez si un proxy inverse modifie le chemin du jeton

Si les paramètres de Nextcloud et d'ONLYOFFICE correspondent mais que l'erreur persiste, examinez le chemin d'accès entre eux. Un proxy inverse, une passerelle d'authentification, un pare-feu applicatif web (WAF) ou un contrôleur d'entrée peut affecter les en-têtes d'autorisation. Cela dépend de votre infrastructure ; par conséquent, ne présumez pas de la culpabilité du proxy sans preuve.

Utilisez cette séquence de test pratique :

• Vérifiez que l'URL publique du serveur de documents est accessible depuis l'hôte Nextcloud.
• Vérifiez que l'URL du serveur de documents interne, si elle est configurée, pointe bien vers le serveur ou le conteneur Nextcloud.
• Vérifiez que l'URL interne Nextcloud/storage est bien résolue depuis l'hôte ou le conteneur ONLYOFFICE Docs.
• Examinez les journaux d'accès/d'erreurs du proxy pendant l'exécution de la vérification du connecteur.
• Si votre proxy possède des règles explicites pour Authorization, vérifiez qu'il transmet plutôt que de remplacer ou de supprimer l'en-tête.

Ne désactivez pas JWT pour faire disparaître l'erreur. Cela supprime le mécanisme de validation au lieu de le réparer. De même, ne désactivez pas la vérification TLS pour corriger un problème JWT : la vérification du certificat et la validation de la signature JWT sont des contrôles distincts. En cas de problème de certificat, corrigez la chaîne de certificats ou la configuration de confiance séparément.

4. Utilisez la fonction de vérification de l'état du connecteur

Le connecteur officiel ONLYOFFICE inclut une commande de diagnostic dédiée :

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

La documentation du connecteur indique que ce test signale la réussite de la connexion ou la cause d'une erreur. Il est plus utile que de tester uniquement la page d'accueil du serveur de documents, car il permet de vérifier l'intégration du point de vue de Nextcloud.

Si la vérification indique que le serveur de documents est accessible mais que la validation du jeton échoue, revenez au secret et à l'en-tête. Si l'accès au serveur est impossible, résolvez les problèmes de DNS, de routage, de pare-feu, de TLS ou d'URL internes avant de consacrer plus de temps à JWT.

5. Ne vérifiez l'heure que lorsque les preuves le confirment.

Les jetons JWT peuvent inclure des revendications temporelles, et le connecteur Nextcloud expose jwt_leewaydes jwt_expirationparamètres à ce sujet. Cela ne signifie pas pour autant qu'il faille augmenter la marge de tolérance en premier lieu. Une horloge erronée peut entraîner la défaillance de jetons par ailleurs valides ; augmenter la marge de tolérance peut masquer le problème d'infrastructure.

Comparez l'heure UTC sur les hôtes ou conteneurs Nextcloud et ONLYOFFICE :

date -u
timedatectl status

Assurez-vous que les deux systèmes synchronisent correctement l'heure. Ce n'est qu'après avoir confirmé un léger décalage horaire légitime que vous devriez envisager une tolérance minimale. Les paramètres JWT pris en charge par le connecteur sont répertoriés dans le manuel de configuration officiel du connecteur .

Comment fonctionne la validation JWT dans cette intégration

ONLYOFFICE Docs utilise JWT pour protéger l'initialisation de l'éditeur et les requêtes serveur à serveur. Son API distingue les jetons du navigateur de ceux des requêtes HTTP entrantes et sortantes. Pour les requêtes entrantes, le jeton peut être inclus dans l'en-tête ou, pour les requêtes POST prises en charge, dans le corps de la requête. Pour les requêtes GET, ONLYOFFICE documente la gestion des jetons dans l'en-tête. Consultez la documentation officielle sur la signature des requêtes .

Cela explique pourquoi une opération peut réussir tandis qu'une autre échoue. Par exemple, l'ouverture de l'éditeur peut réussir alors qu'un rappel ou une requête de téléchargement ultérieur peut échouer si une seule des deux directions possède les paramètres de jeton corrects.

Idées fausses courantes

« Si /healthcheck renvoie vrai, le JWT doit être correct. »

Non. Un point de terminaison de santé prouve que le service répond ; il ne prouve pas que le connecteur Nextcloud et le serveur de documents partagent le même secret et le même en-tête JWT. Action : exécutez occ onlyoffice:documentserver --checket examinez les paramètres de connecteur effectifs.

« Je peux modifier le fichier local.json à l'intérieur d'un conteneur Docker et c'est tout. »

Cette méthode est fragile pour les déploiements Docker. ONLYOFFICE recommande de configurer le JWT via les variables d'environnement Docker, car le démarrage peut régénérer la configuration. Action : définissez JWT_ENABLED` JWT_SECRETJWT JWT_HEADER. ...

« L’en-tête AuthorizationJWT est toujours requis. »

Non. La configuration officielle actuelle du serveur de documents indique Authorizationcet en-tête par défaut, bien que les déploiements existants et les exemples plus anciens puissent utiliser un autre en-tête configuré explicitement. Action : lire les deux configurations actives et les rendre identiques.

« Désactiver JWT est la solution la plus rapide. »

Cela peut supprimer l'erreur de validation immédiate, mais cela supprime également un contrôle de sécurité et peut masquer l'incohérence sous-jacente. Action : corrigez le secret/l'en-tête partagé, sauf si vous avez une raison valable et documentée de fonctionner sans JWT.

Liste de contrôle de validation finale

• Le même secret JWT est configuré dans Nextcloud et ONLYOFFICE Docs.
• Le nom de l'en-tête JWT est identique des deux côtés.
• Les déploiements Docker utilisent des variables d'environnement persistantes, et non une modification ponctuelle à l'intérieur du conteneur.
• Les URL des serveurs publics et internes sont accessibles dans le sens où elles sont utilisées.
• Aucune règle de proxy ne supprime ou ne réécrit de manière inattendue l'en-tête JWT.
• Les systèmes Nextcloud et ONLYOFFICE ont des horloges synchronisées.
• occ onlyoffice:documentserver --checkréussit.
• Un document réel s'ouvre, se modifie, s'enregistre automatiquement, se ferme et se rouvre avec la modification enregistrée.

Lorsque l'erreur de jeton persiste

Si les clés secrètes et les en-têtes correspondent, que les horloges sont synchronisées et que la vérification du connecteur réussit, mais qu'une opération spécifique signale toujours un jeton invalide, capturez la direction exacte de la requête défaillante et les journaux correspondants avant de modifier d'autres paramètres. ONLYOFFICE distingue la validation du navigateur, de la boîte de réception et de la boîte d'envoi ; il convient donc de déterminer si l'échec se produit lors de l'initialisation de l'éditeur, d'une commande envoyée au serveur de documents ou d'un rappel/téléchargement renvoyé à Nextcloud.

Utilisez les journaux du serveur de documents conjointement avec les journaux Nextcloud et les journaux du proxy pour un même horodatage. Évitez de publier publiquement des JWT ou des secrets complets. Si vous devez comparer la structure des jetons, masquez la signature et les informations sensibles. Le comportement de référence pour la signature et la validation est décrit dans la documentation de signature d'ONLYOFFICE .