Sign inGet Started

mTLS

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

Mutual TLS (mTLS) voegt in beide richtingen een certificaatcontrole toe aan de TLS-handshake. Elke richting heeft eigen instellingen. Je kunt één richting instellen of beide.

RichtingTLS-clientTLS-serverInstellingen
API-verzoekenJe systemenHet mTLS-endpointWorkspace settings > mTLS
WebhookleveringenWijJe ontvangersWebhooks > mTLS

Elke partij houdt haar eigen privésleutels. Voor API-verzoeken geef je ons het openbare certificaat van je certificeringsinstantie (CA). Voor webhookleveringen geven wij je een certificaatondertekeningsverzoek (CSR) en stuur je het ondertekende openbare certificaat terug.

Voordat je begint

  • Neem contact op met je Bird-vertegenwoordiger om API-mTLS, webhook-mTLS of beide voor je organisatie in te schakelen. Elke richting wordt apart ingeschakeld.
  • Zorg dat je een rol hebt met schrijftoegang tot de scope access_restrictions in de werkruimte. Om testgebeurtenissen voor webhooks te versturen, heb je ook schrijftoegang tot de scope webhooks nodig.
  • Haal voor API-verzoeken het PEM-certificaat op van de CA die je clientcertificaten uitgeeft. Kies liever de uitgevende CA dan de root-CA. De ketencontrole accepteert elk certificaat dat via een keten herleidbaar is tot een geregistreerde CA, dus met een root-CA komen ook de certificaten van de andere uitgevende CA's van die root door de controle. Elk certificaat moet nog steeds door de andere controles komen, zoals die op het uitgebreide sleutelgebruik clientAuth.
  • Zorg voor webhookleveringen voor een CA die een CSR kan ondertekenen met het uitgebreide sleutelgebruik clientAuth.

Clientcertificaten vereisen bij API-verzoeken

Elke regio heeft een mTLS-endpoint. Dit endpoint ondersteunt dezelfde bewerkingen als het standaardendpoint en vraagt elke client om een certificaat.

RegioStandaardendpointmTLS-endpoint
eu1https://eu1.platform.bird.comhttps://mtls.eu1.platform.bird.com
us1https://us1.platform.bird.comhttps://mtls.us1.platform.bird.com

Het clientcertificaat vervangt je inloggegevens niet. Elk verzoek stuurt nog steeds een API-sleutel, een OAuth-token of een serviceaccounttoken mee in de Authorization-header.

De modus is een instelling van de werkruimte. Die bepaalt welk endpoint voor de werkruimte verzoeken accepteert met een API-sleutel, een OAuth-token of een serviceaccounttoken.

ModusStandaardendpointmTLS-endpoint
disabledAccepteert verzoekenWeigert verzoeken
evaluatingAccepteert verzoekenAccepteert verzoeken met een geldig clientcertificaat
enforcedWeigert verzoekenAccepteert verzoeken met een geldig clientcertificaat

De modus geldt voor dit verkeer. Al het andere blijft in elke modus werken.

VerkeerModus enforced
API-verzoeken met een API-sleutel, een OAuth-token of een serviceaccounttokenHet standaardendpoint weigert ze met E02090.
Indienen via SMTPGeweigerd. SMTP kan geen clientcertificaat presenteren.
De gehoste MCP-serverKan de werkruimte niet bereiken. De server kan je clientcertificaat niet presenteren.
DashboardsessiesNiet beïnvloed.
AutomationsGeen invloed.
Verzoeken met inloggegevens van de organisatie bij organisatiebewerkingenNiet gecontroleerd. De modus hoort bij een werkruimte, en deze verzoeken noemen geen werkruimte.
SIP-trunksGeen invloed. Een trunk blijft gesprekken authenticeren met een toegestane API-sleutel, zonder certificaat.

Een wijziging van de modus geldt direct voor nieuwe verzoeken. Een open SMTP-sessie krijgt de nieuwe modus bij het volgende bericht.

