Comment tester les API nécessitant des certificats client (mTLS) dans Apidog

Vous interrogez une API partenaire, envoyez une requête bien formée avec un jeton valide, et vous obtenez quand même un échec de la négociation TLS. Le point d'accès ne demande pas votre clé API. Il demande à votre client de prouver son identité avec un certificat, avant même qu'une requête HTTP ne quitte votre machine. C'est le TLS mutuel, et si vous ne l'avez jamais configuré dans un outil de test, cela peut bloquer une intégration pendant une journée.

Ce guide explique comment configurer les certificats clients et les certificats CA dans Apidog afin que vous puissiez tester une API protégée par mTLS sans avoir à lutter contre la négociation. Vous ajouterez un certificat client et une clé pour un hôte spécifique, attacherez un certificat CA pour que les racines auto-signées cessent de générer des erreurs, et enverrez une requête authentifiée qu'Apidog signera automatiquement. Si les erreurs de certificat sont un nouveau territoire pour vous, l'introduction à la vérification des certificats SSL vaut la peine d'être lue en parallèle. Pour le protocole lui-même, la référence TLS de MDN est une explication solide et neutre vis-à-vis des fournisseurs.

bouton

Qu'est-ce que le TLS mutuel et pourquoi certaines API l'exigent

Le HTTPS standard est une confiance unidirectionnelle. Le serveur présente un certificat, votre client le vérifie, et la connexion est chiffrée. Le serveur n'a aucune preuve cryptographique de votre identité ; il s'appuie sur un jeton ou une clé API à l'intérieur de la requête pour cela.

Le TLS mutuel fait que la confiance va dans les deux sens. Le serveur présente toujours son certificat, mais il demande également au client d'en présenter un. Si votre certificat n'est pas signé par une autorité de certification à laquelle le serveur fait confiance, la négociation échoue et la connexion ne s'ouvre jamais. Aucun corps de requête, aucun en-tête, rien ne passe.

Vous rencontrerez l'authentification TLS mutuelle (mTLS) dans les cas où un jeton de porteur divulgué n'est pas un mode de défaillance acceptable :

Banque et paiements. Les API d'open banking et les processeurs de cartes nécessitent souvent un certificat client émis à votre organisation en plus d'OAuth. La documentation Stripe décrit ce type de modèle de credential en couches pour les points de terminaison financiers sensibles.
Trafic interne et de service à service. Les entreprises exploitant un réseau de confiance zéro font en sorte que les services prouvent leur identité avec des certificats au lieu de faire confiance au périmètre du réseau.
API partenaires B2B. Un partenaire peut vous délivrer un certificat client lors de l'intégration afin que seules vos machines enregistrées puissent atteindre leurs points de terminaison.

Si OAuth est également en jeu, les deux se combinent proprement ; la RFC 8705 officialise la manière dont le TLS mutuel lie un jeton OAuth à un certificat client. Le certificat est une credential au niveau de la couche réseau, séparée de l'authentification au niveau de la couche application dans votre requête. Cette distinction est importante dans Apidog, et c'est ce qui embrouille le plus souvent les gens. Les certificats gèrent le mTLS. L'onglet Autorisation gère les clés API, les jetons de porteur, OAuth et l'authentification de base. Vous avez souvent besoin des deux à la fois, mais vous les configurez à des endroits différents.

Comment Apidog gère la portée des certificats par hôte

Apidog gère à la fois les certificats CA et les certificats clients, et les configure globalement plutôt que par requête. Vous configurez un certificat une fois, le liez à un hôte, et Apidog l'attache automatiquement à chaque requête HTTPS qui correspond à cet hôte. Il n'y a pas de bascule par requête à retenir ni d'en-tête à coller.

Deux types de certificats remplissent deux fonctions différentes :

Un certificat client est ce que vous présentez pour prouver votre identité pour l'authentification TLS mutuelle. C'est la credential que l'API partenaire demande.
Un certificat CA indique à Apidog de faire confiance à une autorité de certification qu'il ne connaît pas encore. Dirigez-le vers votre CA racine interne et la redoutable erreur SSL Error: Self signed certificate disparaît, car Apidog fait désormais confiance aux points d'accès signés par cette autorité.

