Une API partenaire peut lire des commandes, créer des remboursements et recevoir des webhooks de paiement. Le diagramme d’architecture montre TLS et OAuth, mais personne ne sait encore ce qu’un token volé permet, comment un message rejoué agit ni quelle équipe détecte une dérive.
En réalité, la présence de standards ne constitue pas un modèle de menace. Le risque vient des hypothèses entre organisations : audience trop large, identifiant d’objet devinable, secret copié, payload accepté comme fiable ou file de retry capable de répéter une mutation financière.
Un signal faible apparaît quand la revue de sécurité demande seulement « chiffrement oui/non » ; un autre signal faible apparaît lorsque tous les scénarios se terminent par « surveillance des logs » sans événement précis. Le coût caché combine fraude, exposition de données, interruption, enquête et perte de marge.
Vous allez comprendre comment relier actifs, flux, frontières, abus, contrôles et tests à l’authentification et sécurité des intégrations API. Contre-intuitivement, notre expertise en intégration API préfère un modèle court qui prouve dix chemins critiques à un inventaire exhaustif que personne ne peut rejouer.
Dans quels cas le threat model devient critique
Le modèle devient prioritaire dès qu’un partenaire agit au-delà d’une simple lecture publique : données personnelles, paiement, stock, droits, documents, configuration ou capacité de déclencher une opération irréversible.
Repérer une relation de confiance implicite
Une IP autorisée, un réseau privé ou un contrat commercial ne prouvent pas l’identité de chaque appel. La compromission d’un poste partenaire ou d’un secret transforme cette confiance globale en accès durable.
Le premier atelier liste ce que l’intégration suppose vrai : identité, horloge, ordre des événements, unicité, disponibilité, schéma, provenance et capacité de révocation. Chaque hypothèse non imposée devient un candidat de menace.
Cibler les effets métier importants
Une réponse 200 n’est pas l’actif ; l’actif est la commande correcte, le remboursement unique, la confidentialité du dossier ou la disponibilité de la chaîne. Cette formulation empêche de réduire la sécurité au transport.
Le produit, les opérations, la conformité et la technique nomment ensemble les pertes inacceptables. Un contrôle devient prioritaire lorsqu’il protège un effet que le métier ne peut ni compenser ni reconstruire.
Borner le système et les actifs à protéger
Un périmètre utile inclut les composants capables d’influencer la décision : client partenaire, gateway, service métier, fournisseur d’identité, stockage, queue, back-office, observabilité et opérateurs humains concernés.
Décrire les actifs par propriété
Pour chaque donnée ou capacité, l’équipe précise confidentialité, intégrité, disponibilité, authenticité et non-répudiation attendues. Une clé privée réclame surtout confidentialité ; un ordre de remboursement réclame intégrité, unicité et attribution.
Les actifs comprennent aussi métadonnées, quotas, journaux, schémas et clés de routage. Un identifiant de client exposé peut permettre une énumération même si le document final reste protégé.
Écrire ce qui reste hors périmètre
Le modèle indique les services non étudiés, leurs owners et le document qui les couvre. « Infrastructure sécurisée » n’est pas une exclusion recevable si une mauvaise configuration peut contourner le contrôle de l’API.
Les dépendances héritées disposent d’un contrat d’assurance : version TLS, rotation, disponibilité, surveillance ou test tiers. Une exclusion sans preuve devient une dette acceptée, pas une disparition du risque.
Tracer les flux de données réellement exécutés
Le Data Flow Diagram décrit acteurs externes, processus, stockages et flux, avec protocoles et données traversées. Il montre aussi les retours, appels secondaires et traitements asynchrones que le parcours nominal oublie souvent.
Partir d’une transaction complète
L’équipe suit une commande depuis émission du token jusqu’au résultat métier, puis parcourt validation, accès aux données, événement, cache, webhook et journal. Chaque étape nomme entrée, sortie et décision.
Le diagramme sépare contrôle et donnée : obtenir un token, appeler une ressource et publier un message sont trois flux distincts. Cette précision révèle les chemins qui n’appliquent pas la même politique.
Ajouter les chemins dégradés
Timeout, retry, dead-letter queue, cache périmé, batch manuel et support d’urgence appartiennent au modèle. Un attaquant cherchera précisément le chemin où l’équipe a réduit les vérifications pour rétablir le service.
Le fallback indique conditions, durée, owner et journalisation. S’il contourne l’autorisation ou accepte un payload non vérifié, il crée une frontière plus faible que le chemin nominal.
Nommer chaque frontière de confiance
Une frontière apparaît quand identité, responsabilité ou niveau de confiance changent. Internet vers gateway est évidente ; gateway vers service métier, compte technique vers tenant et production vers support le sont parfois moins.
Attacher un contrôle à chaque passage
Le flux franchissant une frontière précise authentification, autorisation, validation, confidentialité, intégrité, quotas et preuve. TLS protège le canal, mais ne décide ni l’objet accessible ni l’usage autorisé.
Les frontières sont numérotées et reliées aux scénarios. L’équipe peut alors montrer que le contrôle F3 refuse une audience étrangère et que le test T3 reproduit effectivement ce refus.
Refuser la confiance transitive
Le service interne ne doit pas croire toute requête parce qu’elle vient de la gateway. Il reçoit un contexte d’identité vérifiable, impose sa propre autorisation métier et borne les attributs transmis.
La même règle vaut pour la réponse partenaire. HTTPS authentifie un serveur, pas l’exactitude commerciale de chaque donnée ; le consommateur contrôle schéma, limites et invariants avant effet.
Modéliser acteurs, capacités et préconditions
« Attaquant externe » reste trop vague pour produire une défense. Le modèle distingue client légitime curieux, intégration compromise, administrateur partenaire, opérateur interne, fournisseur tiers et processus automatisé mal configuré.
Attribuer les capacités plausibles
Un acteur peut posséder un token valide, observer le trafic côté client, contrôler une URL de callback ou connaître des identifiants. Le scénario n’accorde pas arbitrairement un accès administrateur si ce pouvoir n’est pas plausible.
Chaque capacité possède une origine et une durée. Un secret exposé dans un pipeline, un token court volé en mémoire et une clé partenaire oubliée n’ouvrent ni la même fenêtre ni la même réponse.
Inclure les erreurs non malveillantes
Un job qui mélange deux clients, un opérateur qui copie le mauvais fichier ou un webhook envoyé deux fois peuvent produire le même impact qu’une attaque. La défense doit protéger l’invariant, pas deviner l’intention.
Cette lecture évite de confier tout le risque à la détection de fraude. Idempotence, partitionnement, validation d’objet et confirmation renforcée ferment aussi les accidents ordinaires.
Écrire des scénarios d’abus reproductibles
Un scénario relie acteur, précondition, action, frontière, actif et impact. « Vol de données » devient par exemple : un client valide modifie l’identifiant d’une commande et obtient l’adresse d’un autre partenaire.
Formuler le chemin minimal
La description utilise les étapes nécessaires, sans récit spectaculaire. Elle indique le premier contrôle attendu, la réponse observable et la preuve qui confirmerait que l’abus a échoué.
Par exemple : capturer un webhook valide, le rejouer après cinq minutes, déclencher un second remboursement. Cette formulation appelle horodatage, signature, anti-rejeu, idempotence et test de double effet.
Chercher les abus de logique métier
Les catégories STRIDE aident à varier les questions, mais elles ne remplacent pas la connaissance du processus. Fractionner un montant pour rester sous un seuil peut contourner une autorisation sans exploiter une faille technique classique.
L’atelier demande comment dépasser quota, ordre, montant, nombre d’objets, étape ou séparation des rôles. Le résultat devient une liste de chemins testables, pas une collection de noms génériques.
Prioriser selon impact et faisabilité
Un score ne doit pas produire une fausse précision. L’équipe évalue impact métier, préconditions, exposition, détectabilité, réversibilité et contrôles déjà prouvés, puis documente les hypothèses encore incertaines.
Faire dominer les pertes irréversibles
Une fuite de données sensibles ou une mutation financière non compensable passe devant un défaut cosmétique fréquent. La fréquence historique ne suffit pas pour ignorer un événement rare mais catastrophique.
Les seuils relient niveau de risque et décision : bloquer la mise en production, limiter le périmètre, ajouter une défense, accepter temporairement ou surveiller. Chaque acceptation possède owner et date de revue.
Distinguer risque inhérent et résiduel
Le risque inhérent décrit le scénario sans défense ; le risque résiduel tient compte des contrôles testés. Une configuration prévue mais non déployée ne réduit jamais le niveau affiché.
Le registre lie preuve, environnement et version. Si le partenaire change son flux ou si l’audience OAuth s’élargit, la conclusion précédente ne peut pas être réutilisée automatiquement.
Relier chaque menace à un contrôle observable
Une menace sans contrôle reste un risque ; un contrôle sans menace devient une dépense difficile à justifier. La matrice relie scénario, défense préventive, détection, réponse, preuve et owner.
Définir un résultat de sécurité
« Utiliser OAuth » est une solution ; « un token émis pour le partenaire A ne peut lire aucune ressource du partenaire B » est un résultat testable. La seconde phrase oriente configuration et test négatif.
Le contrôle décrit entrées, sorties, responsabilités, dépendances, seuil, journalisation, monitoring et fallback. Cette structure empêche qu’un composant soit déclaré protecteur sans comportement en panne.
Construire une défense en profondeur utile
Gateway, service et données peuvent imposer des garanties complémentaires, à condition que chacune ferme un mode distinct. Trois vérifications identiques dépendant du même claim ne constituent pas trois défenses indépendantes.
Le test désactive ou contourne une couche lorsque cela reste sûr, puis vérifie que l’invariant tient. Cette mutation contrôlée révèle si la profondeur annoncée existe réellement.
Durcir identité, tokens et autorisations
L’identité partenaire doit être courte, révocable et bornée à une audience. Les permissions expriment les opérations et ressources nécessaires, sans scope générique réutilisé par tous les environnements.
Séparer émission et décision métier
Le serveur d’autorisation prouve l’identité et les attributs consentis ; l’API décide si cette identité peut agir sur l’objet et dans son état courant. Un scope ne remplace pas cette autorisation.
La méthode des identités de workload attestées complète le modèle lorsque les appels machine doivent abandonner des secrets longs au profit d’identités courtes et renouvelées.
Protéger redirections et jetons
L’audience, l’émetteur, la signature, la durée et le type de token sont validés. Les redirect URI utilisent une correspondance stricte ; les flux dépréciés ne survivent pas par compatibilité tacite.
Rotation et révocation possèdent un test opérationnel. Si une clé est compromise, l’équipe sait couper le partenaire, estimer les appels concernés et rétablir le service sans partager un secret par messagerie.
Valider données entrantes et réponses tierces
Chaque payload reste non fiable jusqu’après validation syntaxique et métier. Taille, profondeur, types, formats, relations, montants et transitions sont bornés avant d’allouer des ressources coûteuses ou d’écrire une donnée.
Refuser les champs ambigus
Le contrat rejette les propriétés inconnues sur les mutations sensibles ou les isole selon une règle versionnée. Une valeur par défaut ne doit pas transformer une omission en autorisation, quantité ou statut avantageux.
Les identifiants fournis sont recherchés dans le périmètre autorisé. La méthode d’isolation tenant API détaille la propagation de cette frontière jusque dans SQL, caches, messages, fichiers et index.
Borner la consommation d’une API tierce
Une réponse externe valide techniquement peut contenir mille pages, une URL interne, un fichier énorme ou des valeurs incohérentes. Le client impose taille, pagination, redirections, destinations et temps maximal.
Le fallback ne considère jamais la dernière réponse comme éternellement sûre. Il associe fraîcheur, provenance, intégrité et usage autorisé, puis bloque l’effet si la donnée dépasse son budget de confiance.
Couvrir webhooks, files et reprises
L’asynchrone éloigne la cause de l’effet et multiplie les rejouages. Le modèle doit traiter authenticité, ordre, duplication, retard, saturation et capacité d’un message ancien à modifier un état récent.
Signer contenu et contexte
La signature couvre le corps brut, un horodatage et un identifiant d’événement. Le récepteur valide secret actif, fenêtre temporelle, type attendu et correspondance du partenaire avant désérialisation métier.
La clé d’idempotence est stockée avec le résultat. Un même événement rejoué retourne la décision connue ; il ne crée ni second remboursement ni nouvelle notification trompeuse.
Séparer panne technique et refus métier
Le retry traite timeout et indisponibilité transitoire avec backoff et plafond. Un objet interdit, une signature invalide ou une transition impossible rejoint une quarantaine, sans boucle infinie.
Le monitoring observe queue depth, ancienneté, duplications, échecs de signature et dead letters. Un seuil déclenche runbook, owner et décision de ralentissement ou de coupure du partenaire.
Journaliser sans fabriquer une fuite secondaire
Le journal doit prouver la décision de sécurité sans recopier secrets, tokens, données personnelles ou payloads complets. Il conserve identité normalisée, action, ressource pseudonymisée, verdict, règle et corrélation.
Définir les événements utiles
Un refus d’audience, une signature expirée, un objet hors périmètre ou un quota dépassé possèdent des codes distincts. Le support peut diagnostiquer sans ouvrir le contenu protégé.
Les alertes utilisent taux, séquence et contexte plutôt qu’un événement isolé. Dix identifiants interdits parcourus par le même client révèlent une énumération que dix logs génériques ne montrent pas.
Tester la réponse à incident
L’exercice part d’un signal concret, identifie la clé ou le token, borne les ressources touchées, coupe l’accès, conserve les preuves et restaure une identité saine. Chaque étape est chronométrée.
Une détection sans révocation ni inventaire d’impact ne réduit que tardivement le risque. Le modèle garde donc contrôles préventifs, détectifs et correctifs reliés au même scénario.
Maintenir le modèle avec le contrat API
Le modèle devient périmé lorsque endpoints, scopes, données, fournisseurs ou chemins de fallback changent. Sa maintenance doit suivre les décisions d’architecture, pas une revue annuelle indépendante du code.
Déclencher une revue sur les différences
Une pull request signale nouveau flux, nouvelle frontière, nouvel actif, permission élargie ou dépendance modifiée. L’équipe révise uniquement les scénarios touchés, puis rejoue leurs tests.
Le schéma, le diagramme et la matrice portent une version corrélée au déploiement. Un contrôle prouvé sur la version trois ne couvre pas automatiquement la nouvelle route introduite en version quatre.
Suivre les risques résiduels
Chaque acceptation indique justification, owner, échéance, condition de réouverture et signal surveillé. Elle ne se transforme jamais en « risque connu » permanent sans décision renouvelée.
Les incidents, anomalies et quasi-accidents enrichissent les scénarios. Un signal faible non prévu vaut souvent davantage qu’une nouvelle catégorie théorique ajoutée à la matrice.
Éviter les erreurs fréquentes de modélisation
Les modèles échouent moins par manque de vocabulaire que par absence de liens. Un diagramme sans abus, une menace sans owner ou un contrôle sans test ne change aucune décision de mise en production.
Reconnaître les livrables décoratifs
- Cocher STRIDE : six catégories sont remplies, mais aucun acteur, objet, précondition ni impact métier ne permet de reproduire le scénario.
- Faire confiance au réseau : la gateway authentifie l’appel, tandis que le service accepte audience, ressource et attributs sans autorisation locale.
- Tout confier aux logs : l’équipe détecte éventuellement l’abus après l’effet, sans prévention, alerte précise, révocation ni procédure de limitation.
- Oublier le dégradé : retry, batch manuel et support d’urgence contournent les contrôles conçus uniquement pour le parcours nominal.
Chaque erreur fréquente appelle une correction vérifiable : scénario concret, contexte signé, événement d’alerte ou test du fallback. Ajouter une colonne « couvert » ne prouve jamais le comportement.
Auditer par échantillon contradictoire
La revue choisit une menace critique, une acceptée et une considérée faible. Une autre équipe tente de retrouver le flux, le contrôle, le test, la preuve et la conclusion résiduelle.
Si le verdict dépend de l’auteur du modèle, le dossier reste incomplet. Le but n’est pas l’unanimité parfaite, mais une décision reproductible à partir des mêmes faits.
Suivre un exemple concret de webhook de paiement
Un prestataire appelle payment.refunded avec montant, commande et identifiant d’événement. Le traitement crédite le client puis publie une écriture comptable ; la disponibilité de ce flux est importante, son unicité davantage.
Écrire les chemins d’abus
Le scénario A rejoue un événement signé ; le scénario B remplace l’identifiant de commande ; le scénario C envoie un montant supérieur ; le scénario D sature la file avec des signatures invalides.
Les contrôles couvrent anti-rejeu, idempotence, rattachement partenaire-commande, plafond métier, validation d’état, quota avant traitement coûteux et quarantaine clairement distincte des erreurs techniques réellement transitoires.
Prouver les refus
Le test rejoue le payload cent fois et observe une seule écriture. Il change la commande et reçoit un refus sans révéler son existence, puis dépasse le montant et vérifie l’absence d’événement aval.
Enfin, un exercice de clé compromise coupe l’ancien secret, borne les événements reçus pendant la fenêtre et rétablit le partenaire. La preuve couvre ainsi prévention, détection et réponse.
Plan d’action : produire la preuve en six semaines
Le pilote sélectionne une transaction sensible et un partenaire réel. Il évite le modèle de toute la plateforme et couvre pourtant identité, synchrone, asynchrone, stockage, support et observabilité nécessaires à cette transaction.
Avancer du flux vers les tests
- Semaine 1 : borner transaction, acteurs, actifs, environnements, dépendances, hypothèses et exclusions avec leurs owners et preuves héritées.
- Semaine 2 : tracer flux nominaux et dégradés, identifier toutes les frontières et qualifier les données traversées dans chaque direction.
- Semaine 3 : écrire quinze scénarios d’abus avec acteur, précondition, action, impact, faisabilité et signaux observables sans contrôle.
- Semaine 4 : relier contrôles préventifs, détectifs et correctifs, puis nommer risques résiduels, owners, échéances et décisions de périmètre.
- Semaine 5 : automatiser les tests négatifs, anti-rejeu, autorisation objet, limites, schéma, fallback, révocation et absence de fuite dans les logs.
- Semaine 6 : exécuter la revue contradictoire, corriger les écarts et autoriser le go seulement si les chemins critiques produisent les refus attendus.
La recette exige que chaque menace prioritaire possède un contrôle actif, une preuve datée et un risque résiduel assumé. Les formulations « sécurisé par OAuth » ou « surveillé » restent insuffisantes.
Poser les portes de passage
L’extension attend zéro mutation croisée, zéro double effet sous replay, une révocation testée et des files bornées. Tout fallback non modélisé limite le go au périmètre qui ne l’utilise pas.
Le comité réunit owner métier, sécurité, intégration, exploitation et représentant partenaire. Il tranche les risques, la date de revue et la capacité réelle de réponse avant d’ouvrir davantage de données.
- Traçabilité : actif, flux, frontière, scénario, contrôle, test et risque résiduel utilisent des identifiants reliés dans le même dossier versionné.
- Résistance : autorisation objet, validation, idempotence, quotas, retry, fallback et révocation sont testés sur les chemins nominaux et dégradés.
- Décision : chaque risque non fermé possède owner, justification, expiration et signal capable de provoquer une nouvelle revue immédiate.
Guides complémentaires et sources primaires
La modélisation s’appuie sur des méthodes et standards, mais le verdict dépend du système réel. Les références suivantes précisent la démarche, les risques API et les recommandations OAuth actuelles.
Relier le modèle aux contrôles voisins
L’isolation tenant dans une API approfondit autorisation objet, partitionnement, caches, messages et tests négatifs lorsque la frontière critique sépare plusieurs organisations clientes dans le même système.
Les identités machine pour API complètent la revue des secrets, audiences, rotations, révocations et preuves d’identité entre workloads ou partenaires dans plusieurs environnements distincts.
Vérifier la méthode et les recommandations
L’OWASP Threat Modeling Cheat Sheet structure la démarche autour de la décomposition, de l’identification et priorisation des menaces, des mitigations puis de la revue et validation.
Le NIST SP 800-154 — Data-Centric System Threat Modeling présente une approche centrée sur les données protégées et leur intégration aux processus de gestion du risque.
L’OWASP API Security Top 10 2023 — Unsafe Consumption of APIs rappelle qu’une donnée tierce doit rester validée, bornée et traitée avec le même niveau de défiance qu’une entrée utilisateur.
La RFC 9700 — OAuth 2.0 Security Best Current Practice actualise le modèle d’attaquant OAuth, déprécie des modes moins sûrs et fournit les recommandations applicables aux déploiements modernes.
Conclusion : fermer des chemins, pas cocher une liste
Un threat model utile relie la valeur métier au comportement technique. Il nomme les actifs, suit les flux, marque les frontières et décrit comment un acteur plausible pourrait provoquer une perte concrète.
La qualité vient ensuite des liens : chaque scénario prioritaire possède contrôle, owner, test, preuve et risque résiduel. Un standard ou un produit ne remplace jamais cette chaîne de décision.
Le premier périmètre doit rester étroit et profond, puis évoluer avec le contrat. Les événements de sécurité, incidents et changements d’architecture réouvrent les hypothèses avant que la confiance implicite ne s’installe.
Pour cartographier les flux, durcir les identités et transformer les scénarios d’abus en tests de mise en production, notre accompagnement en intégration API rend le risque vérifiable.
