DEV Community

Cover image for APIs mit Client-Zertifikaten (mTLS) in Apidog testen
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

APIs mit Client-Zertifikaten (mTLS) in Apidog testen

Sie greifen auf eine Partner-API zu, senden eine wohlgeformte Anfrage mit einem gültigen Token und erhalten trotzdem einen TLS-Handshake-Fehler. Der Endpunkt fragt nicht nach Ihrem API-Schlüssel: Er verlangt von Ihrem Client, sich mit einem Zertifikat auszuweisen, bevor überhaupt eine HTTP-Anfrage Ihre Maschine verlässt. Das ist gegenseitiges TLS (mTLS) – und ohne die richtige Konfiguration im Testtool kann es eine Integration für einen ganzen Tag blockieren.

Apidog noch heute ausprobieren

Dieser Leitfaden zeigt, wie Sie Client- und CA-Zertifikate in Apidog konfigurieren, um eine mTLS-geschützte API zu testen. Sie binden ein Client-Zertifikat samt Schlüssel an einen Host, hinterlegen bei Bedarf eine interne oder selbstsignierte CA und senden anschließend Anfragen, die Apidog automatisch während des TLS-Handshakes signiert. Als Ergänzung hilft die Einführung zur SSL-Zertifikatsüberprüfung. Für die Grundlagen des Protokolls bietet die MDN-TLS-Referenz eine herstellerunabhängige Erklärung.

Was gegenseitiges TLS (mTLS) ist und warum APIs es verlangen

Normales HTTPS ist einseitiges Vertrauen:

  1. Der Server präsentiert sein Zertifikat.
  2. Ihr Client überprüft dieses Zertifikat.
  3. Die Verbindung wird verschlüsselt aufgebaut.

Der Server hat dabei keinen kryptografischen Nachweis über die Identität Ihres Clients. Dafür verwendet er meist einen API-Schlüssel, ein Bearer-Token oder OAuth innerhalb der HTTP-Anfrage.

mTLS ergänzt diesen Ablauf um eine Client-Prüfung:

  1. Der Server präsentiert sein Zertifikat.
  2. Der Client überprüft den Server.
  3. Der Server fordert ein Client-Zertifikat an.
  4. Der Client präsentiert sein Zertifikat und beweist den Besitz des privaten Schlüssels.
  5. Erst danach wird die HTTP-Verbindung geöffnet.

Ist das Client-Zertifikat nicht von einer vertrauenswürdigen Zertifizierungsstelle signiert, scheitert der Handshake. Header, Request-Body und API-Token erreichen den Server dann nicht.

Typische Einsatzfälle für mTLS:

  • Bankwesen und Zahlungsverkehr: Open-Banking-APIs und Kartenprozessoren kombinieren oft Client-Zertifikate mit OAuth. Die Stripe-Dokumentation beschreibt vergleichbare mehrschichtige Anmeldeinformationsmodelle für sensible Finanzendpunkte.
  • Interner Service-zu-Service-Verkehr: In Zero-Trust-Netzwerken identifizieren sich Dienste mit Zertifikaten statt über Netzwerkpositionen.
  • B2B-Partner-APIs: Partner stellen beim Onboarding Client-Zertifikate aus, damit nur registrierte Systeme auf ihre Endpunkte zugreifen können.

Wenn zusätzlich OAuth verwendet wird, bleiben beide Verfahren getrennt. RFC 8705 beschreibt beispielsweise, wie mTLS OAuth-Tokens an Client-Zertifikate binden kann.

Merken Sie sich diese Trennung in Apidog:

Aufgabe Konfigurationsbereich
Client-Identität auf TLS-Ebene Zertifikate
API-Key, Bearer-Token, OAuth, Basic Auth Authentifizierung/Autorisierung

Oft benötigen Sie beides, aber Sie konfigurieren es an unterschiedlichen Stellen.

Wie Apidog Zertifikate anhand des Hosts auswählt

Apidog verwaltet CA- und Client-Zertifikate global, nicht pro einzelner Anfrage. Sie hinterlegen das Zertifikat einmal, ordnen es einem Host zu und Apidog verwendet es automatisch für passende HTTPS-Anfragen.

