← Blog
10 min de lecture
|
Publié le
|
Mis à jour le

Rotation de clés API : créer, définir, tester, finaliser

Faire tourner des clés API sans interruption : schéma créer, définir, tester, finaliser, durées du NIST, gestionnaires de secrets et cas Chaingateway.

Chapitres
C
Chaingateway Team
Experts blockchain

Relu par Maurice Sobiera

Illustration isométrique de la rotation des identifiants API

La rotation d’une clé API consiste à remplacer une clé active par une nouvelle, à intervalle fixe ou après une exposition, puis à retirer l’ancienne. Le schéma fiable compte quatre étapes : créer, définir, tester, finaliser. Un court chevauchement laisse les deux clés valides, pour que les requêtes en cours n’échouent pas. Le NIST et l’OWASP recommandent tous deux de l’automatiser.

Pourquoi faire tourner les clés API ?

La rotation réduit la durée pendant laquelle une clé divulguée reste utile à un attaquant. Chaque clé API est un risque permanent. Une clé peut fuiter par un fichier .env commité, un runner CI compromis ou l’ordinateur portable d’un ancien collaborateur. Plus la clé reste valide longtemps, plus la fuite reste exploitable.

L’OWASP classe ce risque sous NHI7, Long-Lived Secrets, dans son Non-Human Identities Top 10. Il décrit des clés API et des jetons dont la date d’expiration est très lointaine, voire inexistante. Il juge ces secrets extrêmement courants, car la rotation est difficile et les alternatives éphémères ne sont pas toujours disponibles.

La rotation compte surtout pour ces identifiants :

  • Les clés aux portées larges, comme l’accès admin, la facturation ou l’écriture sur les données de production.
  • Les identifiants partagés entre plusieurs services ou équipes.
  • Tout ce qui est intégré dans du code côté client, des applications mobiles ou des intégrations tierces.
  • Les jetons qui ont touché un dépôt public, même brièvement.

Quand c’est possible, remplacez la clé statique par un jeton de courte durée issu d’OAuth ou d’un système d’identité de charge de travail. Un identifiant qui expire seul n’a pas besoin de tâche de rotation.

À quelle fréquence faire tourner les clés API ?

Le NIST fixe un seul chiffre concret, et il vise les clés de signature. Le NIST IR 8587 indique que, pour les systèmes à fort impact, les clés de signature ne doivent pas avoir une période d’usage actif supérieure à 90 jours. Pour les systèmes à impact modéré ou faible, une période plus longue peut convenir, mais elle doit rester inférieure à un an. Le rapport demande aussi de documenter les cryptopériodes et d’employer une rotation automatisée.

Le NIST ne donne pas d’intervalles pour les clés API ordinaires. Les valeurs ci-dessous sont nos suggestions, tirées de l’approche fondée sur le risque du rapport. Ce n’est pas une exigence du NIST.

IdentifiantÂge maximal suggéréRaison
Clés de signature des systèmes à fort impact90 jours (NIST)Plus grand rayon d’impact
Clés API de service à service30 à 90 joursDépend de la portée
Jetons CI/CD30 joursPortent souvent un accès au déploiement
Clés API destinées aux utilisateurs90 jours, et immédiatement après une exposition suspectéeNombreuses copies en circulation

Diagramme à barres des cryptopériodes suggérées : clés de signature jusqu'à 90 jours, clés de service à service de 30 à 90 jours, jetons CI/CD jusqu'à 30 jours, clés API destinées aux utilisateurs 90 jours

La règle derrière ce tableau est simple : plus un identifiant divulgué peut causer de dégâts, plus sa période d’usage doit être courte. Un cycle manuel de 30 jours est réaliste pour une poignée de clés. Avec des dizaines de services, il faut automatiser. Le NIST fait la même remarque. Des cryptopériodes plus courtes poussent les organisations à automatiser la rotation et à pratiquer régulièrement le basculement.

Où stocker les clés API ?

Stockez les clés dans un gestionnaire de secrets qui versionne les secrets, exécute des hooks de rotation, limite l’accès et journalise chaque lecture. Les tableurs et les fichiers .env partagés ne savent rien faire de tout cela. Vérifiez quatre capacités avant de choisir :

  • Le versionnement, pour que le secret actuel et le précédent puissent exister en même temps.
  • Des hooks de rotation qui lancent votre fonction de rotation selon un calendrier ou un événement.
  • Une portée d’accès restreinte, pour que l’agent de rotation ne puisse pas lire tous les secrets.
  • Des journaux d’audit qui consignent qui a consulté ou fait tourner quel secret.

AWS Secrets Manager prend en charge la rotation planifiée par une fonction de rotation. HashiCorp Vault peut émettre des secrets dynamiques qui expirent d’eux-mêmes. Les services de gestion de clés natifs du cloud, liés à des rôles IAM, jouent le même rôle.

Quand l’architecture le permet, évitez les clés statiques. L’OWASP recommande les secrets dynamiques dans la mesure du possible, car ils réduisent la surface de réutilisation des identifiants. Les identifiants temporaires d’AWS STS ou les identités managées sur Azure et Google Cloud expirent après quelques minutes ou heures. Il ne reste alors rien de durable à faire tourner.

