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 werden trotzdem mit einem TLS-Handshake-Fehler konfrontiert. Der Endpunkt fragt nicht nach Ihrem API-Schlüssel. Er verlangt von Ihrem Client, sich mit einem Zertifikat auszuweisen, noch bevor eine HTTP-Anfrage Ihre Maschine verlässt. Das ist gegenseitiges TLS (mTLS), und wenn Sie es noch nie in einem Testtool konfiguriert haben, kann es eine Integration für einen ganzen Tag aufhalten.

Dieser Leitfaden führt Sie durch die Einrichtung von Client-Zertifikaten und CA-Zertifikaten in Apidog, damit Sie eine mTLS-geschützte API testen können, ohne sich mit dem Handshake herumschlagen zu müssen. Sie fügen ein Client-Zertifikat und einen Schlüssel für einen bestimmten Host hinzu, fügen ein CA-Zertifikat an, damit selbstsignierte Roots keine Fehler mehr verursachen, und senden eine authentifizierte Anfrage, die Apidog automatisch signiert. Wenn Zertifikatsfehler Neuland für Sie sind, lohnt sich die Einführung zur SSL-Zertifikatsüberprüfung als ergänzende Lektüre. Für das Protokoll selbst ist die MDN TLS-Referenz eine solide, herstellerunabhängige Erklärung.

Button

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

Normales HTTPS ist ein Einweg-Vertrauen. Der Server präsentiert ein Zertifikat, Ihr Client überprüft es, und die Verbindung wird verschlüsselt. Der Server hat keinen kryptografischen Beweis dafür, wer Sie sind; dafür verlässt er sich auf ein Token oder einen API-Schlüssel innerhalb der Anfrage.

Gegenseitiges TLS (mTLS) macht das Vertrauen zweiseitig. Der Server präsentiert weiterhin sein Zertifikat, fordert aber auch den Client auf, eines zu präsentieren. Wenn Ihr Zertifikat nicht von einer vom Server als vertrauenswürdig eingestuften Zertifizierungsstelle signiert ist, schlägt der Handshake fehl und die Verbindung wird niemals geöffnet. Kein Anfrage-Body, keine Header, nichts kommt durch.

Sie werden auf die gegenseitige TLS (mTLS)-Authentifizierung an Orten stoßen, wo ein geleaktes Bearer-Token kein akzeptabler Fehlerfall ist:

Bankwesen und Zahlungsverkehr. Open-Banking-APIs und Kartenprozessoren verlangen oft ein Client-Zertifikat, das Ihrer Organisation zusätzlich zu OAuth ausgestellt wurde. Die Stripe-Dokumentation beschreibt diese Art von mehrschichtigem Anmeldeinformationsmodell für sensible Finanzendpunkte.
Interner und Service-zu-Service-Verkehr. Unternehmen, die ein Zero-Trust-Netzwerk betreiben, lassen Dienste ihre Identität mit Zertifikaten nachweisen, anstatt der Netzwerkperipherie zu vertrauen.
B2B-Partner-APIs. Ein Partner kann Ihnen während des Onboardings ein Client-Zertifikat ausstellen, sodass nur Ihre registrierten Maschinen deren Endpunkte erreichen können.

Wenn OAuth ebenfalls im Spiel ist, lassen sich die beiden sauber kombinieren; RFC 8705 formalisiert, wie gegenseitiges TLS ein OAuth-Token an ein Client-Zertifikat bindet. Das Zertifikat ist eine netzwerkschichtige Anmeldeinformation, getrennt von der anwendungsschichtigen Authentifizierung in Ihrer Anfrage. Diese Unterscheidung ist in Apidog wichtig und das, worin sich die Leute am häufigsten verfangen. Zertifikate handhaben mTLS. Der Tab Authentifizierung handhabt API-Schlüssel, Bearer-Tokens, OAuth und Basic Auth. Sie benötigen oft beides gleichzeitig, konfigurieren es aber an verschiedenen Stellen.

Wie Apidog Zertifikate nach Hostbereich festlegt

Apidog verarbeitet sowohl CA-Zertifikate als auch Client-Zertifikate und konfiguriert sie global statt pro Anfrage. Sie richten ein Zertifikat einmal ein, verknüpfen es mit einem Host, und Apidog hängt es automatisch an jede HTTPS-Anfrage an, die mit diesem Host übereinstimmt. Es gibt keinen Umschalter pro Anfrage, an den man sich erinnern müsste, und keinen Header zum Einfügen.

Zwei Zertifikatstypen erfüllen zwei verschiedene Aufgaben:

Ein Client-Zertifikat ist das, was Sie vorlegen, um Ihre Identität für die gegenseitige TLS-Authentifizierung zu beweisen. Es ist die Anmeldeinformation, die die Partner-API anfordert.
Ein CA-Zertifikat weist Apidog an, einer Zertifizierungsstelle zu vertrauen, die es noch nicht kennt. Verweisen Sie es auf Ihre interne Stamm-CA, und der gefürchtete Fehler SSL Error: Self signed certificate verschwindet, da Apidog nun Endpunkten vertraut, die von dieser Behörde signiert wurden.

Der Bereichsschlüssel ist der Host. Jedes Client-Zertifikat ist an eine Domäne gebunden, und Apidog gleicht den Host der ausgehenden Anfrage mit dieser Bindung ab. Wenn der Host korrekt ist, läuft alles andere automatisch. Ist er falsch, sendet Apidog stillschweigend nichts, weil es keine Übereinstimmung gefunden hat.

Einrichten eines Client-Zertifikats für eine mTLS-API

Hier ist das Szenario. Ein Zahlungspartner, partner-api.acmebank.com, hat Ihnen während des Onboardings ein Client-Zertifikat und einen privaten Schlüssel ausgestellt. Ihre API ist nur HTTPS und lehnt jeden Client ab, der dieses Zertifikat nicht vorlegen kann. Sie möchten GET /v1/settlements aufrufen und die Antwort überprüfen.

Schritt 1: Die Zertifikatseinstellungen öffnen

Öffnen Sie die Apidog-Einstellungen über das Einstellungssymbol oben rechts und wechseln Sie dann zum Tab Zertifikate. Hier befinden sich beide Zertifikatstypen. Nichts davon ist an eine einzelne Anfrage gebunden; es gilt für alle Ihre Anfragen basierend auf dem Host-Matching.

Schritt 2: Das Client-Zertifikat hinzufügen

Wählen Sie unter Client-Zertifikate die Option Zertifikat hinzufügen. Es öffnet sich ein Formular für die Host-Bindung und die Zertifikatsdateien.

Füllen Sie das Feld Host nur mit der Domäne aus, ohne Protokoll:

partner-api.acmebank.com

Lassen Sie https:// weg. Das Feld nimmt eine reine Domäne auf. Wenn Sie ein Zertifikat für mehrere Subdomains benötigen, unterstützt das Host-Feld Mustererkennung. Die Eingabe von *.acmebank.com verwendet dasselbe Client-Zertifikat für jede Subdomain unter acmebank.com, was praktisch ist, wenn ein Partner partner-api, sandbox-api und settlements-api mit demselben ausgestellten Zertifikat betreibt.

Ein benutzerdefinierter Port ist optional. Lassen Sie ihn leer, und Apidog verwendet standardmäßig 443, den Standard-HTTPS-Port. Legen Sie einen Port nur fest, wenn der mTLS-Endpunkt an einer anderen Stelle lauscht, z.B. 8443.

Schritt 3: Die Zertifikatsdateien auswählen

Apidog akzeptiert zwei Dateiformate für ein Client-Zertifikat. Wählen Sie das aus, das Ihr Partner Ihnen gegeben hat:

CRT + Schlüsseldateien. Eine separate Zertifikatsdatei und eine private Schlüsseldatei. Wählen Sie jede in ihrem Feld aus.
PFX-Dateien. Eine einzelne gebündelte Datei, die Zertifikat und Schlüssel zusammenpackt.

Wenn das Zertifikat mit einer Passphrase generiert wurde, geben Sie diese in das Feld Passphrase ein. Es ist optional, lassen Sie es also leer, wenn Ihr Schlüssel nicht passwortgeschützt ist. Ein typisches Onboarding-Paket einer Bank wird als .crt- und .key-Paar geliefert, manchmal mit einer Passphrase auf dem Schlüssel.

Schritt 4: Speichern

Wählen Sie Hinzufügen, um das Client-Zertifikat zu speichern. Es erscheint nun in Ihrer Liste, gebunden an partner-api.acmebank.com. Von diesem Zeitpunkt an müssen Sie es pro Anfrage nicht mehr anfassen.

Schritt 5: Senden der authentifizierten Anfrage

Erstellen Sie eine Anfrage an den Host und senden Sie sie:

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

Apidog gleicht den Host ab, hängt Ihr Client-Zertifikat während des TLS-Handshakes an und schließt die gegenseitige TLS-Authentifizierung ab, bevor die Anfrage gesendet wird. Wenn der Partner auch OAuth erfordert, wird das Bearer-Token wie gewohnt in der Anfrage mitgeführt. Das Zertifikat beweist die Maschine; das Token beweist den Anrufer. 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
}

Kein manueller Schritt pro Anfrage hat das bewirkt. Das Host-Matching hat es getan.