La clé de portée est l'hôte. Chaque certificat client est lié à un domaine, et Apidog fait correspondre l'hôte de la requête sortante à cette liaison. Si l'hôte est correct, tout le reste est automatique. Si l'hôte est incorrect, Apidog n'envoie rien silencieusement, car il n'a jamais trouvé de correspondance.

Configurer un certificat client pour une API mTLS

Voici le scénario. Un partenaire de paiement, partner-api.acmebank.com, vous a délivré un certificat client et une clé privée lors de l'intégration. Leur API est uniquement HTTPS et rejette tout client qui ne peut pas présenter ce certificat. Vous souhaitez appeler GET /v1/settlements et inspecter la réponse.

Étape 1 : Ouvrir les paramètres des certificats

Ouvrez les paramètres d'Apidog en utilisant l'icône des paramètres en haut à droite, puis allez à l'onglet Certificats. C'est là que résident les deux types de certificats. Rien ici n'est lié à une seule requête ; cela s'applique à toutes vos requêtes en fonction de la correspondance de l'hôte.

Étape 2 : Ajouter le certificat client

Sous Certificats clients, sélectionnez Ajouter un certificat. Un formulaire s'ouvre pour la liaison de l'hôte et les fichiers de certificat.

Remplissez le champ Hôte avec le domaine uniquement, sans protocole :

partner-api.acmebank.com

Laissez de côté https://. Le champ accepte un domaine nu. Si vous avez besoin d'un certificat pour couvrir plusieurs sous-domaines, le champ hôte prend en charge la correspondance de motifs. Saisir *.acmebank.com utilise le même certificat client pour chaque sous-domaine sous acmebank.com, ce qui est pratique lorsqu'un partenaire utilise partner-api, sandbox-api et settlements-api avec le même certificat émis.

Le port personnalisé est facultatif. Laissez-le vide et Apidog utilisera par défaut 443, le port HTTPS standard. Ne définissez un port que si le point d'accès mTLS écoute ailleurs, par exemple 8443.

Étape 3 : Sélectionner les fichiers de certificat

Apidog accepte deux formats de fichiers pour un certificat client. Choisissez celui que votre partenaire vous a fourni :

Fichiers CRT + Clé. Un fichier de certificat et un fichier de clé privée séparés. Sélectionnez chacun dans son champ.
Fichiers PFX. Un seul fichier groupé qui regroupe le certificat et la clé.

Si le certificat a été généré avec une phrase secrète, saisissez-la dans le champ phrase secrète. C'est facultatif, alors laissez-le vide si votre clé n'est pas protégée par un mot de passe. Un pack d'intégration typique d'une banque est livré sous forme de paire .crt et .key, parfois avec une phrase secrète sur la clé.

Étape 4 : Enregistrer

Sélectionnez Ajouter pour enregistrer le certificat client. Il apparaît maintenant dans votre liste, lié à partner-api.acmebank.com. À partir de ce moment, vous n'y touchez plus pour chaque requête.

Étape 5 : Envoyer la requête authentifiée

Créez une requête vers l'hôte et envoyez-la :

GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <your_oauth_token>

Apidog fait correspondre l'hôte, attache votre certificat client pendant la négociation TLS et complète l'authentification TLS mutuelle avant l'envoi de la requête. Si le partenaire exige également OAuth, ce jeton de porteur est inclus dans la requête comme d'habitude. Le certificat prouve la machine ; le jeton prouve l'appelant. Une réponse réussie pourrait ressembler à ceci :

{
  "settlements": [
    {
      "id": "stl_88213",
      "amount": 41200,
      "currency": "USD",
      "status": "cleared",
      "settled_at": "2026-07-14T09:31:00Z"
    }
  ],
  "next_cursor": null
}

Aucune étape manuelle par requête n'a rendu cela possible. La correspondance de l'hôte l'a fait.