Quelles sont les étapes créer, définir, tester, finaliser ?

Ces quatre étapes sont le schéma que la cheat sheet de l’OWASP décrit pour les fonctions de rotation serverless. Elles s’appliquent à tout gestionnaire de secrets ou script maison.

  1. Créer : générer une nouvelle version du secret sans toucher à celle qui est utilisée.
  2. Définir : pousser le nouvel identifiant vers le service dépendant ou le magasin de configuration.
  3. Tester : lancer un contrôle d’intégration qui prouve que le nouveau secret s’authentifie.
  4. Finaliser : promouvoir le nouveau secret comme actif, puis révoquer l’ancien ou planifier sa suppression.

L’étape que les équipes sautent est le chevauchement entre « définir » et « finaliser ». Le NIST le décrit comme une acceptation simultanée de l’ancienne et de la nouvelle clé. La rotation doit planifier le basculement des clés avant l’expiration, pour que les destinataires acceptent les deux versions pendant un temps. La bonne durée du chevauchement dépend de votre système. Elle doit dépasser votre requête en cours la plus longue et le temps dont vos clients ont besoin pour prendre la nouvelle valeur, durées de cache comprises. Choisissez un chiffre, puis testez-le en préproduction.

DéclencheurCas d’usageModèle de permissions
PlanifiéCadence prévisible, par exemple 30 ou 90 joursRôle de rotation limité à un chemin de secret
ÉvénementielCompromission détectée, départ d’un collaborateurÉlevé mais limité dans le temps, révoqué après l’exécution
ManuelAudits ponctuels, intégration d’un nouveau serviceValidation humaine plus MFA

L’agent de rotation doit détenir le plus petit jeu de permissions possible : l’accès en écriture à un seul secret, rien de plus large.

Que doit contenir ma checklist de rotation ?

Passez en revue quatre points avant d’automatiser quoi que ce soit.

  1. Sauvegardez le secret actuel et testez le retour arrière, pour qu’il ne reste pas théorique.
  2. Écrivez un test d’intégration qui valide le nouvel identifiant sur un vrai point d’accès.
  3. Créez un rôle de rotation limité à exactement un secret.
  4. Journalisez chaque événement de rotation dans votre piste d’audit.

Surveillez trois points de défaillance récurrents. Des applications mettent les identifiants en cache mémoire et ne voient la nouvelle clé qu’après un redémarrage. Des fournisseurs limitent le débit du point d’accès de création de clés si vous faites tourner beaucoup de secrets en un seul lot. Des clients périmés continuent à utiliser une clé révoquée après la fin du chevauchement.

Journalisez qui ou quoi a déclenché chaque rotation, une version masquée de l’ancienne et de la nouvelle clé, le mode (planifié, manuel ou d’urgence) et le résultat. Surveillez un pic soudain de requêtes venant d’une clé, des appels depuis des adresses IP ou des régions que la clé n’avait jamais utilisées, et des requêtes qui emploient une clé censée avoir déjà expiré. Lancez des analyses de dépôts pour trouver les clés codées en dur et tenez un inventaire, car une clé hors inventaire n’est jamais renouvelée.

Comment faire tourner les identifiants Chaingateway ?

Une intégration Chaingateway utilise trois types de secrets, et chacun tourne différemment.

Le jeton API authentifie vos requêtes comme jeton bearer. Vous créez les jetons dans le panneau du compte sous API Tokens, et vous donnez un nom à chacun. Utilisez un nom par environnement, comme development, staging et production. Pour la rotation, créez un nouveau jeton, déployez-le via votre gestionnaire de secrets, vérifiez que les requêtes aboutissent, puis retirez l’ancien. Pour limiter ce qu’un jeton divulgué peut faire, activez la liste blanche d’IP (voir ci-dessous) afin que seules les adresses de vos serveurs puissent l’utiliser.

Le secret du webhook, appelé secret personnel, signe chaque webhook par l’en-tête X-Signature. La documentation sur la sécurité des webhooks indique qu’un nouveau secret prend effet immédiatement sur les notifications de webhook. Vous ne pouvez pas faire tourner deux secrets côté émetteur, donc le chevauchement doit se faire côté récepteur. Vérifiez la signature avec le nouveau secret et avec l’ancien pendant un court moment, puis abandonnez l’ancien.

import { createHmac, timingSafeEqual } from "node:crypto";
// Accept the new secret and, during rotation only, the previous one
const secrets = [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET_PREVIOUS].filter(Boolean);
function signatureValid(txid, received) {
return secrets.some((secret) => {
const expected = createHmac("sha256", secret).update(txid).digest("base64");
return (
expected.length === received.length &&
timingSafeEqual(Buffer.from(expected), Buffer.from(received))
);
});
}

Les notifications que votre serveur a rejetées pendant le basculement apparaissent dans la liste des notifications échouées. Chaingateway ne les relance pas automatiquement. Lisez la liste avec GET /api/v2/{chain}/webhooks/notifications/failed et renvoyez chaque entrée avec POST /api/v2/{chain}/webhooks/notifications/{id}/retry. Le guide de livraison des webhooks détaille ce point.

