Automatisation

n8n : sauvegarder la clé de chiffrement des credentials

N8N_ENCRYPTION_KEY : où n8n la stocke, pourquoi une restauration échoue sans elle, comment la définir, la sauvegarder et la protéger sur une instance auto-hébergée.

· 7 min de lecture · InfiniteLab

Vous avez une sauvegarde de la base de données n8n, une machine neuve, et pourtant les identifiants de connexion (Gmail, CRM, API) ne fonctionnent pas après la restauration. Dans ce scénario, le coupable est presque toujours le même : la clé de chiffrement de l'instance, que personne n'a sauvegardée parce que personne ne savait qu'elle existait.

Cet article explique à quoi sert cette clé, où n8n la range, ce qu'il faut sauvegarder avec elle et comment la protéger sans la fragiliser. Les faits sur n8n viennent de sa documentation officielle, citée en fin d'article ; les recommandations d'organisation sont notre analyse, à adapter à votre contexte.

À quoi sert la clé de chiffrement

D'après la documentation de n8n, l'outil utilise une clé pour chiffrer les credentials avant de les enregistrer dans la base de données. Autrement dit, les mots de passe, jetons et clés d'API que vos workflows utilisent ne sont pas stockés en clair : ils sont lisibles uniquement avec la clé qui les a chiffrés.

La conséquence pratique figure dans la page de sauvegarde et de restauration : sans la clé, une base restaurée ou un export chiffré de credentials ne peut pas être déchiffré. Vos workflows reviennent, vos connexions non. Il faut alors recréer chaque credential à la main, en retrouvant chaque secret auprès de son service d'origine.

Où se trouve la clé

Deux cas se présentent, selon la documentation :

  • Vous n'avez rien défini. n8n génère une clé aléatoire au premier lancement et la range dans le dossier .n8n, dans le fichier config. Par défaut, ce dossier est ~/.n8n, et la variable N8N_USER_FOLDER change son emplacement.
  • Vous avez défini N8N_ENCRYPTION_KEY. n8n utilise alors votre clé plutôt que d'en générer une. Cette variable fait partie de la configuration de déploiement.

Le piège le plus courant vient de ce premier cas. Avec Docker, si le dossier .n8n n'est pas sur un volume persistant, il disparaît avec le conteneur : n8n repart à neuf, sans la clé d'origine. Les retours de la communauté n8n décrivent exactement ce schéma ; la documentation ne le détaille pas, mais il découle de ce qui précède.

Ce qu'une sauvegarde complète contient

La documentation liste ce qu'il faut sauvegarder pour restaurer une instance :

  1. le dossier .n8n (qui contient le fichier config avec la clé) ;
  2. la base PostgreSQL externe, si vous en utilisez une, avec les outils propres à la base ;
  3. le stockage externe des données binaires ou d'exécution (S3, par exemple), et les chemins personnalisés ;
  4. les dossiers chargés via N8N_CUSTOM_EXTENSIONS, si vos workflows utilisent des nœuds personnalisés.

Avec SQLite, la base se trouve dans le dossier .n8n : la documentation précise d'arrêter n8n avant de le copier, sinon la copie peut être incohérente.

Deux choses ressortent. D'abord, sauvegarder la base sans la clé ne suffit pas. Ensuite, si vous avez défini N8N_ENCRYPTION_KEY, elle fait partie de la configuration de déploiement à restaurer, et non d'un dossier : un fichier docker-compose.yml ou un gestionnaire de secrets, par exemple. L'ordre de restauration complet décrit par la documentation est : arrêter n8n, restaurer .n8n, restaurer la base, restaurer la configuration de déploiement (dont la clé personnalisée), redémarrer.

Définir sa propre clé : pourquoi et comment

Laisser n8n générer la clé fonctionne, mais elle reste cachée dans un fichier. Définir N8N_ENCRYPTION_KEY vous donne une clé que vous connaissez et que vous pouvez conserver ailleurs, ce qui est notre recommandation pour toute instance qui compte. La documentation donne l'exemple d'une variable d'environnement :

export N8N_ENCRYPTION_KEY=<UNE CHAÎNE ALÉATOIRE>

