DEV Community

Cover image for Comment tester les API nécessitant des certificats client (mTLS) dans Apidog
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

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

Vous interrogez une API partenaire avec une requête valide et un jeton correct, mais la négociation TLS échoue avant même l’envoi de la requête HTTP. Le serveur ne réclame pas encore votre clé API : il attend que votre client prouve son identité avec un certificat. C’est le TLS mutuel (mTLS).

Essayez Apidog dès aujourd’hui

Ce guide montre comment configurer des certificats clients et des certificats CA dans Apidog pour tester une API protégée par mTLS. Vous allez :

  1. Associer un certificat client et une clé privée à un hôte.
  2. Ajouter une CA privée ou auto-signée.
  3. Envoyer une requête HTTPS qu’Apidog signera automatiquement.

Si les erreurs SSL sont nouvelles pour vous, consultez aussi l’introduction à la vérification des certificats SSL. Pour les bases du protocole, la référence TLS de MDN est un bon point de départ.

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

Avec HTTPS standard, la confiance est unidirectionnelle :

  1. Le serveur présente son certificat.
  2. Le client vérifie ce certificat.
  3. La connexion est chiffrée.

Le serveur ne possède toutefois aucune preuve cryptographique de l’identité du client. Il s’appuie généralement sur une clé API, un jeton Bearer ou OAuth dans la requête HTTP.

Avec le TLS mutuel, la vérification fonctionne dans les deux sens :

  1. Le serveur présente son certificat.
  2. Le client vérifie le serveur.
  3. Le serveur demande un certificat au client.
  4. Le client présente son certificat et sa clé privée.
  5. La connexion ne s’ouvre que si le serveur fait confiance à ce certificat.

Si le certificat client est absent, invalide ou signé par une CA non reconnue par le serveur, la négociation échoue. Aucun en-tête HTTP, aucun corps de requête et aucun jeton OAuth ne sont envoyés.

Vous rencontrerez souvent mTLS dans ces contextes :

  • Banque et paiements : des API d’open banking ou de traitement de cartes ajoutent un certificat client à OAuth. La documentation Stripe décrit des modèles de credentials en couches pour des endpoints financiers sensibles.
  • Trafic interne et service à service : dans une architecture zero trust, les services s’identifient par certificat plutôt que par appartenance au réseau.
  • API partenaires B2B : un partenaire peut fournir un certificat client pendant l’onboarding afin de limiter l’accès aux machines enregistrées.

mTLS et OAuth ne s’excluent pas. La RFC 8705 définit notamment comment associer un jeton OAuth à un certificat client.

Retenez la séparation suivante dans Apidog :

  • Les certificats gèrent l’identité au niveau TLS.
  • L’onglet Autorisation gère les clés API, les jetons Bearer, OAuth et l’authentification Basic.

Vous avez souvent besoin des deux, mais ils se configurent à des endroits différents.

Comment Apidog applique les certificats par hôte

Apidog configure les certificats globalement, et non requête par requête.

Vous ajoutez un certificat, vous l’associez à un hôte, puis Apidog l’attache automatiquement à chaque requête HTTPS qui correspond à cet hôte.

Deux types de certificats sont disponibles :

  • Certificat client : prouve votre identité auprès du serveur pendant la négociation mTLS.
  • Certificat CA : ajoute une autorité de certification de confiance pour valider les certificats de serveurs internes, privés ou auto-signés.

Par exemple, un certificat CA permet d’éviter l’erreur suivante :

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

La correspondance se fait sur l’hôte. Si l’hôte ou le port ne correspond pas à votre configuration, Apidog ne sélectionnera pas le certificat client.

Configurer un certificat client pour une API mTLS

Supposons qu’un partenaire de paiement vous fournisse :

  • un certificat client ;
  • une clé privée ;
  • éventuellement une phrase secrète ;
  • un endpoint https://partner-api.acmebank.com/v1/settlements.

L’API exige mTLS avant de traiter votre requête.

Étape 1 : ouvrir les paramètres des certificats

Dans Apidog :

  1. Cliquez sur l’icône des paramètres en haut à droite.
  2. Ouvrez l’onglet Certificats.
  3. Accédez à la section Certificats clients.