Les mots de passe de portefeuille protègent les adresses que vous avez créées avec un mot de passe. Vous pouvez en changer avec POST /api/v2/ethereum/addresses/{address}, qui prend old_password et new_password. La même route existe pour les autres chaînes. Chaingateway ne stocke pas les mots de passe : conservez donc le nouveau dans votre gestionnaire de secrets avant de changer. Un mot de passe perdu ne peut pas être récupéré.

À quoi sert la liste blanche d’IP de Chaingateway ?

La liste blanche d’IP est un paramètre du compte qui limite votre clé API aux adresses de serveurs que vous indiquez. Elle a été publiée le 21 juin 2021. Vous l’activez dans les paramètres du panneau du compte, puis vous saisissez les adresses autorisées. Une requête provenant de toute autre adresse est refusée, même si la clé est correcte. Une clé divulguée est donc inutilisable depuis une machine que vous n’avez pas listée.

Ajoutez l’adresse de votre propre serveur en activant la fonction, sinon vos propres requêtes sont aussi refusées. Indiquez l’adresse publique que votre serveur présente sur Internet. Les plages privées comme 10.0.0.0/8 et 192.168.0.0/16 sont définies dans la RFC 1918 et n’arrivent jamais à l’API comme source d’une requête. Derrière une passerelle NAT, indiquez l’adresse de la passerelle. Toutes les machines situées derrière sont alors autorisées, et pas une seule.

La liste blanche s’applique aux requêtes que vous envoyez à l’API. Elle ne s’applique pas aux webhooks, qui vont de Chaingateway vers votre endpoint. Vérifiez les webhooks avec la signature, comme décrit plus haut.

La liste blanche et la rotation limitent des choses différentes. La liste blanche limite l’endroit où une clé volée fonctionne. La rotation limite la durée pendant laquelle elle fonctionne. Utilisez les deux. Quand vos serveurs passent à de nouvelles adresses, mettez la liste à jour avant le changement, afin que votre propre trafic ne soit pas refusé.

Quand les clés API statiques cessent-elles d’avoir du sens ?

Les clés statiques conviennent aux outils internes à faible risque. Dès que vous exposez une API à des partenaires externes ou que vous traitez des données financières, passez à une authentification OIDC ou JWT avec des durées d’expiration courtes. Commencez par un service à faible trafic. Confirmez que votre automatisation de rotation tient sous trafic réel, puis étendez. Une politique de rotation appliquée, et pas seulement suggérée, est l’un des changements opérationnels les plus efficaces qu’une équipe de sécurité puisse faire.

Capture d'écran de la page d'accueil de Chaingateway avec le titre sur une API blockchain unifiée pour les paiements crypto et les webhooks, et un bouton pour démarrer un essai gratuit de 7 jours

Chaingateway couvre Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain et Arbitrum avec une seule API REST et une seule couche d’authentification. Vous ne gérez donc pas un cycle de vie d’identifiants distinct par chaîne. La fonction webhooks couvre les notifications de dépôt. Les forfaits démarrent à 49 € par mois sur la page des tarifs, et l’essai gratuit de 7 jours ne demande pas de carte.

Sources

Recommandé

Created with BabyLoveGrowth to build backlinks

Questions fréquentes

Faire tourner une clé API, c’est générer un nouvel identifiant pour remplacer l’actif, puis retirer l’ancien quand tous les systèmes dépendants ont basculé. Bien menée, la rotation suit un cycle automatisé créer, définir, tester, finaliser, avec un court chevauchement pendant lequel les deux clés fonctionnent.

Cela dépend du risque. Le NIST IR 8587 indique que les clés de signature des systèmes à fort impact ne doivent pas rester en usage actif plus de 90 jours. Pour les clés API ordinaires, il ne donne aucun chiffre : choisissez donc un intervalle selon la portée de la clé. Plus court vaut mieux pour les jetons CI/CD et pour tout ce qui a un accès large.

La rotation limite les dégâts d’un identifiant divulgué ou volé, car elle raccourcit la durée de validité de la clé. L’OWASP classe les secrets de longue durée sous NHI7 dans son Non-Human Identities Top 10.

Automatisez le processus avec un gestionnaire de secrets, suivez le schéma créer, définir, tester, finaliser et gardez une fenêtre de transition pendant laquelle l’ancienne et la nouvelle clé fonctionnent. Cela évite l’interruption qu’entraînerait un basculement simultané de tous les services dépendants.

Oui. Chaingateway signe les webhooks en HMAC-SHA256 dans l’en-tête X-Signature, ce qui vous permet de vérifier leur authenticité. Si vous changez le secret personnel, le nouveau secret s’applique tout de suite : votre récepteur doit donc accepter les deux secrets pendant un court moment.

Comment nous rédigeons ces articles

Prêt à le construire vous-même ? Obtenir votre clé API — essai de 7 jours, sans carte bancaire — ou consultez API Blockchain pour la référence complète des endpoints.

C
Chaingateway Team
Experts blockchain

L'équipe Chaingateway s'attache à simplifier l'intégration blockchain pour les développeurs du monde entier.