n8n auto‑hébergé : protéger N8N_ENCRYPTION_KEY sans perdre ses identifiants

ParKelvin Carretero-Corrales

Une sauvegarde PostgreSQL peut être parfaitement valide et pourtant laisser une instance n8n inutilisable. Les workflows reviennent, les identifiants sont toujours présents dans la base… mais n8n ne peut plus les déchiffrer. La pièce manquante tient dans une variable : N8N_ENCRYPTION_KEY.

Cette clé ne sert pas à chiffrer toute la base. Elle protège les informations sensibles enregistrées par n8n : mots de passe, jetons OAuth, clés d’API et autres données d’authentification. La perdre revient donc à restaurer un coffre sans sa serrure d’origine.

Ce que n8n fait au premier démarrage

Si aucune clé personnalisée n’est fournie, n8n en génère une aléatoire au premier lancement et la conserve dans son dossier utilisateur ~/.n8n. Dans le conteneur Docker officiel, ce dossier se trouve normalement à l’emplacement /home/node/.n8n et doit être monté sur un volume persistant.

Les identifiants sont chiffrés avant d’être enregistrés dans la base. Cela signifie que, dans une installation avec PostgreSQL, deux éléments sont nécessaires pour une restauration complète :

  • la sauvegarde de la base PostgreSQL ;
  • la clé de chiffrement de l’instance, provenant soit du fichier de configuration dans .n8n, soit de la variable N8N_ENCRYPTION_KEY.

Conserver uniquement le dump PostgreSQL ne suffit donc pas. La base contient les données chiffrées, pas le secret permettant de les lire.

La bonne approche pour une nouvelle instance

Pour un nouveau déploiement, le plus propre est de définir explicitement une clé aléatoire avant le premier démarrage. Elle doit être longue, imprévisible et différente des mots de passe utilisés ailleurs.

openssl rand -hex 32

La commande produit 32 octets aléatoires représentés en hexadécimal. Copiez immédiatement le résultat dans un gestionnaire de secrets ou un coffre de mots de passe professionnel. Ne le collez pas dans un dépôt Git, une documentation publique ou un ticket accessible à toute l’équipe.

Dans un fichier Compose, la configuration peut ensuite référencer une variable fournie par l’environnement de déploiement :

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    environment:
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Le fichier Compose décrit où injecter la valeur, mais ne doit pas contenir la clé elle-même. Un fichier .env local peut dépanner sur un petit serveur, à condition d’être exclu de Git, protégé par des permissions strictes et inclus dans la stratégie de sauvegarde. Pour une infrastructure plus sensible, utilisez le mécanisme de secrets proposé par la plateforme de déploiement.

Instance existante : ne remplacez pas la clé au hasard

Sur une instance déjà utilisée, ajouter soudainement une nouvelle valeur à N8N_ENCRYPTION_KEY n’est pas une opération de maintenance anodine. Si elle ne correspond pas à la clé ayant servi à chiffrer les identifiants, n8n ne pourra plus les lire.

Commencez par identifier le mode actuel sans afficher le secret dans les journaux ou dans une capture d’écran :

  1. Vérifiez si N8N_ENCRYPTION_KEY est déjà fournie par votre environnement, votre orchestrateur ou votre gestionnaire de secrets.
  2. Si elle ne l’est pas, confirmez que le volume n8n_data est bien persistant et que le fichier de configuration du dossier .n8n est sauvegardé.
  3. Faites une sauvegarde complète avant toute modification.
  4. Testez la restauration dans un environnement isolé avant de toucher à la production.

Cette commande vérifie seulement la présence du fichier de configuration dans un conteneur Compose ; elle n’en affiche pas le contenu :

docker compose exec n8n sh -lc \
'test -f /home/node/.n8n/config && echo "config présent" || echo "config absent"'

« Présent » ne veut pas dire « sauvegardé et restaurable ». Il faut encore confirmer que le volume figure dans les sauvegardes, que celles-ci ne sont pas vides et qu’une copie indépendante existe.

Une vraie sauvegarde n8n contient plus qu’un export JSON

Les commandes export:workflow et export:credentials sont utiles pour déplacer des éléments entre instances, mais la documentation n8n précise qu’elles ne constituent pas, à elles seules, une sauvegarde complète. Elles n’incluent notamment ni les utilisateurs et leurs rôles, ni l’historique des exécutions, ni les variables, ni les réglages de l’instance, ni la clé de chiffrement.