Cette configuration est réutilisée automatiquement pour toutes les requêtes correspondant à l’hôte.

Étape 2 : ajouter le certificat client

Sous Certificats clients, cliquez sur Ajouter un certificat.

Dans le champ Hôte, saisissez uniquement le domaine :

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

N’ajoutez pas https://.

Pour utiliser le même certificat sur plusieurs sous-domaines, utilisez un motif wildcard :

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Ce motif peut couvrir, par exemple :

partner-api.acmebank.com
sandbox-api.acmebank.com
settlements-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Le port est optionnel :

  • laissez-le vide pour utiliser 443 ;
  • indiquez-le si votre endpoint mTLS utilise un port comme 8443 ou 9443.

Étape 3 : sélectionner les fichiers de certificat

Apidog prend en charge deux formats courants.

Option A : certificat CRT et clé privée séparée

Sélectionnez :

  • le fichier de certificat, par exemple .crt ;
  • le fichier de clé privée, par exemple .key.

Option B : fichier PFX

Sélectionnez un fichier .pfx contenant à la fois le certificat et la clé privée.

Si la clé privée ou le bundle est protégé, renseignez le champ phrase secrète. Sinon, laissez-le vide.

Un package d’intégration bancaire contient souvent une paire similaire à :

client.crt
client.key
Enter fullscreen mode Exit fullscreen mode

Étape 4 : enregistrer la configuration

Cliquez sur Ajouter.

Le certificat apparaît dans la liste et est désormais associé à :

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Vous n’avez plus besoin de l’ajouter manuellement à chaque requête.

Étape 5 : envoyer une requête HTTPS

Créez et envoyez votre requête :

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

Au moment de la négociation TLS, Apidog :

  1. détecte l’hôte de la requête ;
  2. trouve le certificat client associé ;
  3. présente le certificat au serveur ;
  4. termine la négociation mTLS ;
  5. envoie la requête HTTP avec votre jeton OAuth.

Une réponse API pourrait ressembler à ceci :

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

Le certificat prouve l’identité du client au niveau TLS. Le jeton Bearer prouve l’identité ou les permissions de l’appelant au niveau applicatif.

Ajouter un certificat CA pour une racine interne ou auto-signée

Le certificat client ne résout pas tous les problèmes TLS.

Si le certificat du serveur est signé par une CA privée, interne ou auto-signée, Apidog peut refuser la connexion avant même la phase mTLS :

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

Pour résoudre ce problème :

  1. Ouvrez Paramètres → Certificats.
  2. Activez la section Certificats CA.
  3. Sélectionnez votre fichier CA au format PEM.

Un fichier PEM peut contenir plusieurs certificats, par exemple une chaîne de CA racines et intermédiaires :

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
Enter fullscreen mode Exit fullscreen mode

Une fois cette CA ajoutée :

  • Apidog fait confiance au certificat du serveur ;
  • le serveur peut vérifier votre certificat client ;
  • la connexion mTLS fonctionne de bout en bout.

Conseils pratiques et cas fréquents

Utiliser un certificat pour plusieurs sous-domaines

Si votre partenaire vous fournit un certificat à portée wildcard, configurez une seule entrée :

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Évitez d’ajouter une entrée distincte pour chaque sous-domaine lorsque le même certificat doit être utilisé partout.

Configurer les ports non standards

Le port par défaut est 443.

Si votre API écoute sur 8443, configurez explicitement ce port dans le certificat client. Sinon, l’hôte ne correspondra pas correctement et le certificat ne sera pas envoyé.

Exemple d’URL :

https://partner-api.acmebank.com:8443/v1/settlements
Enter fullscreen mode Exit fullscreen mode

Remplacer un certificat expiré

Les certificats ne sont pas modifiables après leur ajout.

Pour remplacer un certificat :

  1. Supprimez l’entrée existante.
  2. Ajoutez le nouveau certificat.
  3. Vérifiez l’hôte, le port et la phrase secrète avant d’enregistrer.

Ajoutez cette procédure à votre runbook de rotation des certificats.

Éviter les doublons par domaine

N’enregistrez pas deux certificats clients pour le même domaine.

Chaque liaison est spécifique à l’hôte. Un doublon rend ambigu le certificat qu’Apidog doit présenter.

