mTLS

Available on requestContact your Bird representative to enable it for your organization.

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.

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.

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.

Der Modus gilt für den folgenden Datenverkehr. Alles andere funktioniert in jedem Modus weiter.

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.
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:

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 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 ab.

Der gehostete MCP-Server kann den Workspace nicht erreichen. Verwenden Sie stattdessen den lokalen MCP-Server der Bird CLI.

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 und ihr lokaler MCP-Server (bird mcp) legen Ihr Client-Zertifikat mit diesen Einstellungen vor:

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.

// 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);

import os

from bird import Bird

# client_cert and client_key also fall back to BIRD_CLIENT_CERT and BIRD_CLIENT_KEY.
client = Bird(
    api_key=os.environ["BIRD_API_KEY"],
    client_cert="client.pem",
    client_key="client.key",
)

workspace = client.workspace.get()
print(workspace.id)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(
		option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
		option.WithClientCertificate("client.pem", "client.key"),
	)
	if err != nil {
		log.Fatal(err)
	}
	workspace, err := client.Workspace.Get(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(workspace.Id)
}

<?php

require __DIR__ . '/vendor/autoload.php';

$bird = new MessageBird\Bird(
    getenv('BIRD_API_KEY') ?: '',
    clientCert: 'client.pem',
    clientKey: 'client.key',
);

echo $bird->workspace->get()->getId(), PHP_EOL;

Client-Zertifikat bei Webhook-Zustellungen vorlegen

Wir erzeugen ein RSA-2048-Schlüsselpaar und eine CSR mit dem Subject CN=<workspace ID>, 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

Zertifikat signieren und hochladen

1. Öffnen Sie 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=<workspace ID> 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 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, 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 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 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.

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.

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:

Eine Änderung der Einstellungen kann einen dieser Codes zurückgeben:

• E10027: API-mTLS ist für den Workspace nicht aktiviert. Wenden Sie sich an Ihre Ansprechperson bei Bird, um es zu aktivieren.
• 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: API-Schlüssel, Scopes und Servicekonten
• Webhooks & Events: Endpunkte erstellen und Signaturen prüfen
• Fehler: die Fehlerantwort und ihre Behandlung