Pour une installation avec PostgreSQL, le plan minimal doit donc couvrir :

  • la base PostgreSQL, sauvegardée avec un outil adapté et restaurée lors d’un test ;
  • le volume ou dossier .n8n, même si la base est externe ;
  • la valeur personnalisée de N8N_ENCRYPTION_KEY, lorsqu’elle est gérée hors du volume ;
  • les stockages externes de données binaires ou d’exécutions ;
  • les extensions et nœuds personnalisés nécessaires aux workflows ;
  • les fichiers de déploiement et les autres variables indispensables, sans publier leurs secrets.

n8n permet aussi d’exporter les identifiants en clair avec l’option --decrypted. C’est pratique dans quelques migrations très contrôlées, mais extrêmement sensible : le fichier obtenu contient directement les secrets. Ce n’est pas un raccourci à conserver « au cas où » sur le serveur.

En mode queue, toutes les instances partagent la même clé

En mode queue, le processus principal reçoit les déclencheurs tandis que les workers exécutent les workflows. Les workers lisent les identifiants dans la même base ; ils doivent donc recevoir exactement la même N8N_ENCRYPTION_KEY que l’instance principale. La règle vaut aussi pour les processeurs de webhooks.

services:
  n8n-main:
    environment:
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}

  n8n-worker:
    environment:
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    command: worker

Ne créez pas une clé différente par worker. Ce serait logique pour isoler des services ordinaires, mais pas ici : chaque worker doit pouvoir déchiffrer les mêmes identifiants. Gardez également les processus n8n sur une version cohérente pendant les opérations de maintenance.

Rotation : la clé maître et la clé de données ne sont pas la même chose

Les versions récentes de n8n proposent une rotation des clés de chiffrement sur toutes les éditions auto-hébergées. Il faut bien distinguer les deux niveaux :

  • La clé d’instance, fournie par N8N_ENCRYPTION_KEY, joue le rôle de clé maître. Elle protège les clés de données et ne se remplace pas lors d’une rotation ordinaire.
  • La clé de données chiffre directement les identifiants et autres contenus sensibles. C’est elle que n8n sait faire tourner.

Après une rotation, les nouvelles écritures utilisent la nouvelle clé de données. Les anciens enregistrements restent lisibles et sont rechiffrés lorsqu’ils sont modifiés. La matière secrète n’est pas renvoyée par l’API : seules les métadonnées de la clé sont exposées.

Attention : l’activation de la rotation est à sens unique

La fonction s’active avec N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true sur l’instance principale et tous les workers. Mais n8n avertit clairement : une fois que des données ont été écrites dans le nouveau format, désactiver cette option ou revenir à une ancienne version peut rendre ces données illisibles.

La séquence raisonnable est donc la suivante :

  1. réaliser une sauvegarde complète de la base et des éléments de déploiement ;
  2. valider la restauration de cette sauvegarde ;
  3. activer la fonction sur un environnement de test ;
  4. vérifier plusieurs identifiants et exécuter des workflows représentatifs ;
  5. activer ensuite la production sur tous les processus en même temps ;
  6. ne plus désactiver la fonction et ne pas rétrograder vers une version incompatible.

La rotation se pilote ensuite dans Settings > Data Encryption Keys ou via l’API prévue à cet effet. Elle ne remplace ni la sauvegarde de la clé maître, ni les tests de restauration.

Le test qui compte vraiment

Un fichier de sauvegarde présent sur le disque ne prouve presque rien. Le test utile consiste à reconstruire une instance isolée avec la base, le dossier .n8n, la configuration et la même clé maître, puis à vérifier qu’un identifiant peut être ouvert et qu’un workflow de test s’exécute correctement.

Faites ce test sans appeler de services clients ni envoyer de vrais messages : désactivez les workflows automatiques, isolez les webhooks et utilisez des comptes de test. Une restauration ne doit pas déclencher une deuxième fois des factures, des e-mails ou des écritures dans un logiciel métier.

En résumé

Pour n8n, la base de données et la clé de chiffrement forment un couple. Sauvegarder l’une sans l’autre donne une récupération incomplète. Définissez la clé avant le premier lancement lorsque c’est possible, stockez-la hors de Git, fournissez la même valeur à tous les workers et testez une restauration complète.

Si vous voulez fiabiliser une instance ou un workflow avant de le confier à votre activité, FuretSplick peut intervenir sur la partie automatisation, sécurisation et maintenance. Le but n’est pas seulement que « ça tourne », mais que ça puisse aussi repartir proprement après une panne.

Sources

Publications similaires