Ne pas confondre certificats et autorisation HTTP

Utilisez Certificats pour mTLS.

Utilisez Autorisation pour :

  • clé API ;
  • jeton Bearer ;
  • OAuth ;
  • authentification Basic.

L’autorisation peut être définie à plusieurs niveaux :

  • requête individuelle ;
  • dossier ;
  • collection.

Les requêtes peuvent hériter de l’autorisation du dossier ou de la collection. Pour approfondir ce sujet, consultez le guide sur l’authentification de la passerelle API et le tutoriel de configuration de l’authentification Kerberos dans Apidog.

Utiliser HTTPS obligatoirement

Apidog n’attache pas de certificat client à une requête HTTP simple.

Cette URL ne déclenchera jamais mTLS :

http://partner-api.acmebank.com/v1/settlements
Enter fullscreen mode Exit fullscreen mode

Utilisez toujours HTTPS :

https://partner-api.acmebank.com/v1/settlements
Enter fullscreen mode Exit fullscreen mode

Automatiser les tests mTLS avec l’interface CLI d’Apidog

Après avoir validé vos requêtes dans l’interface, exécutez vos scénarios depuis un terminal ou un pipeline CI/CD avec l’interface CLI d’Apidog.

Installez la CLI et authentifiez-vous :

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Exécutez ensuite un scénario enregistré avec un environnement :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Pour transmettre la configuration mTLS, utilisez notamment :

  • --ssl-client-cert pour le certificat PEM ;
  • --ssl-client-key pour la clé privée ;
  • --ssl-client-passphrase si la clé est protégée ;
  • --ssl-extra-ca-certs pour ajouter des CA de confiance ;
  • --ssl-client-cert-list pour charger une configuration de certificats associée à des motifs d’URL.

Vous pouvez aussi produire plusieurs rapports :

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenario_id> \
  -e <env_id> \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

Intégrez cette commande à votre pipeline pour vérifier votre API mTLS à chaque push. Le guide de l’interface CLI d’Apidog en CI/CD couvre l’exécution dans un pipeline.

Questions fréquentes

Ai-je besoin d’un certificat client et d’un certificat CA ?

Cela dépend du serveur.

Vous avez besoin d’un certificat client lorsque le serveur exige mTLS.

Vous avez besoin d’un certificat CA lorsque le certificat du serveur est signé par une autorité non reconnue par défaut, par exemple une CA interne.

En pratique :

  • API publique avec CA reconnue + mTLS : certificat client uniquement.
  • API interne avec CA privée + mTLS : certificat client et certificat CA.

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

Vérifiez ces points :

  1. Le champ Hôte contient uniquement le domaine, sans https://.
  2. Le port configuré correspond à l’URL.
  3. L’URL utilise https://.
  4. Le certificat est associé au bon sous-domaine ou au bon wildcard.

Apidog n’attache jamais de certificat à une requête HTTP non chiffrée.

Où configurer une clé API ou un jeton Bearer ?

Dans l’onglet Autorisation de la requête, du dossier ou de la collection.

Les certificats gèrent l’identité TLS. L’autorisation gère les credentials HTTP. Consultez les schémas de sécurité pour les types d’authentification disponibles.

Un certificat peut-il couvrir plusieurs sous-domaines ?

Oui. Utilisez un motif tel que :

*.example.com
Enter fullscreen mode Exit fullscreen mode

Le même certificat client sera alors utilisé pour les sous-domaines de example.com.

Comment mettre à jour un certificat ?

Supprimez l’entrée existante, puis ajoutez le certificat renouvelé ou corrigé.

Pour mieux gérer les variations entre environnements, utilisez aussi la définition de paramètres globaux dans Apidog.

En résumé

Pour tester une API protégée par mTLS dans Apidog :

  1. Associez le certificat client au bon hôte.
  2. Ajoutez une CA si le serveur utilise une racine privée ou auto-signée.
  3. Utilisez une URL HTTPS.
  4. Configurez OAuth, les clés API ou les jetons Bearer séparément dans Autorisation.
  5. Laissez Apidog sélectionner automatiquement le certificat lors de la négociation TLS.

Téléchargez Apidog, ajoutez le certificat fourni par votre partenaire et envoyez votre première requête mTLS.

Top comments (0)