Ajouter un certificat CA pour les racines internes ou auto-signées

Les certificats clients ne sont qu'une partie de l'histoire. L'autre moitié apparaît lorsque le propre certificat du serveur est signé par une autorité à laquelle votre machine ne fait pas confiance, ce qui est courant avec les services internes et les environnements de staging qui utilisent une CA racine privée.

Lorsque cela se produit, la requête échoue avec un message comme SSL Error: Self signed certificate avant même que le mTLS n'ait une chance. La solution consiste à donner la CA à Apidog afin qu'il fasse confiance à cette racine.

Dans le même onglet Certificats, activez le bouton à côté de Certificats CA, puis sélectionnez votre fichier PEM. Les certificats CA utilisent le format PEM, et un seul fichier PEM peut contenir plusieurs certificats CA, vous pouvez donc regrouper une chaîne complète de racines internes et intermédiaires dans un seul fichier :

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----

Une fois la CA approuvée, Apidog cesse de rejeter les points d'accès signés par celle-ci. Associez une CA de confiance à un certificat client et vous pourrez tester un service mTLS interne qui utilise une racine privée de bout en bout : la CA vous permet de faire confiance à leur serveur, et le certificat client leur permet de vous faire confiance.

Conseils avancés et variations courantes

Quelques éléments permettent de gagner du temps une fois la configuration de base passée.

Couverture de sous-domaines avec un seul certificat. Si un partenaire a délivré un certificat à portée wildcard, définissez l'hôte sur *.acmebank.com une seule fois au lieu d'enregistrer partner-api, sandbox-api, et le reste séparément. Une seule liaison, tous les sous-domaines.

Ports non standard. Les passerelles mTLS internes aiment les ports comme 8443 ou 9443. Le port par défaut est 443, alors spécifiez le port personnalisé chaque fois que le point d'accès écoute ailleurs, sinon l'hôte ne correspondra pas et aucun certificat ne sera envoyé.

Les certificats ne sont pas modifiables après ajout. Il n'y a pas d'action d'édition. Pour renouveler un certificat ou corriger une faute de frappe dans l'hôte, supprimez l'existant avec l'icône de suppression et ajoutez-le à nouveau. Intégrez cela dans votre guide de rotation des certificats afin que personne ne cherche un bouton d'édition qui n'existe pas.

Un certificat par domaine. N'enregistrez pas deux certificats clients pour le même domaine. Chaque liaison est spécifique au domaine, et un doublon crée une ambiguïté quant à celui qu'Apidog devrait présenter. Gardez-en un par hôte.

Gardez les certificats et l'autorisation séparés dans votre esprit. C'est la plus grande source de confusion. Le mTLS se trouve dans l'onglet Certificats. Les clés API, les jetons de porteur, OAuth et l'authentification de base se trouvent dans l'onglet Autorisation d'une requête ou d'un dossier, et les requêtes héritent de l'autorisation de leur dossier parent. L'autorisation s'applique à trois niveaux : requêtes individuelles, toutes les requêtes d'un dossier et toutes les requêtes d'une collection. Si un partenaire a besoin d'un certificat client et d'OAuth, vous définissez le certificat dans Certificats et le jeton dans Autorisation. Ils ne se chevauchent pas. Pour un examen plus approfondi du câblage de l'authentification basée sur les jetons, le guide sur l'authentification de la passerelle API couvre le côté requête, et si vous travaillez avec une pile Windows lourde, la configuration de l'authentification Kerberos dans Apidog est un tutoriel connexe qui vaut la peine d'être mis en favori.

HTTPS uniquement, toujours. Apidog n'attachera pas de certificat client à une requête HTTP simple. Si votre cible de test est http://, le certificat n'est jamais envoyé et la logique de négociation ne s'exécute jamais. Le point d'accès doit être HTTPS pour que tout cela s'applique.

Automatiser le workflow avec l'interface CLI d'Apidog

