# Bonnes pratiques en matière de gestion des clés API secrètes

Découvrez comment gérer vos clés API secrètes en toute sécurité et comment réagir rapidement en cas d’exposition ou de compromission.

Les clés API secrètes constituent des identifiants de compte, comparables à un nom d’utilisateur et un mot de passe. Contrairement aux clés publiques, qui peuvent être intégrées en toute sécurité dans des pages web ou des applications, les clés secrètes doivent impérativement rester dans votre environnement serveur. Si une personne non autorisée obtient votre clé API secrète, elle peut effectuer des paiements frauduleux, accéder aux données de vos clients ou perturber votre intégration.

Ce guide présente des méthodes spécifiques pour protéger les clés dans votre environnement serveur. Pour obtenir un aperçu des différents types de clés pris en charge par Stripe, consultez la page [Clés API](https://docs.stripe.com/keys.md).

## Protéger les clés API secrètes

Vous devez gérer et stocker vos clés API secrètes de manière sécurisée à chaque étape du développement afin de les protéger contre toute exposition ou compromission.

- **Ne placez jamais de clés API secrètes dans le code source** : des acteurs malveillants analysent en permanence les dépôts publics à la recherche de clés API Stripe. Même les dépôts privés peuvent être exposés via des environnements de développement.
  - Utilisez les outils de gestion des clés secrètes de votre plateforme (tels qu’un [coffre-fort de secrets](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault)) pour fournir les clés API à votre code d’intégration. Si votre plateforme ne propose pas de coffre-fort de secrets, utilisez plutôt des variables d’environnement.
  - Auditez périodiquement votre code source, vos fichiers de configuration et vos pipelines CI/CD pour détecter les clés sensibles, y compris les clés d’API de l’environnement de test et de l’organisation. Utilisez un scanner de secrets avec des [modèles Stripe](https://docs.github.com/en/code-security/reference/secret-security/supported-secret-scanning-patterns) à jour. Si vous trouvez une clé sensible, partez du principe qu’elle a été [exposée et compromise](https://docs.stripe.com/keys-best-practices.md#handling-compromised-keys).
  - Utilisez un hook pre-commit dans votre système de contrôle de version pour rejeter les commits contenant des clés détectées par votre scanner de secrets.
  - Les extraits de code de la documentation Stripe incluent parfois des clés à titre d’illustration uniquement. N’utilisez pas de vraies clés dans votre code.
- **N’intégrez jamais de clés API secrètes dans vos applications :** des acteurs malveillants peuvent analyser ou désassembler une application afin d’y rechercher des clés intégrées. Pour les usages côté client - tels que les outils client, les SDK ou les applications mobiles - utilisez des [clés publiques](https://docs.stripe.com/keys.md#obtain-api-keys) à la place.
- **Appliquez le principe du moindre privilège :** les personnes et les systèmes ne doivent disposer que des autorisations *strictement nécessaires à l’exécution de leurs tâches*.
  - Définissez une politique claire précisant quels membres de l’équipe sont autorisés à créer, modifier ou consulter des clés API secrètes. Limitez l’accès aux seules personnes qui en ont besoin et vérifiez régulièrement les autorisations associées aux clés.
  - Maintenez une documentation à jour sur la gestion des clés API secrètes au sein de votre organisation. Organisez régulièrement des sessions de formation afin de renforcer l’adoption des bonnes pratiques.
- **Manipulez les clés API secrètes avec la plus grande prudence :** lorsque vous créez une clé API secrète dans le Dashboard Stripe, elle ne s’affiche qu’une seule fois. Stockez-la immédiatement dans le [coffre-fort de secrets](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) de votre plateforme et ne la conservez nulle part ailleurs. Si votre plateforme ne propose pas de coffre-fort de secrets, vous pouvez stocker la clé dans une variable d’environnement.
  - Partagez vos clés API secrètes uniquement via les outils sécurisés de gestion des informations sensibles de votre plateforme - et non par e-mail, message instantané ou ticket d’assistance. **Stripe ne vous demandera jamais votre clé API secrète.**
  - Utilisez des [clés d’API limitées](https://docs.stripe.com/keys-best-practices.md#limit-access) avec des autorisations restreintes au lieu de clés d’API secrètes non restreintes.
- **Renouvelez régulièrement vos clés API secrètes :** définissez et testez un processus clair pour le [renouvellement de vos clés API Stripe](https://docs.stripe.com/keys.md#rolling-keys). Un renouvellement périodique vous permet de vérifier où chaque clé est utilisée et de vous assurer que votre équipe peut la remplacer rapidement si nécessaire. Formalisez un plan de secours afin que, en cas d’exposition ou de compromission d’une clé, votre équipe puisse réagir avec un impact minimal sur votre activité.
- **Auditez les logs des requêtes API afin de détecter toute activité suspecte :** examinez ou surveillez régulièrement les [logs des requêtes](https://docs.stripe.com/development/dashboard/request-logs.md) API afin d’identifier de manière proactive toute utilisation abusive de clés API. Assurez-vous que vos développeurs n’utilisent pas de clés en mode production lorsqu’une clé *d’environnement de test* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) est appropriée. Consultez la rubrique [Environnement de test versus mode production](https://docs.stripe.com/keys.md#test-live-modes).

## Stocker les clés API de manière sécurisée

Ne placez pas de clés d’API limitées ou secrètes dans votre code, même s’il reste sur vos serveurs. Des acteurs malveillants analysent en permanence les bases de code publiques à la recherche de clés API exposées accidentellement. Si vos développeurs ont du code contenant des clés dans leurs environnements de développement, toute compromission du poste d’un développeur peut entraîner l’exposition de ces clés.

Certains exemples de code Stripe incluent des clés d’environnement de test pour faciliter leur exécution immédiate. Si vous copiez un exemple de code, supprimez ces clés et stockez-les dans un [coffre-fort de secrets](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault). Si votre plateforme ne propose pas de coffre-fort de secrets, vous pouvez stocker les clés dans des variables d’environnement.

### Utiliser un coffre-fort de secrets

Un coffre-fort de secrets stocke les identifiants séparément de votre code et les fournit à vos applications au moment de l’exécution. Votre code ne fait référence à une clé que par son nom ou une référence : la valeur n’apparaît donc jamais dans les fichiers sources, la configuration CI ou les environnements de développeur. Au-delà de la protection des valeurs de clés, un coffre-fort fournit un journal d’audit complet de chaque accès, la prise en charge de la rotation automatique des clés et la possibilité d’en révoquer l’accès instantanément sans redéployer votre application.

La plupart des plateformes cloud et des outils d’infrastructure incluent un coffre-fort de secrets. Utilisez les fonctionnalités de permissions de votre plateforme pour restreindre l’accès au coffre-fort aux seuls services qui en ont besoin :

- **[AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)** : s’intègre à IAM et prend en charge la rotation automatique.
- **[Google Cloud Secret Manager](https://cloud.google.com/secret-manager)** : clés secrètes versionnées avec des permissions IAM granulaires.
- **[Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/)** : gère les clés secrètes, les clés et les certificats avec un contrôle d’accès basé sur les rôles.
- **[HashiCorp Vault](https://developer.hashicorp.com/vault)** : auto-hébergé ou géré ; prend en charge les clés secrètes dynamiques et la tenue d’un journal d’audit.

[Cet article de blog](https://stripe.dev/blog/securing-stripe-api-keys-aws-automatic-rotation) explique comment stocker et effectuer la rotation automatique d’une clé API Stripe à l’aide d’AWS Secrets Manager.

### Définir une clé API comme variable d’environnement

Si votre plateforme d’hébergement ne propose pas de coffre-fort de secrets, fournissez les clés à votre application via des variables d’environnement. Certaines plateformes permettent de marquer des variables d’environnement comme *sensibles* afin qu’elles ne soient plus visibles après leur définition. Vos applications peuvent toujours utiliser ces variables sensibles, mais elles ne peuvent pas être dérobées depuis votre navigateur web.

Lorsque vous exécutez des exemples de code de Stripe, définissez une variable temporaire pour votre session de terminal en cours. La variable d’environnement est supprimée lorsque vous fermez le terminal.

#### Mac/Linux

```bash
export STRIPE_API_KEY=sk_test_...
```

### Utiliser la clé API dans votre code

Au lieu d’intégrer une clé codée en dur, votre code fait référence aux clés API par les noms des variables d’environnement.

#### Ruby

```ruby
client = Stripe::StripeClient.new(ENV["STRIPE_API_KEY"])
```

Si vous placez des clés API Stripe dans des variables d’environnement, veillez à ne pas les exposer à vos utilisateurs. Par exemple, n’affichez pas les variables d’environnement sur les pages d’erreur et ne rendez pas les modes de diagnostic accessibles au public.

## Personnaliser l’accès à l’API avec des clés API limitées

Au lieu d’utiliser des clés API secrètes offrant un accès étendu, créez des [clés API restreintes](https://docs.stripe.com/keys/restricted-api-keys.md) afin d’attribuer des autorisations spécifiques aux composants de vos applications. Par exemple, vous pouvez limiter votre système de facturation à la gestion des factures, exclusivement.

Les clés API restreintes vous permettent de limiter l’impact potentiel d’une compromission. Par exemple, si vous devez fournir une clé API Stripe à un tiers chargé du suivi des litiges, vous pouvez créer une clé API restreinte accordant un accès en lecture seule aux ressources liées aux litiges dans votre compte Stripe, tout en bloquant tout autre accès. Si ce tiers était compromis, un attaquant qui s’emparerait de votre clé API restreinte ne pourrait effectuer que ces appels à l’API spécifiques.

## Limiter les adresses IP pouvant envoyer des requêtes API

Si votre service envoie des requêtes d’API à partir d’adresses IP stables, vous pouvez restreindre vos clés d’API secrètes ou limitées à ces adresses. Par exemple, si votre plateforme propose une passerelle NAT dédiée ou un autre moyen de réserver une adresse IP ou une plage d’adresses IP, vous pouvez configurer Stripe pour bloquer les requêtes API utilisant vos clés provenant de toute autre adresse.

Vous pouvez également bloquer les requêtes API en fonction du numéro de système autonome (ASN), du pays ou de catégories de menaces courantes. Pour obtenir des instructions détaillées, consultez la page [Politiques d’accès](https://docs.stripe.com/keys.md#access-policies).

## Gérer les clés API compromises

Si une clé API limitée ou secrète est exposée ou compromise, effectuez une rotation immédiatement, même si vous n’avez pas la certitude qu’elle ait été consultée. Considérez toute exposition comme une compromission potentielle.

- L’*exposition* désigne toute situation où une clé devient visible dans un endroit inapproprié - par exemple dans un dépôt public, un fichier journal ou un e-mail - alors qu’elle aurait dû rester strictement confidentielle.
- La *compromission* correspond à toute situation où des éléments indiquent une utilisation non autorisée de la clé.

### Que faire en cas d’exposition ou de compromission d’une clé ?

Si vous découvrez qu’une clé API limitée ou secrète a été exposée ou compromise, suivez les instructions sur [cette page de service de support](https://support.stripe.com/questions/protecting-against-compromised-api-keys) pour minimiser les dommages potentiels à votre entreprise.

### Protection proactive des clés Stripe

Si Stripe détecte une clé API secrète ou limitée exposée, nous vous en informons et vous demandons de la faire pivoter. Dans certains cas, Stripe désactive la clé de manière proactive et vous informe de toute action.

Stripe ne garantit pas la détection de toutes les clés exposées ou compromises. L’application de ces bonnes pratiques vous aide à prévenir toute exposition de clé et à maintenir la sécurité de votre intégration avec Stripe.

## Clés API gérées

Certaines plateformes serveur ou hébergeurs peuvent [gérer les clés API Stripe](https://docs.stripe.com/keys/managed-api-keys.md) pour le compte de leurs clients, y compris les étapes de provisionnement et de rotation. Les clés API gérées restent sur la plateforme serveur, qui les fournit à votre code côté serveur. Le [Dashboard Stripe](https://dashboard.stripe.com/apikeys) affiche vos clés API gérées, mais ne révèle pas les clés complètes.

Comme les clés API gérées sont des données sensibles dans un environnement serveur, suivez les bonnes pratiques de ce guide pour les protéger. Ne codez jamais en dur les clés API gérées dans votre code côté serveur et n’exposez jamais directement les variables d’environnement depuis votre application.

Si votre plateforme serveur fournit des clés API Stripe gérées à votre application sous forme de variables d’environnement et permet de marquer certaines variables d’environnement comme *sensibles* pour activer des protections supplémentaires, veillez à marquer toutes les clés Stripe comme sensibles.

Si vous pensez qu’une clé API gérée a été exposée ou compromise, [renouvelez-la depuis le Dashboard Stripe](https://docs.stripe.com/keys.md#rolling-keys) ou depuis la plateforme serveur. Si vous renouvelez une clé API gérée dans le Dashboard, ou si Stripe détecte qu’elle a été compromise et la désactive pour protéger votre compte Stripe, nous synchronisons automatiquement ce changement avec votre plateforme serveur : vous n’avez pas besoin de modifier la clé à deux endroits.

Lorsque vos clés API gérées changent, vous devez généralement redéployer les applications correspondantes côté serveur, sauf si votre plateforme serveur effectue ce redéploiement automatiquement.

## See also

- [Clés API](https://docs.stripe.com/keys.md)
- [Protéger vos clés API contre la compromission](https://support.stripe.com/questions/protecting-against-compromised-api-keys)