Een geldig clientcertificaat is via een keten herleidbaar tot een CA van de werkruimte, valt binnen zijn geldigheidsperiode en heeft het uitgebreide sleutelgebruik clientAuth. Als je een verplichte subject alternative name (SAN) instelt, moet het certificaat die ook bevatten. We vergelijken DNS-namen en URI's. De common name gebruiken we niet.

Je certificaatautoriteit toevoegen

  1. Open Workspace settings > mTLS.
  2. Selecteer in Certificate authorities de optie Add certificate authority.
  3. Plak het PEM-certificaat van je CA of kies een bestand.
  4. Selecteer Add certificate authority.

Het certificaat moet de basisbeperking CA:true en het sleutelgebruik keyCertSign hebben en mag niet verlopen zijn. Een werkruimte kan twee CA's hebben.

Als je CA ook certificaten aan andere partijen uitgeeft, stel je Required subject alternative name in op de identiteit die je clientcertificaten bevatten.

Testen in de evaluatiemodus

  1. Selecteer in Mode de optie Evaluating en selecteer daarna Save.
  2. Configureer je client zodat die zijn certificaat aanbiedt. Als een tussenliggende CA het clientcertificaat ondertekent, stuur je ook het tussenliggende certificaat mee.
  3. Wijzig de basis-URL van je client naar het mTLS-endpoint.
  4. Stuur een testverzoek:
Codevoorbeeld
curl https://mtls.eu1.platform.bird.com/v1/workspace \
  --cert client.pem \
  --key client.key \
  -H "Authorization: Bearer $BIRD_API_KEY"

Een ander antwoord dan 401 betekent dat de certificaatcontrole is geslaagd. Een 401-antwoord bevat een foutcode. Problemen oplossen geeft per code de oorzaak.

Wil je de aanroepers vinden die de modus enforced zou weigeren, filter dan de verzoeklogs van de werkruimte op mTLS missing. De verzoeklogs registreren schrijfbewerkingen, zoals POST-, PATCH- en DELETE-verzoeken, en SMTP-inzendingen. Leesbewerkingen registreren ze niet. Controleer clients die alleen lezen daarom apart, want de modus enforced weigert die ook.

mTLS afdwingen

  1. Zet elke integratie over naar het mTLS-endpoint.
  2. Selecteer bij Mode de optie Enforced en selecteer daarna Save.

Het standaardendpoint weigert nu verzoeken met een API-sleutel, een OAuth-token of een serviceaccounttoken voor de werkruimte met E02090.

De gehoste MCP-server kan de werkruimte niet bereiken. Gebruik in plaats daarvan de lokale MCP-server van de Bird CLI.

Het SMTP-endpoint weigert AUTH voor de werkruimte met 535 5.7.8. Een open SMTP-sessie ontvangt 530 5.7.0 bij het volgende bericht. Verstuur e-mail in plaats daarvan via de API op het mTLS-endpoint.

Het kan tot 15 minuten duren voordat een wijziging aan de CA's of de vereiste SAN voor elk verzoek geldt.

De Bird CLI gebruiken

De Bird CLI en de bijbehorende lokale MCP-server (bird mcp) presenteren je clientcertificaat met deze instellingen:

InstellingFlagOmgevingsvariabele
Certificaatketen, PEM, leafcertificaat eerst--client-certBIRD_CLIENT_CERT
Privésleutel, PEM, niet versleuteld--client-keyBIRD_CLIENT_KEY
Verzoeken naar het mTLS-endpoint sturen--mtlsBIRD_MTLS=1
Codevoorbeeld
export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtls

Wil je de instellingen bewaren bij een OAuth-login, geef dan de drie flags mee aan bird auth login. Het profiel slaat de bestandspaden op, en latere opdrachten gebruiken het mTLS-endpoint zonder flags. bird auth status toont de SHA-256-vingerafdruk en de vervaldatum van het certificaat.