Une fois que vos requêtes mTLS passent manuellement, intégrez-les dans des scénarios de test enregistrés et exécutez-les sans interface graphique avec l'interface CLI d'Apidog. Installez-le et authentifiez-vous :

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Ensuite, exécutez un scénario enregistré contre un environnement :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

La commande apidog run prend en charge directement la configuration des certificats clients, de sorte que le mTLS survit au passage de l'interface graphique au pipeline. Pour un seul certificat, passez --ssl-client-cert (le certificat PEM), --ssl-client-key (la clé privée), et --ssl-client-passphrase si la clé en a une. Pointez --ssl-extra-ca-certs vers des CA fiables supplémentaires, ou utilisez --ssl-client-cert-list avec un fichier de configuration lorsque vous faites correspondre les certificats aux hôtes par motif d'URL. Les rapporteurs sont définis avec -r (essayez -r html,cli). Intégrez cette commande dans un travail et votre API protégée par certificat sera testée à chaque push. Le guide de l'interface CLI d'Apidog en CI/CD couvre son exécution dans un pipeline.

Questions fréquemment posées

Ai-je besoin d'un certificat client et d'un certificat CA, ou seulement d'un des deux ?

Cela dépend du point d'accès. Un certificat client prouve votre identité, vous en avez donc besoin chaque fois que le serveur exige un TLS mutuel. Un certificat CA n'est nécessaire que lorsque le propre certificat du serveur est signé par une autorité à laquelle votre machine ne fait pas déjà confiance, comme une CA racine interne. Une API partenaire publique sur une CA publique fiable ne nécessite que le certificat client ; un service mTLS interne sur une racine privée nécessite généralement les deux.

Pourquoi Apidog n'envoie-t-il pas mon certificat client ?

Presque toujours une non-correspondance d'hôte ou une cible HTTP simple. Vérifiez que le champ Hôte contient le domaine exact sans préfixe https://, que le port correspond (par défaut 443, donc définissez un port personnalisé si le point d'accès écoute ailleurs), et que l'URL de la requête est HTTPS. Apidog n'attache jamais de certificat à une requête HTTP.

Où vont les clés API et les jetons de porteur si ce n'est pas dans les Certificats ?

Dans l'onglet Autorisation de la requête ou du dossier, qui est séparé de la configuration des certificats. Les certificats gèrent l'identité au niveau de la couche TLS ; l'Autorisation gère la clé API, le jeton de porteur, OAuth et l'authentification de base au niveau de la couche requête. Vous trouverez la description complète des types d'authentification dans le guide des schémas de sécurité, et vous pouvez définir l'authentification une fois au niveau du dossier ou de la collection afin que chaque requête en hérite.

Un certificat peut-il couvrir plusieurs sous-domaines ?

Oui. Le champ hôte prend en charge la correspondance de motifs. Saisissez *.example.com et le même certificat client s'appliquera à chaque sous-domaine de example.com. C'est la manière propre de réutiliser un certificat à portée wildcard qu'un partenaire a émis pour plusieurs de ses sous-domaines API.

Comment mettre à jour un certificat après l'avoir ajouté ?

Les certificats ne sont pas modifiables sur place. Supprimez celui qui existe avec l'icône de suppression, puis ajoutez la version corrigée ou renouvelée. Gardez cela à l'esprit pour la rotation des certificats, et pendant que vous organisez les configurations de test, la définition de paramètres globaux dans Apidog s'harmonise bien pour maintenir les valeurs d'environnement propres entre les requêtes.

En résumé

Tester une API protégée par mTLS se résume à trois actions dans Apidog : lier un certificat client à l'hôte correct, attacher un certificat CA si le serveur utilise une racine privée, et laisser la correspondance d'hôte signer automatiquement chaque requête HTTPS. Gardez les certificats et l'autorisation dans leurs sections séparées et la négociation cessera d'être un mystère.

Téléchargez Apidog pour suivre, ajouter le certificat de votre partenaire et envoyer cette première requête authentifiée. Essayez-le gratuitement, aucune carte de crédit requise.