Es gibt zwei relevante Zertifikatstypen:

  • Client-Zertifikat: Dieses Zertifikat präsentiert Ihr Client gegenüber dem Server. Es ist die Anmeldeinformation für mTLS.
  • CA-Zertifikat: Dieses Zertifikat erweitert die Vertrauenskette von Apidog. Damit akzeptiert Apidog beispielsweise Zertifikate, die von Ihrer internen Root-CA signiert wurden.

Ein CA-Zertifikat behebt typischerweise Fehler wie:

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

Der entscheidende Schlüssel für die Zuordnung ist der Host. Apidog vergleicht den Host der ausgehenden URL mit der Zertifikatsbindung:

  • Host stimmt überein → Client-Zertifikat wird beim TLS-Handshake verwendet.
  • Host stimmt nicht überein → kein Client-Zertifikat wird gesendet.

Client-Zertifikat für eine mTLS-API einrichten

Angenommen, ein Zahlungspartner stellt Ihnen für partner-api.acmebank.com ein Client-Zertifikat und einen privaten Schlüssel bereit. Sie möchten folgenden Endpunkt aufrufen:

GET /v1/settlements
Enter fullscreen mode Exit fullscreen mode

Schritt 1: Zertifikatseinstellungen öffnen

  1. Öffnen Sie in Apidog die Einstellungen über das Symbol oben rechts.
  2. Wechseln Sie zum Tab Zertifikate.

Dort verwalten Sie sowohl CA- als auch Client-Zertifikate. Die Konfiguration gilt hostbasiert für alle passenden Anfragen.

Schritt 2: Client-Zertifikat hinzufügen

Wählen Sie unter Client-Zertifikate die Option Zertifikat hinzufügen.

Tragen Sie im Feld Host ausschließlich die Domain ein:

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

Verwenden Sie nicht:

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

Das Host-Feld erwartet keinen Protokollpräfix.

Wenn ein Zertifikat mehrere Subdomains abdecken soll, können Sie ein Muster verwenden:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Damit gilt dieselbe Zertifikatsbindung beispielsweise für:

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

Lassen Sie den Port leer, wenn der Endpunkt HTTPS auf dem Standardport 443 verwendet. Geben Sie einen Port nur an, wenn der Dienst auf einem abweichenden Port lauscht, etwa:

8443
Enter fullscreen mode Exit fullscreen mode

Schritt 3: Zertifikatsdateien auswählen

Apidog unterstützt zwei übliche Formate für Client-Zertifikate:

  • CRT + Schlüsseldatei: Zertifikat und privater Schlüssel liegen getrennt vor.
  • PFX-Datei: Zertifikat und privater Schlüssel liegen gemeinsam in einer Datei vor.

Wählen Sie das Format, das Sie vom Partner erhalten haben.

Wenn der private Schlüssel mit einer Passphrase geschützt ist, tragen Sie diese im Feld Passphrase ein. Andernfalls lassen Sie das Feld leer.

Ein typisches Paket kann beispielsweise so aussehen:

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

Oder als gebündelte Datei:

client.pfx
Enter fullscreen mode Exit fullscreen mode

Schritt 4: Zertifikat speichern

Klicken Sie auf Hinzufügen.

Das Zertifikat erscheint anschließend in der Liste und ist an partner-api.acmebank.com gebunden. Sie müssen es nun nicht mehr manuell für jede Anfrage auswählen.

Schritt 5: Authentifizierte Anfrage senden

Erstellen Sie eine HTTPS-Anfrage an den konfigurierten Host:

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

Beim Senden passiert Folgendes:

  1. Apidog erkennt den Host partner-api.acmebank.com.
  2. Apidog findet die zugehörige Client-Zertifikatsbindung.
  3. Apidog verwendet Zertifikat und privaten Schlüssel während des TLS-Handshakes.
  4. Nach erfolgreichem mTLS-Handshake wird die HTTP-Anfrage gesendet.
  5. Das Bearer-Token authentifiziert zusätzlich den Aufrufer auf Anwendungsebene.

Das Zertifikat identifiziert die Maschine bzw. den Client. Das OAuth-Token identifiziert den Aufrufer bzw. die Berechtigung.

Eine erfolgreiche Antwort könnte so aussehen:

{
  "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

Der entscheidende Punkt: Das Host-Matching übernimmt die Zertifikatszuordnung automatisch.

CA-Zertifikat für interne oder selbstsignierte Roots hinzufügen

Ein Client-Zertifikat löst nur die Client-Authentifizierung. Zusätzlich muss Apidog dem Zertifikat des Servers vertrauen.

Das ist häufig bei internen Diensten, Testsystemen oder Staging-Umgebungen relevant, die mit einer privaten Root-CA arbeiten. Ohne diese Root-CA schlägt die Verbindung oft schon vor dem mTLS-Schritt fehl:

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

So hinterlegen Sie eine private CA:

  1. Öffnen Sie den Tab Zertifikate.
  2. Aktivieren Sie CA-Zertifikate.
  3. Wählen Sie Ihre PEM-Datei aus.

CA-Zertifikate verwenden das PEM-Format. Eine Datei kann mehrere Zertifikate enthalten, beispielsweise eine Root-CA und Intermediate-Zertifikate:

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

Danach kann Apidog Serverzertifikate akzeptieren, die von dieser CA signiert wurden.

Für einen internen mTLS-Dienst benötigen Sie häufig beide Komponenten:

  • CA-Zertifikat: Apidog vertraut dem Server.
  • Client-Zertifikat: Der Server vertraut Apidog bzw. Ihrem Client.

Erweiterte Tipps und häufige Varianten

Wildcard-Zertifikate für Subdomains verwenden

Wenn der Partner ein Zertifikat für mehrere Subdomains ausgestellt hat, verwenden Sie eine Wildcard-Bindung:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

So vermeiden Sie separate Einträge für jeden API-Host.

Nicht-Standard-Ports korrekt konfigurieren

Interne mTLS-Gateways verwenden oft Ports wie:

8443
9443
Enter fullscreen mode Exit fullscreen mode

Apidog verwendet standardmäßig Port 443. Wenn Ihr Endpunkt einen anderen Port nutzt, geben Sie ihn in der Zertifikatsbindung an. Andernfalls stimmt die Zuordnung möglicherweise nicht und das Zertifikat wird nicht gesendet.

Zertifikatsrotation einplanen

Hinzugefügte Zertifikate sind nicht direkt bearbeitbar. Bei einer Erneuerung oder einer Korrektur:

  1. Entfernen Sie den bestehenden Eintrag.
  2. Fügen Sie das neue Zertifikat erneut hinzu.

Nehmen Sie diesen Ablauf in Ihr Zertifikatsrotations-Runbook auf.

Nur ein Zertifikat pro Domain registrieren

Registrieren Sie nicht mehrere Client-Zertifikate für denselben Host. Mehrere Bindungen für dieselbe Domain schaffen Unklarheit darüber, welches Zertifikat Apidog präsentieren soll.

Verwenden Sie stattdessen genau einen Eintrag pro Host oder Host-Muster.

Zertifikate und Autorisierung getrennt konfigurieren

Die häufigste Fehlerquelle ist das Vermischen von TLS- und HTTP-Authentifizierung:

  • mTLS gehört in den Tab Zertifikate.
  • API-Keys, Bearer-Tokens, OAuth und Basic Auth gehören in den Tab Autorisierung einer Anfrage, eines Ordners oder einer Sammlung.

Anfragen können Autorisierungseinstellungen von übergeordneten Ordnern oder Sammlungen erben. Das Client-Zertifikat wird dagegen ausschließlich anhand des Hosts ausgewählt.

Weitere Details zur tokenbasierten Anfrageseite finden Sie im Leitfaden zur API-Gateway-Authentifizierung. Für Windows-lastige Umgebungen ist auch die Anleitung zur Konfiguration der Kerberos-Authentifizierung in Apidog relevant.

mTLS funktioniert nur mit HTTPS

Apidog hängt kein Client-Zertifikat an einfache HTTP-Anfragen an.

Diese URL löst keinen TLS-Handshake aus:

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

Verwenden Sie immer HTTPS:

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

Den Workflow mit der Apidog CLI automatisieren

Sobald Ihre mTLS-Anfragen manuell funktionieren, können Sie gespeicherte Szenarien in einer CI/CD-Pipeline ausführen. Installieren Sie dazu die Apidog CLI und authentifizieren Sie sich:

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

Führen Sie anschließend ein gespeichertes Szenario in einer Umgebung aus:

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

Die CLI unterstützt Client-Zertifikate direkt. Relevante Optionen sind:

Option Zweck
--ssl-client-cert PEM-Client-Zertifikat
--ssl-client-key Privater Schlüssel
--ssl-client-passphrase Passphrase für den Schlüssel
--ssl-extra-ca-certs Zusätzliche vertrauenswürdige CAs
--ssl-client-cert-list Zertifikatskonfiguration für URL-Muster
-r html,cli Mehrere Reporter aktivieren

Beispiel mit Zertifikat, Schlüssel und zusätzlicher CA:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "<scenario_id>" \
  -e "<env_id>" \
  --ssl-client-cert "./certs/client.pem" \
  --ssl-client-key "./certs/client-key.pem" \
  --ssl-extra-ca-certs "./certs/internal-ca.pem" \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

So bleibt Ihre mTLS-Konfiguration auch außerhalb der GUI reproduzierbar. Für die Pipeline-Integration hilft der Leitfaden Apidog CLI in CI/CD.

Häufig gestellte Fragen

Brauche ich ein Client-Zertifikat und ein CA-Zertifikat oder nur eines?

Das hängt vom Zielsystem ab:

  • Sie benötigen ein Client-Zertifikat, wenn der Server mTLS verlangt.
  • Sie benötigen ein CA-Zertifikat, wenn das Serverzertifikat von einer CA stammt, der Ihre Maschine bzw. Apidog noch nicht vertraut.

Eine öffentliche Partner-API mit öffentlich vertrauenswürdiger CA benötigt häufig nur das Client-Zertifikat. Ein interner mTLS-Dienst mit privater Root-CA benötigt meist beides.

Warum sendet Apidog mein Client-Zertifikat nicht?

Prüfen Sie diese Punkte:

  1. Das Feld Host enthält die korrekte Domain ohne https://.
  2. Der konfigurierte Port stimmt mit dem Ziel überein.
  3. Bei abweichenden Ports wie 8443 oder 9443 ist der Port explizit gesetzt.
  4. Die Anfrage verwendet https://, nicht http://.
  5. Das Host-Muster deckt die aufgerufene Subdomain ab.

Wo konfiguriere ich API-Schlüssel und Bearer-Tokens?

Nicht im Zertifikatsbereich. Verwenden Sie den Tab Autorisierung der Anfrage, des Ordners oder der Sammlung.

  • Zertifikate: TLS-Identität und mTLS
  • Autorisierung: API-Keys, Bearer-Tokens, OAuth und Basic Auth

Eine Übersicht der verfügbaren Verfahren finden Sie im Leitfaden zu Sicherheitsschemata.

Kann ein Zertifikat mehrere Subdomains abdecken?

Ja. Verwenden Sie im Host-Feld ein Muster:

*.example.com
Enter fullscreen mode Exit fullscreen mode

Damit gilt dieselbe Zertifikatsbindung für alle Subdomains von example.com.

Wie aktualisiere ich ein bestehendes Zertifikat?

Zertifikate sind nicht direkt bearbeitbar:

  1. Löschen Sie den bestehenden Eintrag.
  2. Fügen Sie das erneuerte oder korrigierte Zertifikat erneut hinzu.

Für die Organisation gemeinsamer Umgebungswerte passt außerdem der Leitfaden zum Setzen globaler Parameter in Apidog.

Zusammenfassung

Eine mTLS-geschützte API testen Sie in Apidog in drei Schritten:

  1. Binden Sie ein Client-Zertifikat an den richtigen Host.
  2. Hinterlegen Sie ein CA-Zertifikat, wenn der Server eine private oder selbstsignierte Root verwendet.
  3. Senden Sie HTTPS-Anfragen; Apidog übernimmt die Zertifikatsauswahl über das Host-Matching.

Halten Sie TLS-Zertifikate und HTTP-Autorisierung getrennt konfiguriert. Dann wird aus einem schwer nachvollziehbaren Handshake-Fehler ein reproduzierbarer Setup-Schritt.

Laden Sie Apidog herunter, fügen Sie das Zertifikat Ihres Partners hinzu und senden Sie Ihre erste mTLS-authentifizierte Anfrage. Testen Sie es kostenlos, keine Kreditkarte erforderlich.

Top comments (0)