Een SDK gebruiken

Geef de SDK de paden van je certificaatketen (PEM, leafcertificaat eerst) en van de bijbehorende privésleutel (PEM, niet versleuteld). De SDK presenteert het certificaat bij elk verzoek en stuurt verzoeken naar het mTLS-endpoint van de regio van je API-sleutel. Als je een basis-URL instelt, gebruikt de SDK die URL.

De SDK weigert een certificaat in combinatie met een HTTP-client die je zelf meegeeft. Als je je eigen HTTP-client wilt gebruiken, configureer je het certificaat op die client en stel je de basis-URL in op het mTLS-endpoint.

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

Een clientcertificaat tonen bij webhookleveringen

Wij genereren een RSA 2048-sleutelpaar en een CSR met het subject CN=<workspace ID>, O=Bird. De privésleutel blijft bij ons. Jouw CA ondertekent de CSR, en wij tonen het ondertekende certificaat wanneer je ontvanger erom vraagt.

We tonen het certificaat bij webhookabonnementen en directe callbacks, ook bij elke nieuwe poging. Bij deze leveringen tonen we het niet:

  • realtime.*-events
  • Connector-endpoints
  • MCP Events-abonnementen
ModusGedrag bij aflevering
disabledWe presenteren geen certificaat.
evaluatingWe presenteren het certificaat wanneer de ontvanger erom vraagt. Als de ontvanger het weigert, leveren we opnieuw af zonder certificaat.
enforcedWe presenteren het certificaat. Als de ontvanger er niet om vraagt of het weigert, mislukt de afleverpoging.

Het certificaat laten ondertekenen en uploaden

  1. Open Webhooks > mTLS.
  2. Selecteer bij Certificate de optie Create signing request.
  3. Selecteer in Signing request de optie Download.
  4. Laat je CA de CSR ondertekenen met het uitgebreide sleutelgebruik clientAuth.
  5. Selecteer Upload certificate.
  6. Plak eerst het ondertekende certificaat en daarna elk tussenliggend certificaat op volgorde. Je kunt ook een bestand kiezen.
  7. Selecteer Upload certificate.

We controleren of het certificaat overeenkomt met de sleutel van de ondertekeningsaanvraag, het uitgebreide sleutelgebruik clientAuth heeft en binnen de geldigheidsperiode valt. De sectie Certificate toont daarna het onderwerp, de uitgever, het serienummer, de SHA-256-vingerafdruk en de geldigheidsperiode.

Je ontvangers configureren

  1. Vraag tijdens de TLS-handshake om een clientcertificaat.
  2. Vertrouw de CA die ons certificaat heeft ondertekend.
  3. Presenteer een servercertificaat van een publiek vertrouwde CA dat overeenkomt met de hostnaam van de ontvanger.

Wil je ons certificaat accepteren en geen ander certificaat van je CA, controleer dan op het onderwerp CN=<workspace ID> of de SHA-256-vingerafdruk.

Webhook-mTLS afdwingen

  1. Selecteer bij Mode de optie Evaluating en selecteer daarna Save.
  2. Stuur met POST /v1/webhooks/{webhook_id}/test een testevent naar elke webhook. Controleer dat client_certificate gelijk is aan presented. not_requested betekent dat de ontvanger niet om het certificaat heeft gevraagd, en rejected betekent dat de ontvanger het niet heeft geaccepteerd.
  3. Voor SMS-callback-URL's, die geen webhook-ID hebben, stuur je een SMS met options.callback_url ingesteld op de ontvanger. Controleer de logs van de ontvanger en zorg dat de callback ons certificaat presenteert. In evaluating verschijnt een geweigerd certificaat ook in GET /v1/webhook-callbacks/attempts als mislukte poging met een failure_reason.
  4. Selecteer bij Mode de optie Enforced en selecteer daarna Save.

In de modus enforced verschijnt een geweigerd certificaat als mislukte poging in de bezorgpogingen van de webhook.

