--- title: "mTLS" description: "Verlangen Sie bei API-Anfragen über den mTLS-Endpunkt ein Client-Zertifikat, und legen Sie bei Webhook-Zustellungen an Ihre Empfänger ein Client-Zertifikat vor." canonical: "https://bird.com/de-de/dokumentation/guides/mtls" availability: "on-request" --- # mTLS Mutual TLS (mTLS) ergänzt den TLS-Handshake in beide Richtungen um eine Zertifikatsprüfung. Jede Richtung hat eigene Einstellungen. Sie können eine Richtung oder beide einrichten. | Richtung | TLS-Client | TLS-Server | Einstellungen | | -------------------- | ------------ | ----------------- | ------------------------------------------------------------------------------- | | API-Anfragen | Ihre Systeme | Der mTLS-Endpunkt | [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls) | | Webhook-Zustellungen | Wir | Ihre Empfänger | [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls) | Jede Seite behält ihre eigenen privaten Schlüssel. Für API-Anfragen geben Sie uns das öffentliche Zertifikat Ihrer Zertifizierungsstelle (CA). Für Webhook-Zustellungen geben wir Ihnen eine Zertifikatsignierungsanforderung (CSR), und Sie senden uns das signierte öffentliche Zertifikat zurück. ## Bevor Sie beginnen - Wenden Sie sich an Ihre Ansprechperson bei Bird, um API-mTLS, Webhook-mTLS oder beides für Ihre Organisation zu aktivieren. Jede Richtung wird separat aktiviert. - Lassen Sie sich im Workspace eine Rolle mit Schreibzugriff auf den Scope `access_restrictions` zuweisen. Um Webhook-Testereignisse zu senden, benötigen Sie zusätzlich Schreibzugriff auf den Scope `webhooks`. - Besorgen Sie für API-Anfragen das PEM-Zertifikat der CA, die Ihre Client-Zertifikate ausstellt. Verwenden Sie lieber die ausstellende CA als die Root-CA: Die Kettenprüfung akzeptiert jedes Zertifikat, dessen Kette zu einer registrierten CA führt, daher lässt eine Root-CA auch die Zertifikate ihrer anderen ausstellenden CAs zu. Jedes Zertifikat muss trotzdem die übrigen Prüfungen bestehen, etwa die erweiterte Schlüsselverwendung `clientAuth`. - Stellen Sie für Webhook-Zustellungen eine CA bereit, die eine CSR mit der erweiterten Schlüsselverwendung `clientAuth` signieren kann. ## Client-Zertifikate für API-Anfragen verlangen Jede Region hat einen mTLS-Endpunkt. Er bietet dieselben Operationen wie der Standard-Endpunkt und verlangt von jedem Client ein Zertifikat. | Region | Standard-Endpunkt | mTLS-Endpunkt | | ------ | ------------------------------- | ------------------------------------ | | `eu1` | `https://eu1.platform.bird.com` | `https://mtls.eu1.platform.bird.com` | | `us1` | `https://us1.platform.bird.com` | `https://mtls.us1.platform.bird.com` | Das Client-Zertifikat ersetzt Ihre Anmeldedaten nicht. Jede Anfrage sendet weiterhin einen API-Schlüssel, ein OAuth-Token oder ein Servicekonto-Token im Header `Authorization`. Der Modus ist eine Workspace-Einstellung. Er legt fest, welcher Endpunkt Anfragen für den Workspace mit einem API-Schlüssel, einem OAuth-Token oder einem Servicekonto-Token akzeptiert. | Modus | Standard-Endpunkt | mTLS-Endpunkt | | ------------ | ------------------- | -------------------------------------------------------- | | `disabled` | Akzeptiert Anfragen | Lehnt Anfragen ab | | `evaluating` | Akzeptiert Anfragen | Akzeptiert Anfragen mit einem gültigen Client-Zertifikat | | `enforced` | Lehnt Anfragen ab | Akzeptiert Anfragen mit einem gültigen Client-Zertifikat | Der Modus gilt für den folgenden Datenverkehr. Alles andere funktioniert in jedem Modus weiter. | Datenverkehr | Modus `enforced` | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | API-Anfragen mit einem API-Schlüssel, einem OAuth-Token oder einem Servicekonto-Token | Der Standard-Endpunkt lehnt sie mit [`E02090`](/docs/api/errors/E02090) ab. | | Übermittlung über [SMTP](/docs/guides/email/smtp) | Abgelehnt. SMTP kann kein Client-Zertifikat vorlegen. | | Der gehostete MCP-Server | Kann den Workspace nicht erreichen. Er kann Ihr Client-Zertifikat nicht vorlegen. | | Dashboard-Sitzungen | Nicht betroffen. | | Automations | Nicht betroffen. | | Anfragen mit Anmeldedaten der Organisation an Organisationsoperationen | Nicht geprüft. Der Modus gehört zu einem Workspace, und diese Anfragen nennen keinen. | | [SIP-Trunks](/docs/guides/voice/sip-trunks) | Nicht betroffen. Ein Trunk authentifiziert Anrufe weiterhin mit einem zugelassenen API-Schlüssel, ohne Zertifikat. | Eine Änderung des Modus gilt sofort für neue Anfragen. Eine offene SMTP-Sitzung erhält den neuen Modus bei ihrer nächsten Nachricht. Ein gültiges Clientzertifikat führt über seine Zertifikatskette zu einer CA des Workspace, liegt in seinem Gültigkeitszeitraum und hat die erweiterte Schlüsselverwendung `clientAuth`. Wenn Sie einen erforderlichen alternativen Antragstellernamen (SAN) festlegen, muss das Zertifikat ihn ebenfalls enthalten. Wir vergleichen DNS-Namen und URIs. Den Common Name verwenden wir nicht. ### Zertifizierungsstelle hinzufügen 1. Öffnen Sie [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls). 2. Wählen Sie unter **Certificate authorities** die Option **Add certificate authority**. 3. Fügen Sie das PEM-Zertifikat Ihrer CA ein, oder wählen Sie eine Datei aus. 4. Wählen Sie **Add certificate authority**. Das Zertifikat muss die Basiseinschränkung `CA:true` und die Schlüsselverwendung `keyCertSign` haben und darf nicht abgelaufen sein. Ein Workspace kann zwei CAs haben. Wenn Ihre CA auch Zertifikate für andere Parteien ausstellt, setzen Sie **Required subject alternative name** auf die Identität, die Ihre Clientzertifikate enthalten. ### Im Evaluierungsmodus testen 1. Wählen Sie unter **Mode** die Option **Evaluating** und dann **Save**. 2. Konfigurieren Sie Ihren Client so, dass er sein Zertifikat vorlegt. Wenn eine Zwischen-CA das Clientzertifikat signiert, senden Sie auch das Zwischenzertifikat mit. 3. Ändern Sie die Basis-URL Ihres Clients auf den mTLS-Endpunkt. 4. Senden Sie eine Testanfrage: ```bash curl https://mtls.eu1.platform.bird.com/v1/workspace \ --cert client.pem \ --key client.key \ -H "Authorization: Bearer $BIRD_API_KEY" ``` Eine andere Antwort als `401` zeigt, dass die Zertifikatsprüfung bestanden wurde. Eine `401`-Antwort enthält einen Fehlercode. Unter [Fehlerbehebung](#fehlerbehebung) finden Sie die Ursache jedes Codes. Um die Aufrufer zu finden, die der Modus `enforced` ablehnen würde, filtern Sie die Anfrage-Logs des Workspace nach **mTLS** `missing`. Die Anfrage-Logs erfassen Schreibvorgänge, etwa `POST`-, `PATCH`- und `DELETE`-Anfragen, sowie SMTP-Übermittlungen. Lesevorgänge erfassen sie nicht. Prüfen Sie Clients, die nur lesen, daher separat: Der Modus `enforced` lehnt auch sie ab. ### mTLS erzwingen 1. Stellen Sie jede Integration auf den mTLS-Endpunkt um. 2. Wählen Sie unter **Mode** die Option **Enforced** und dann **Save**. Der Standard-Endpunkt lehnt jetzt Anfragen mit einem API-Schlüssel, einem OAuth-Token oder einem Servicekonto-Token für den Workspace mit [`E02090`](/docs/api/errors/E02090) ab. Der gehostete MCP-Server kann den Workspace nicht erreichen. Verwenden Sie stattdessen den lokalen MCP-Server der [Bird CLI](#bird-cli-verwenden). Der SMTP-Endpunkt verweigert AUTH für den Workspace mit `535 5.7.8`. Eine offene SMTP-Sitzung erhält bei ihrer nächsten Nachricht `530 5.7.0`. Senden Sie E-Mails stattdessen über die API am mTLS-Endpunkt. Eine Änderung an den CAs oder am erforderlichen SAN kann bis zu 15 Minuten dauern, bis sie für jede Anfrage gilt. ### Bird CLI verwenden Die [Bird CLI](/docs/cli) und ihr lokaler MCP-Server (`bird mcp`) legen Ihr Client-Zertifikat mit diesen Einstellungen vor: | Einstellung | Flag | Umgebungsvariable | | --------------------------------------------- | --------------- | ------------------ | | Zertifikatskette, PEM, Leaf-Zertifikat zuerst | `--client-cert` | `BIRD_CLIENT_CERT` | | Privater Schlüssel, PEM, unverschlüsselt | `--client-key` | `BIRD_CLIENT_KEY` | | Anfragen an den mTLS-Endpunkt senden | `--mtls` | `BIRD_MTLS=1` | ```bash export BIRD_API_KEY=bk_eu1_... export BIRD_CLIENT_CERT=client.pem export BIRD_CLIENT_KEY=client.key bird workspace get --mtls ``` Um die Einstellungen mit einer OAuth-Anmeldung zu speichern, übergeben Sie die drei Flags an `bird auth login`. Das Profil speichert die Dateipfade, und spätere Befehle verwenden den mTLS-Endpunkt ohne Flags. `bird auth status` zeigt den SHA-256-Fingerabdruck und das Ablaufdatum des Zertifikats an. ### Ein SDK verwenden Übergeben Sie dem SDK die Pfade Ihrer Zertifikatskette (PEM, Leaf-Zertifikat zuerst) und ihres privaten Schlüssels (PEM, unverschlüsselt). Das SDK legt das Zertifikat bei jeder Anfrage vor und sendet Anfragen an den mTLS-Endpunkt der Region Ihres API-Schlüssels. Wenn Sie eine Basis-URL festlegen, verwendet das SDK diese URL. Das SDK lehnt ein Zertifikat zusammen mit einem HTTP-Client ab, den Sie selbst bereitstellen. Um Ihren eigenen HTTP-Client zu verwenden, konfigurieren Sie das Zertifikat auf diesem Client und setzen Sie die Basis-URL auf den mTLS-Endpunkt. **TypeScript** ```typescript // Node.js only. Install the optional undici dependency if your package manager skipped it. import { BirdClient } from "@messagebird/sdk"; const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY!, clientCertificate: { cert: "client.pem", key: "client.key" }, }); const workspace = await bird.workspace.get(); console.log(workspace.id); ``` Examples: [TypeScript](/de-de/dokumentation/guides/mtls.ts.md) · [Python](/de-de/dokumentation/guides/mtls.py.md) · [Go](/de-de/dokumentation/guides/mtls.go.md) · [PHP](/de-de/dokumentation/guides/mtls.php.md) ## Client-Zertifikat bei Webhook-Zustellungen vorlegen Wir erzeugen ein RSA-2048-Schlüsselpaar und eine CSR mit dem Subject `CN=, O=Bird`. Der private Schlüssel bleibt bei uns. Ihre CA signiert die CSR, und wir legen das signierte Zertifikat vor, wenn Ihr Empfänger eines anfordert. Wir legen das Zertifikat bei Webhook-Abonnements und direkten Callbacks vor, auch bei erneuten Versuchen. Bei diesen Zustellungen legen wir es nicht vor: - `realtime.*`-Events - Connector-Endpunkte - MCP-Events-Abonnements | Modus | Zustellverhalten | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `disabled` | Wir legen kein Zertifikat vor. | | `evaluating` | Wir legen das Zertifikat vor, wenn der Empfänger eines anfordert. Lehnt der Empfänger es ab, stellen wir erneut ohne Zertifikat zu. | | `enforced` | Wir legen das Zertifikat vor. Fordert der Empfänger es nicht an oder lehnt er es ab, schlägt der Zustellversuch fehl. | ### Zertifikat signieren und hochladen 1. Öffnen Sie [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls). 2. Wählen Sie unter **Certificate** die Option **Create signing request**. 3. Wählen Sie unter **Signing request** die Option **Download**. 4. Lassen Sie den CSR von Ihrer CA mit der erweiterten Schlüsselverwendung `clientAuth` signieren. 5. Wählen Sie **Upload certificate**. 6. Fügen Sie zuerst das signierte Zertifikat ein, danach jedes Zwischenzertifikat in der richtigen Reihenfolge. Sie können auch eine Datei auswählen. 7. Wählen Sie **Upload certificate**. Wir prüfen, ob das Zertifikat zum Schlüssel der Signieranforderung passt, die erweiterte Schlüsselverwendung `clientAuth` hat und sich in seinem Gültigkeitszeitraum befindet. Der Abschnitt **Certificate** zeigt danach Subject, Aussteller, Seriennummer, SHA-256-Fingerabdruck und Gültigkeitszeitraum an. ### Empfänger konfigurieren 1. Fordern Sie während des TLS-Handshakes ein Client-Zertifikat an. 2. Vertrauen Sie der CA, die unser Zertifikat signiert hat. 3. Präsentieren Sie ein Serverzertifikat einer öffentlich vertrauenswürdigen CA, das zum Hostnamen des Empfängers passt. Um nur unser Zertifikat und kein anderes Zertifikat Ihrer CA zu akzeptieren, prüfen Sie auf das Subject `CN=` oder den SHA-256-Fingerabdruck. ### Webhook-mTLS erzwingen 1. Wählen Sie unter **Mode** die Option **Evaluating** aus und dann **Save**. 2. Senden Sie mit [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook) ein Testereignis an jeden Webhook. Stellen Sie sicher, dass `client_certificate` den Wert `presented` hat. `not_requested` bedeutet, dass der Empfänger das Zertifikat nicht angefordert hat, und `rejected` bedeutet, dass er es nicht akzeptiert hat. 3. Für [SMS-Callback-URLs](/docs/guides/sms/callbacks), die keine Webhook-ID haben, senden Sie eine SMS, bei der `options.callback_url` auf den Empfänger gesetzt ist. Prüfen Sie die Logs des Empfängers und stellen Sie sicher, dass der Callback unser Zertifikat vorlegt. Im Modus `evaluating` erscheint ein abgelehntes Zertifikat außerdem in [`GET /v1/webhook-callbacks/attempts`](/docs/api/reference/list-webhook-callback-attempts) als fehlgeschlagener Versuch mit `failure_reason`. 4. Wählen Sie unter **Mode** die Option **Enforced** aus und dann **Save**. Im Modus `enforced` erscheint ein abgelehntes Zertifikat als fehlgeschlagener Versuch in den [Zustellversuchen](/docs/guides/webhooks#replaying-failed-deliveries) des Webhooks. ## Sperrstatus prüfen Setzen Sie **Certificate revocation list check** auf **Full chain**, um den Sperrstatus anhand von Zertifikatsperrlisten (CRLs) zu prüfen. - Bei API-Anfragen prüfen wir das Client-Zertifikat und jedes Zwischenzertifikat unterhalb Ihrer CA. - Bei Webhook-Zustellungen prüfen wir das Serverzertifikat Ihres Empfängers und jedes Zwischenzertifikat unterhalb seiner Root-CA. Wir prüfen jeden CRL-Verteilungspunkt des Zertifikats. Die `http`- und `https`-URIs eines Verteilungspunkts sind Spiegel derselben CRL, und wir verwenden den ersten Spiegel, der antwortet. Ein Verteilungspunkt ohne `http`- oder `https`-URI lässt die Prüfung fehlschlagen. Ein Zertifikat ohne CRL-Verteilungspunkte wird nicht geprüft. Wir verifizieren die Signatur jeder CRL. Wenn wir keine gültige CRL abrufen können, lehnen wir die Anfrage ab oder der Zustellversuch schlägt fehl. | Limit | Wert | | --------------------- | --------------------------------------------------- | | Downloadzeit für CRLs | 5 Sekunden pro Download, 10 Sekunden pro Anfrage | | Größe einer CRL | 10 MiB | | CRLs pro Workspace | 10 für API-Anfragen und 10 für Webhook-Zustellungen | ## Zertifikate rotieren Wir senden den Kontakten des Workspace 30 Tage und 7 Tage vor dem Ablauf einer CA oder des Webhook-Client-Zertifikats eine E-Mail. So rotieren Sie die CA für API-Anfragen: 1. Fügen Sie die neue CA hinzu. Der Workspace vertraut dann beiden CAs. 2. Stellen Sie jede Integration auf ein Client-Zertifikat der neuen CA um. 3. Entfernen Sie die alte CA. Solange der Modus `evaluating` oder `enforced` ist, können Sie die letzte CA nicht entfernen. Im Modus Bird müssen Sie für Client-Zertifikate Ihrer CA nichts tun. So rotieren Sie das Webhook-Client-Zertifikat: 1. Wählen Sie **Create new signing request**. 2. Lassen Sie den neuen CSR signieren und laden Sie das Zertifikat hoch. Das aktuelle Zertifikat bleibt in Gebrauch, bis Sie das neue hochladen. Testsendungen verwenden das neue Zertifikat sofort, Zustellungen können das vorherige jedoch noch bis zu einige Minuten lang vorlegen. Bis dahin müssen Ihre Empfänger beide Zertifikate akzeptieren, entweder über die CA oder über den Fingerabdruck. ## Mit der API automatisieren Für jede Aktion im Dashboard gibt es eine API-Operation. Senden Sie diese Aufrufe an einen Endpunkt, den Ihr Modus akzeptiert: im Modus `disabled` oder `evaluating` an den Standard-Endpunkt, im Modus `enforced` mit einem Client-Zertifikat an den mTLS-Endpunkt. Der API-Schlüssel benötigt Schreibzugriff auf den Scope `access_restrictions`. Master-Schlüssel der Organisation können diese Operationen nicht verwenden. | Operation | Aktion | | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [`PATCH /v1/workspace/mtls-settings`](/docs/api/reference/update-workspace-mtls-settings) | `state`, `expected_san` oder `crl_check` ändern | | [`POST /v1/workspace/mtls-certificate-authorities`](/docs/api/reference/create-workspace-mtls-certificate-authority) | Eine CA hinzufügen | | [`DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}`](/docs/api/reference/delete-workspace-mtls-certificate-authority) | Eine CA entfernen | | [`PATCH /v1/workspace/webhook-client-certificate`](/docs/api/reference/update-workspace-webhook-client-certificate) | `state` oder `crl_check` ändern | | [`POST /v1/workspace/webhook-client-certificate/signing-request`](/docs/api/reference/create-workspace-webhook-client-certificate-signing-request) | Eine CSR erstellen | | [`POST /v1/workspace/webhook-client-certificate/certificate`](/docs/api/reference/submit-workspace-webhook-client-certificate) | Das signierte Zertifikat hochladen | ```bash curl -X PATCH https://eu1.platform.bird.com/v1/workspace/mtls-settings \ -H "Authorization: Bearer $BIRD_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"state": "enforced", "crl_check": "full_chain"}' ``` ## Fehlerbehebung API-Anfragen, die eine Prüfung nicht bestehen, geben `401` mit einem dieser Codes zurück: | Code | Ursache | | ----------------------------------- | -------------------------------------------------------------------------------------------------- | | [`E02086`](/docs/api/errors/E02086) | Die Anfrage hat kein Client-Zertifikat vorgelegt. | | [`E02087`](/docs/api/errors/E02087) | Das Client-Zertifikat ist für den Workspace nicht gültig. | | [`E02088`](/docs/api/errors/E02088) | Ein Zertifikat in der Kette ist widerrufen. | | [`E02089`](/docs/api/errors/E02089) | Der Modus ist `disabled`, daher lehnt der mTLS-Endpunkt die Anfrage ab. | | [`E02090`](/docs/api/errors/E02090) | Der Modus ist `enforced`, daher lehnt der Standard-Endpunkt die Anfrage ab. | | [`E02091`](/docs/api/errors/E02091) | Wir konnten eine CRL nicht innerhalb von 5 Sekunden herunterladen. | | [`E02092`](/docs/api/errors/E02092) | Eine CRL ist größer als 10 MiB. | | [`E02093`](/docs/api/errors/E02093) | Der Workspace verwendet bereits 10 CRLs. | | [`E02094`](/docs/api/errors/E02094) | Eine CRL hat eine ungültige Signatur oder ihr nächster Aktualisierungszeitpunkt ist überschritten. | Eine Änderung der Einstellungen kann einen dieser Codes zurückgeben: - [`E10027`](/docs/api/errors/E10027): API-mTLS ist für den Workspace nicht aktiviert. Wenden Sie sich an Ihre Ansprechperson bei Bird, um es zu aktivieren. - [`E10028`](/docs/api/errors/E10028): Webhook-mTLS ist für den Workspace nicht aktiviert. Wenden Sie sich an Ihre Ansprechperson bei Bird, um es zu aktivieren. ## Nächste Schritte - [Authentifizierung](/docs/guides/authentication): API-Schlüssel, Scopes und Servicekonten - [Webhooks & Events](/docs/guides/webhooks): Endpunkte erstellen und Signaturen prüfen - [Fehler](/docs/guides/errors): die Fehlerantwort und ihre Behandlung ## Related resources - [Webhooks done right: reliable delivery events](/learn/basics/webhooks-done-right-reliable-delivery-events) (video) - [How do I verify a webhook signature?](/explained/platform/how-do-i-verify-a-webhook-signature) (answer) - [SMTP relay](/email-api/features/smtp) (product) - [Operate messaging reliably](/learn/paths/reliability) (course)