Hinzufügen eines CA-Zertifikats für interne oder selbstsignierte Roots

Client-Zertifikate sind die halbe Miete. Die andere Hälfte tritt in Erscheinung, wenn das eigene Zertifikat des Servers von einer Autorität signiert ist, der Ihre Maschine nicht vertraut, was bei internen Diensten und Staging-Umgebungen, die eine private Root-CA verwenden, üblich ist.

In diesem Fall schlägt die Anfrage mit einer Meldung wie SSL Error: Self signed certificate fehl, noch bevor mTLS überhaupt eine Chance bekommt. Die Lösung besteht darin, Apidog die CA zu übergeben, damit es dieser Root vertraut.

Im selben Tab Zertifikate aktivieren Sie den Schalter neben CA-Zertifikate und wählen dann Ihre PEM-Datei aus. CA-Zertifikate verwenden das PEM-Format, und eine einzelne PEM-Datei kann mehrere CA-Zertifikate enthalten, sodass Sie eine ganze Kette interner Roots und Intermediate-Zertifikate in einer Datei bündeln können:

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

Sobald die CA als vertrauenswürdig eingestuft ist, lehnt Apidog keine Endpunkte mehr ab, die von ihr signiert wurden. Kombinieren Sie eine vertrauenswürdige CA mit einem Client-Zertifikat, und Sie können einen internen mTLS-Dienst, der einen privaten Root verwendet, End-to-End testen: Die CA lässt Sie ihrem Server vertrauen, und das Client-Zertifikat lässt sie Ihnen vertrauen.

Erweiterte Tipps und häufige Varianten

Einige Dinge sparen Zeit, sobald Sie die Grundeinrichtung hinter sich haben.

Subdomain-Abdeckung mit einem Zertifikat. Wenn ein Partner ein Wildcard-Zertifikat ausgestellt hat, stellen Sie den Host einmal auf *.acmebank.com ein, anstatt partner-api, sandbox-api und den Rest separat zu registrieren. Eine Bindung, jede Subdomain.
Nicht-Standard-Ports. Interne mTLS-Gateways lieben Ports wie 8443 oder 9443. Der Standard ist 443, also geben Sie den benutzerdefinierten Port an, wann immer der Endpunkt woanders lauscht, sonst passt der Host nicht und es wird kein Zertifikat gesendet.
Zertifikate sind nach dem Hinzufügen nicht bearbeitbar. Es gibt keine Bearbeitungsaktion. Um ein erneuertes Zertifikat zu rotieren oder einen Tippfehler im Host zu korrigieren, entfernen Sie das vorhandene mit dem Löschen-Symbol und fügen Sie es erneut hinzu. Bauen Sie dies in Ihr Zertifikatsrotations-Handbuch ein, damit niemand nach einem Bearbeiten-Button sucht, der nicht vorhanden ist.
Ein Zertifikat pro Domäne. Registrieren Sie keine zwei Client-Zertifikate für dieselbe Domäne. Jede Bindung ist domänenspezifisch, und ein Duplikat schafft Unklarheit darüber, welches Apidog präsentieren soll. Beschränken Sie es auf eines pro Host.
Halten Sie Zertifikate und Autorisierung in Ihrem Kopf getrennt. Dies ist die größte Quelle für Verwirrung. mTLS befindet sich im Tab Zertifikate. API-Schlüssel, Bearer-Tokens, OAuth und Basic Auth befinden sich im Tab Autorisierung einer Anfrage oder eines Ordners, und Anfragen erben die Autorisierung von ihrem übergeordneten Ordner. Die Autorisierung gilt auf drei Ebenen: einzelne Anfragen, alle Anfragen in einem Ordner und alle Anfragen in einer Sammlung. Wenn ein Partner sowohl ein Client-Zertifikat als auch OAuth benötigt, legen Sie das Zertifikat in den Zertifikaten und das Token in der Autorisierung fest. Sie überschneiden sich nicht. Für einen tieferen Einblick in die Verkabelung der Token-basierten Authentifizierung deckt der Leitfaden zur API-Gateway-Authentifizierung die Anfrageseite ab, und wenn Sie mit einem Windows-lastigen Stack arbeiten, ist die Konfiguration der Kerberos-Authentifizierung in Apidog eine verwandte Anleitung, die es wert ist, gespeichert zu werden.
Nur HTTPS, immer. Apidog hängt kein Client-Zertifikat an eine einfache HTTP-Anfrage an. Wenn Ihr Testziel http:// ist, wird das Zertifikat niemals gesendet und die Handshake-Logik niemals ausgeführt. Der Endpunkt muss HTTPS sein, damit dies alles angewendet werden kann.