Intrekking controleren

Stel Certificate revocation list check in op Full chain om intrekking te controleren met certificaatintrekkingslijsten (CRL's).

  • Bij API-verzoeken controleren we het clientcertificaat en elk tussencertificaat onder je CA.
  • Bij webhookbezorgingen controleren we het servercertificaat van je ontvanger en elk tussencertificaat onder de root ervan.

We controleren elk CRL-distributiepunt van het certificaat. De http- en https-URI's van één distributiepunt zijn mirrors van dezelfde CRL, en we gebruiken de eerste mirror die reageert. Een distributiepunt zonder http- of https-URI laat de controle mislukken. Een certificaat zonder CRL-distributiepunten wordt niet gecontroleerd. We verifiëren de handtekening van elke CRL. Als we geen geldige CRL kunnen ophalen, weigeren we het verzoek of laten we de bezorgpoging mislukken.

LimietWaarde
Downloadtijd van CRL5 seconden per download, 10 seconden per verzoek
Grootte van CRL10 MiB
CRL's per werkruimte10 voor API-verzoeken en 10 voor webhookleveringen

Certificaten vervangen

We e-mailen de contactpersonen van de werkruimte 30 dagen en 7 dagen voordat een CA of het webhookclientcertificaat verloopt.

Zo vervang je de CA voor API-verzoeken:

  1. Voeg de nieuwe CA toe. De werkruimte vertrouwt nu beide CA's.
  2. Zet elke integratie over op een clientcertificaat van de nieuwe CA.
  3. Verwijder de oude CA.

Je kunt de laatste CA niet verwijderen zolang de modus evaluating of enforced is. Clientcertificaten van je CA vereisen geen actie in Bird.

Zo vervang je het webhook-clientcertificaat:

  1. Selecteer Create new signing request.
  2. Laat de nieuwe CSR ondertekenen en upload het certificaat.

Het huidige certificaat blijft in gebruik totdat je het nieuwe uploadt. Testverzendingen gebruiken het nieuwe certificaat direct, maar leveringen kunnen het vorige certificaat nog tot enkele minuten blijven presenteren. Je ontvangers moeten tot dan beide certificaten accepteren, op basis van de CA of de vingerafdruk.

Automatiseren met de API

Voor elke actie in het dashboard is er een API-bewerking. Stuur deze aanroepen naar een endpoint dat je modus accepteert: het standaardendpoint in de modus disabled of evaluating, en het mTLS-endpoint met een clientcertificaat in de modus enforced. De API-sleutel heeft schrijftoegang tot de scope access_restrictions nodig. Master-sleutels van de organisatie kunnen deze bewerkingen niet gebruiken.

Codevoorbeeld
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"}'

Problemen oplossen

API-verzoeken die niet door een controle komen, geven 401 terug met een van deze codes:

CodeOorzaak
E02086Het verzoek bevatte geen clientcertificaat.
E02087Het clientcertificaat is niet geldig voor de werkruimte.
E02088Een certificaat in de keten is ingetrokken.
E02089De modus is disabled, dus het mTLS-endpoint weigert het verzoek.
E02090De modus is enforced, dus het standaard-endpoint weigert het verzoek.
E02091We konden een CRL niet binnen 5 seconden downloaden.
E02092Een CRL is groter dan 10 MiB.
E02093De werkruimte gebruikt al 10 CRL's.
E02094Een CRL heeft een ongeldige handtekening of het tijdstip van de volgende update is verstreken.

Een wijziging van een instelling kan een van deze codes teruggeven:

  • E10027: API-mTLS is niet ingeschakeld voor de werkruimte. Neem contact op met je Bird-vertegenwoordiger om het in te schakelen.
  • E10028: webhook-mTLS is niet ingeschakeld voor de werkruimte. Neem contact op met je Bird-vertegenwoordiger om het in te schakelen.

Volgende stappen

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.