Stocker les secrets d'application pour un site

L'onglet Secrets est un stockage chiffré pour les valeurs de configuration sensibles dont une app Node.js a besoin, comme les clés API, les secrets de signature et les tokens tiers, conservés par environnement pour que vos identifiants de production et vos identifiants d'aperçu ne se mélangent jamais.

Où se trouvent les Secrets

Ouvrez Websites, cliquez sur le site, ouvrez le menu Advanced dans la bande d'onglets du site, et choisissez Secrets. L'onglet s'intitule Secrets.

L'onglet n'apparaît que sur les sites Node.js. Les sites WordPress, PHP et statiques ne l'affichent pas, car leur configuration se trouve dans des fichiers sur le disque à la place : wp-config.php pour WordPress, et tout ce que votre framework lit pour une app PHP simple.

Comment les valeurs sont protégées

Chaque valeur est chiffrée avant de toucher la base de données. Rien n'est stocké sous forme de texte lisible, et la vue de liste ne montre jamais une valeur complète : elle affiche un masque avec seulement les quatre derniers caractères, pour que vous puissiez distinguer deux clés similaires sans exposer l'une ou l'autre.

Chaque ligne porte un badge Encrypted comme rappel de cela. Relire une valeur est une action séparée et délibérée plutôt que quelque chose qui se produit simplement en ouvrant la page.

Les deux environnements

Un contrôle segmenté en haut de la page bascule entre production et preview. Ce sont des ensembles de clés complètement séparés. Définir STRIPE_SECRET_KEY en production ne le crée pas en aperçu, et le supprimer de l'aperçu ne touche pas la production.

Cette séparation est l'objectif de cette fonctionnalité. Les builds d'aperçu sont des environnements jetables que quiconque ayant accès au référentiel peut déclencher, ils doivent donc porter des identifiants de test, pas des identifiants réels. Consultez Preview Deploys For Pull Requests pour voir comment les environnements d'aperçu sont créés.

Ajouter ou mettre à jour un Secret

1. Choisissez l'environnement avec le contrôle segmenté.
2. Tapez le nom dans le champ KEY_NAME. Le champ force les majuscules au fur et à mesure de la saisie.
3. Mettez la valeur dans le deuxième champ. Elle est masquée au fur et à mesure de la saisie.
4. Cliquez sur Set.

Définir une clé qui existe déjà la remplace. Il n'y a pas d'action d'édition séparée et pas d'étape de confirmation pour un remplacement, donc vérifiez l'onglet d'environnement avant de cliquer sur Set.

Règles de nom de clé

Une clé doit commencer par une lettre majuscule et peut ensuite contenir des lettres majuscules, des chiffres et des traits de soulignement, jusqu'à 128 caractères. DATABASE_URL, API_KEY_V2 et SENTRY_DSN sont tous valides. Tout le reste est rejeté avec le message Key must be UPPER_SNAKE_CASE letters/numbers/underscore.

Deux autres limites méritent d'être connues :

• Une valeur ne peut pas être vide. Soumettre une valeur vide retourne value required.
• Une valeur ne peut pas dépasser 16 KB. C'est généreux pour un token mais pas suffisant pour, disons, une chaîne de certificats complète, qui appartient à un fichier plutôt qu'à un secret.

Relire une valeur

Cliquez sur Copy sur la ligne. KPanel déchiffre la valeur côté serveur et la met directement dans votre presse-papiers, avec une confirmation Value copied to clipboard. La valeur n'est pas imprimée à l'écran, donc un partage d'écran ou un regard par-dessus l'épaule ne la captera pas.

Chaque révélation est écrite dans la piste d'audit du site, avec qui l'a fait et quelle clé, et apparaît dans le Site Activity Log.

Utiliser un Secret dans votre App

Copiez la valeur dans l'endroit où votre application lit sa configuration sur le serveur. Pour une app Node.js, c'est normalement une variable d'environnement définie par votre gestionnaire de processus, ou un fichier .env à la racine de l'app que votre code charge au démarrage.

L'onglet Secrets est votre enregistrement de ce que la valeur est, conservée chiffrée et auditée, plutôt qu'une note dans un gestionnaire de mots de passe ou un fil de message. Gardez-le comme source de vérité : quand vous renouvelez une clé chez le fournisseur, mettez-la à jour ici en même temps, pour que la prochaine personne à déployer ait la valeur actuelle.

Supprimer un Secret

Cliquez sur Delete sur la ligne. KPanel vous demande de confirmer avec Delete {KEY}? et vous avertit que l'app perdra l'accès à cette valeur au prochain redémarrage. Il n'y a pas d'annulation et aucune copie conservée, donc si vous pourriez avoir besoin de la valeur à nouveau, copiez-la d'abord.

Supprimez un secret quand l'identifiant sous-jacent a été révoqué chez le fournisseur, ou quand le code qui l'utilisait a été supprimé. Laisser des clés obsolètes en place rend plus difficile de dire, plus tard, lesquelles comptent vraiment.

Renouveler un identifiant en toute sécurité

L'ordre sûr est toujours : créer le nouvel identifiant chez le fournisseur, le mettre à jour ici, déployer, confirmer que l'app fonctionne, puis révoquer l'ancien identifiant chez le fournisseur.

Le faire dans l'autre sens, révoquer d'abord, vous donne une fenêtre où l'app en cours d'exécution détient un identifiant mort et chaque requête qui en a besoin échoue. Si le changement est risqué, faites d'abord une sauvegarde pour pouvoir revenir à un état connu et bon : consultez Taking a Backup.

Dépannage

L'onglet Secrets n'est pas dans le menu. Le site n'est pas un site Node.js. Vérifiez le badge de pile à côté du nom du site en haut de la page.

Le bouton Set ne fait rien. Les deux champs sont requis. Le bouton signale Key + value required si l'un des deux est vide.

La clé a été rejetée. Les lettres minuscules, les traits d'union, les points et les espaces ne sont pas autorisés. api-key et Api_Key échouent tous les deux ; API_KEY réussit.

Copy n'a rien mis dans le presse-papiers. Certains navigateurs bloquent les écritures dans le presse-papiers sur un onglet inactif. Cliquez d'abord sur la page, puis cliquez à nouveau sur Copy.

Où aller ensuite

• Preview Deploys For Pull Requests, l'autre moitié de la séparation production et aperçu.
• Git Deploy For a Site pour pousser le code qui lit ces valeurs.
• Site Activity Log pour voir qui a défini, révélé ou supprimé un secret.