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.
| Richting | TLS-client | TLS-server | Instellingen |
|---|---|---|---|
| API-verzoeken | Je systemen | Het mTLS-endpoint | Workspace settings > mTLS |
| Webhookleveringen | Wij | Je ontvangers | Webhooks > 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_restrictionsin de werkruimte. Om testgebeurtenissen voor webhooks te versturen, heb je ook schrijftoegang tot de scopewebhooksnodig. - 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.
| Regio | Standaardendpoint | mTLS-endpoint |
|---|---|---|
eu1 | https://eu1.platform.bird.com | https://mtls.eu1.platform.bird.com |
us1 | https://us1.platform.bird.com | https://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.
| Modus | Standaardendpoint | mTLS-endpoint |
|---|---|---|
disabled | Accepteert verzoeken | Weigert verzoeken |
evaluating | Accepteert verzoeken | Accepteert verzoeken met een geldig clientcertificaat |
enforced | Weigert verzoeken | Accepteert verzoeken met een geldig clientcertificaat |
De modus geldt voor dit verkeer. Al het andere blijft in elke modus werken.
| Verkeer | Modus enforced |
|---|---|
| API-verzoeken met een API-sleutel, een OAuth-token of een serviceaccounttoken | Het standaardendpoint weigert ze met E02090. |
| Indienen via SMTP | Geweigerd. SMTP kan geen clientcertificaat presenteren. |
| De gehoste MCP-server | Kan de werkruimte niet bereiken. De server kan je clientcertificaat niet presenteren. |
| Dashboardsessies | Niet beïnvloed. |
| Automations | Geen invloed. |
| Verzoeken met inloggegevens van de organisatie bij organisatiebewerkingen | Niet gecontroleerd. De modus hoort bij een werkruimte, en deze verzoeken noemen geen werkruimte. |
| SIP-trunks | Geen 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
- Open Workspace settings > mTLS.
- Selecteer in Certificate authorities de optie Add certificate authority.
- Plak het PEM-certificaat van je CA of kies een bestand.
- 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
- Selecteer in Mode de optie Evaluating en selecteer daarna Save.
- Configureer je client zodat die zijn certificaat aanbiedt. Als een tussenliggende CA het clientcertificaat ondertekent, stuur je ook het tussenliggende certificaat mee.
- Wijzig de basis-URL van je client naar het mTLS-endpoint.
- Stuur een testverzoek:
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
- Zet elke integratie over naar het mTLS-endpoint.
- 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:
| Instelling | Flag | Omgevingsvariabele |
|---|---|---|
| Certificaatketen, PEM, leafcertificaat eerst | --client-cert | BIRD_CLIENT_CERT |
| Privésleutel, PEM, niet versleuteld | --client-key | BIRD_CLIENT_KEY |
| Verzoeken naar het mTLS-endpoint sturen | --mtls | BIRD_MTLS=1 |
export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtlsWil 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);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;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
| Modus | Gedrag bij aflevering |
|---|---|
disabled | We presenteren geen certificaat. |
evaluating | We presenteren het certificaat wanneer de ontvanger erom vraagt. Als de ontvanger het weigert, leveren we opnieuw af zonder certificaat. |
enforced | We presenteren het certificaat. Als de ontvanger er niet om vraagt of het weigert, mislukt de afleverpoging. |
Het certificaat laten ondertekenen en uploaden
- Open Webhooks > mTLS.
- Selecteer bij Certificate de optie Create signing request.
- Selecteer in Signing request de optie Download.
- Laat je CA de CSR ondertekenen met het uitgebreide sleutelgebruik
clientAuth. - Selecteer Upload certificate.
- Plak eerst het ondertekende certificaat en daarna elk tussenliggend certificaat op volgorde. Je kunt ook een bestand kiezen.
- 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
- Vraag tijdens de TLS-handshake om een clientcertificaat.
- Vertrouw de CA die ons certificaat heeft ondertekend.
- 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
- Selecteer bij Mode de optie Evaluating en selecteer daarna Save.
- Stuur met
POST /v1/webhooks/{webhook_id}/testeen testevent naar elke webhook. Controleer datclient_certificategelijk is aanpresented.not_requestedbetekent dat de ontvanger niet om het certificaat heeft gevraagd, enrejectedbetekent dat de ontvanger het niet heeft geaccepteerd. - Voor SMS-callback-URL's, die geen webhook-ID hebben, stuur je een SMS met
options.callback_urlingesteld op de ontvanger. Controleer de logs van de ontvanger en zorg dat de callback ons certificaat presenteert. Inevaluatingverschijnt een geweigerd certificaat ook inGET /v1/webhook-callbacks/attemptsals mislukte poging met eenfailure_reason. - 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.
| Limiet | Waarde |
|---|---|
| Downloadtijd van CRL | 5 seconden per download, 10 seconden per verzoek |
| Grootte van CRL | 10 MiB |
| CRL's per werkruimte | 10 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:
- Voeg de nieuwe CA toe. De werkruimte vertrouwt nu beide CA's.
- Zet elke integratie over op een clientcertificaat van de nieuwe CA.
- 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:
- Selecteer Create new signing request.
- 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.
| Bewerking | Actie |
|---|---|
PATCH /v1/workspace/mtls-settings | state, expected_san of crl_check wijzigen |
POST /v1/workspace/mtls-certificate-authorities | Een CA toevoegen |
DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id} | Een CA verwijderen |
PATCH /v1/workspace/webhook-client-certificate | state of crl_check wijzigen |
POST /v1/workspace/webhook-client-certificate/signing-request | Een CSR aanmaken |
POST /v1/workspace/webhook-client-certificate/certificate | Het ondertekende certificaat uploaden |
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:
| Code | Oorzaak |
|---|---|
E02086 | Het verzoek bevatte geen clientcertificaat. |
E02087 | Het clientcertificaat is niet geldig voor de werkruimte. |
E02088 | Een certificaat in de keten is ingetrokken. |
E02089 | De modus is disabled, dus het mTLS-endpoint weigert het verzoek. |
E02090 | De modus is enforced, dus het standaard-endpoint weigert het verzoek. |
E02091 | We konden een CRL niet binnen 5 seconden downloaden. |
E02092 | Een CRL is groter dan 10 MiB. |
E02093 | De werkruimte gebruikt al 10 CRL's. |
E02094 | Een 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
- Authenticatie: API-sleutels, scopes en serviceaccounts
- Webhooks en events: endpoints aanmaken en handtekeningen verifiëren
- Fouten: het foutantwoord en hoe je ermee omgaat
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.