Den Workflow mit der Apidog CLI automatisieren

Sobald Ihre mTLS-Anfragen manuell durchlaufen, integrieren Sie sie in gespeicherte Testszenarien und führen Sie sie kopflos mit der Apidog CLI aus. Installieren Sie sie und authentifizieren Sie sich:

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

Führen Sie dann ein gespeichertes Szenario in einer Umgebung aus:

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

Der Befehl apidog run unterstützt die Client-Zertifikat-Konfiguration direkt, sodass mTLS den Übergang von der GUI zur Pipeline überlebt. Für ein einzelnes Zertifikat übergeben Sie --ssl-client-cert (das PEM-Zertifikat), --ssl-client-key (den privaten Schlüssel) und --ssl-client-passphrase, falls der Schlüssel eine Passphrase besitzt. Verweisen Sie --ssl-extra-ca-certs auf zusätzliche vertrauenswürdige CAs, oder verwenden Sie --ssl-client-cert-list mit einer Konfigurationsdatei, wenn Sie Zertifikate anhand von URL-Mustern Hosts zuordnen. Reporter werden mit -r festgelegt (versuchen Sie -r html,cli). Verknüpfen Sie diesen Befehl mit einem Job, und Ihre zertifikatgeschützte API wird bei jedem Push getestet. Der Leitfaden Apidog CLI in CI/CD behandelt das Ausführen innerhalb einer Pipeline.

Häufig gestellte Fragen

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

Das hängt vom Endpunkt ab. Ein Client-Zertifikat beweist Ihre Identität, daher benötigen Sie es immer dann, wenn der Server gegenseitiges TLS verlangt. Ein CA-Zertifikat wird nur benötigt, wenn das eigene Zertifikat des Servers von einer Autorität signiert ist, der Ihre Maschine noch nicht vertraut, wie z.B. einer internen Root-CA. Eine öffentliche Partner-API auf einer vertrauenswürdigen öffentlichen CA benötigt nur das Client-Zertifikat; ein interner mTLS-Dienst auf einem privaten Root benötigt normalerweise beides.

Warum sendet Apidog mein Client-Zertifikat nicht?

Fast immer ein Host-Fehler oder ein einfaches HTTP-Ziel. Überprüfen Sie, ob das Feld Host die genaue Domäne ohne https:// Präfix enthält, ob der Port übereinstimmt (Standard 443, also einen benutzerdefinierten Port einstellen, wenn der Endpunkt woanders lauscht), und ob die Anforderungs-URL HTTPS ist. Apidog hängt niemals ein Zertifikat an eine HTTP-Anfrage an.

Wo werden API-Schlüssel und Bearer-Tokens abgelegt, wenn nicht in den Zertifikaten?

Im Tab Autorisierung der Anfrage oder des Ordners, der von der Zertifikatseinrichtung getrennt ist. Zertifikate kümmern sich um die TLS-Schicht-Identität; Autorisierung kümmert sich um API-Schlüssel, Bearer-Token, OAuth und Basic Auth auf der Anforderungsebene. Eine vollständige Aufschlüsselung der Authentifizierungstypen finden Sie im Leitfaden zu Sicherheitsschemata, und Sie können die Authentifizierung einmal auf Ordner- oder Sammlungsebene festlegen, damit jede Anfrage sie erbt.

Kann ein Zertifikat mehrere Subdomains abdecken?

Ja. Das Host-Feld unterstützt Mustererkennung. Geben Sie *.example.com ein, und dasselbe Client-Zertifikat gilt für jede Subdomain von example.com. Das ist die saubere Methode, um ein Wildcard-Zertifikat, das ein Partner für mehrere seiner API-Subdomains ausgestellt hat, wiederzuverwenden.

Wie aktualisiere ich ein Zertifikat, nachdem es hinzugefügt wurde?

Zertifikate sind nicht direkt bearbeitbar. Entfernen Sie das vorhandene mit dem Löschen-Symbol und fügen Sie dann die korrigierte oder erneuerte Version hinzu. Denken Sie daran für die Zertifikatsrotation, und während Sie Test-Setups organisieren, passt das Setzen globaler Parameter in Apidog gut dazu, Umgebungswerte über Anfragen hinweg ordentlich zu halten.

Zusammenfassung

Das Testen einer mTLS-geschützten API läuft in Apidog auf drei Schritte hinaus: Binden Sie ein Client-Zertifikat an den richtigen Host, hängen Sie ein CA-Zertifikat an, wenn der Server eine private Root verwendet, und lassen Sie das Host-Matching jede HTTPS-Anfrage automatisch signieren. Halten Sie Zertifikate und Autorisierung in getrennten Bereichen, und der Handshake ist kein Geheimnis mehr.

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