Quelques points de méthode, issus de notre pratique :

  • Générez la clé avec un outil prévu pour cela (un gestionnaire de mots de passe ou un générateur aléatoire), pas avec une phrase mémorisable.
  • Faites-le dès l'installation. Pour une instance existante qui utilise la clé générée automatiquement, relevez d'abord la valeur du fichier config et, après un test sur une copie, définissez la variable avec cette même valeur : les credentials déjà enregistrés restent alors lisibles. Ne changez pas la clé sur une instance en production sans avoir testé la procédure sur une copie. La documentation ne décrit aucun rechiffrement automatique lors d'un changement de valeur : ne le supposez pas.
  • Évitez de l'écrire dans un dépôt Git. Pour les variables sensibles, la documentation propose le suffixe _FILE (par exemple DB_POSTGRESDB_PASSWORD_FILE), qui fait lire la valeur depuis un fichier. Vérifiez dans la page de configuration de votre version si le suffixe s'applique à la variable que vous visez.

Le cas du mode queue : la même clé partout

Si vous passez en mode queue avec des workers, la documentation demande de fournir la variable d'encryption key à tous les workers. La raison est la même : un worker qui ne possède pas la clé ne peut pas lire les credentials stockés. Gérez la clé comme un secret partagé, injecté depuis une seule source, plutôt que copié à la main sur chaque machine.

Exporter les credentials : deux options, un risque

La commande n8n export:credentials permet d'exporter les credentials en ligne de commande. Selon la documentation :

  • --backup produit une sauvegarde lisible, un fichier JSON par credential ;
  • la restauration sur une autre instance exige soit la même clé de chiffrement, soit un export avec l'option --decrypted ;
  • --decrypted écrit les données en texte brut : la documentation avertit que toutes les informations sensibles y sont visibles, et qu'il faut conserver ce fichier avec le même soin que les credentials eux-mêmes, puis le supprimer après la restauration.

Notre lecture : la meilleure pratique est de ne pas dépendre de l'export en clair. Conservez la clé dans un coffre, sauvegardez le dossier et la base, et réservez --decrypted à une migration planifiée, avec un fichier qui n'existe que le temps de l'opération. Notez que ces exports ne contiennent ni les utilisateurs, ni l'historique d'exécution, ni les variables, ni les paramètres de l'instance.

Un test de restauration en six étapes

Une sauvegarde qu'on n'a jamais restaurée est une hypothèse. Prévoyez un test trimestriel :

  1. Démarrez une machine ou un conteneur vierge, sans copier l'ancien environnement.
  2. Restaurez le dossier .n8n et la base, comme décrit dans la documentation.
  3. Fournissez la clé depuis votre coffre, pas depuis l'ancienne machine.
  4. Démarrez n8n et ouvrez trois credentials de natures différentes (une API, un OAuth, une base de données).
  5. Lancez un workflow de test qui les utilise.
  6. Notez le temps total et les écarts : c'est votre durée de reprise réelle.

Pour la partie versionnement des workflows, voir sauvegarder et versionner ses workflows n8n. Avant une montée de version, la checklist de mise à jour d'une instance auto-hébergée reprend ces sauvegardes. Et si vous hésitez entre hébergement et cloud pour des données sensibles, notre comparatif n8n cloud ou auto-hébergé pour une PME aide à trancher.

Les erreurs fréquentes

  • Sauvegarder la base sans la clé. C'est le scénario décrit au début de l'article.
  • Ne pas persister le dossier .n8n dans un conteneur : la clé générée disparaît au redémarrage suivant.
  • Stocker la clé au seul endroit qui sera perdu avec la machine, par exemple uniquement dans le docker-compose.yml du serveur.
  • Remplacer la valeur de la clé sur une instance existante sans test.
  • Laisser traîner un export --decrypted dans un dossier partagé ou une sauvegarde.
  • Oublier la clé sur les workers après un passage en mode queue.

Besoin de fiabiliser votre instance n8n ?

Sauvegardes qui n'ont jamais été restaurées, clé de chiffrement connue d'une seule personne, instance dont personne ne sait la reconstruire : ce sont des risques d'exploitation, pas des détails techniques. Décrivez-nous votre installation : nous vérifions où se trouve la clé, ce que couvre votre sauvegarde et nous mettons en place une procédure de restauration testée. Notre approche part toujours d'un processus précis, et nos offres détaillent les formats d'accompagnement.

Sources