mTLS
Available on requestContact your Bird representative to enable it for your organization.
Il TLS reciproco (mTLS) aggiunge una verifica del certificato all'handshake TLS in entrambe le direzioni. Ogni direzione ha le proprie impostazioni. Puoi configurare una direzione o entrambe.
| Direzione | Client TLS | Server TLS | Impostazioni |
|---|---|---|---|
| Richieste API | I tuoi sistemi | L'endpoint mTLS | Workspace settings > mTLS |
| Consegne dei webhook | Noi | I tuoi ricevitori | Webhooks > mTLS |
Ogni parte conserva le proprie chiavi private. Per le richieste API, ci fornisci il certificato pubblico della tua autorità di certificazione (CA). Per le consegne dei webhook, ti forniamo una richiesta di firma del certificato (CSR) e tu ci restituisci il certificato pubblico firmato.
Prima di iniziare
- Contatta il tuo referente Bird per abilitare l'mTLS API, l'mTLS dei webhook o entrambi per la tua organizzazione. Ogni direzione viene abilitata separatamente.
- Ottieni un ruolo con accesso in scrittura allo scope
access_restrictionsnello spazio di lavoro. Per inviare eventi di test dei webhook, ottieni anche l'accesso in scrittura allo scopewebhooks. - Per le richieste API, procurati il certificato PEM della CA che emette i tuoi certificati client. Preferisci la CA emittente alla CA radice: la verifica della catena accetta ogni certificato collegato tramite catena a una CA registrata, quindi una CA radice fa passare anche i certificati delle sue altre CA emittenti. Ogni certificato deve comunque superare gli altri controlli, come l'utilizzo esteso della chiave
clientAuth. - Per le consegne dei webhook, prepara una CA in grado di firmare una CSR con l'extended key usage
clientAuth.
Richiedere certificati client sulle richieste API
Ogni regione ha un endpoint mTLS. Questo endpoint offre le stesse operazioni dell'endpoint standard e chiede un certificato a ogni client.
| Regione | Endpoint standard | Endpoint mTLS |
|---|---|---|
eu1 | https://eu1.platform.bird.com | https://mtls.eu1.platform.bird.com |
us1 | https://us1.platform.bird.com | https://mtls.us1.platform.bird.com |
Il certificato client non sostituisce le tue credenziali. Ogni richiesta invia comunque una chiave API, un token OAuth o un token di account di servizio nell'header Authorization.
La modalità è un'impostazione dello spazio di lavoro. Stabilisce quale endpoint accetta le richieste per lo spazio di lavoro con una chiave API, un token OAuth o un token di account di servizio.
| Modalità | Endpoint standard | Endpoint mTLS |
|---|---|---|
disabled | Accetta le richieste | Rifiuta le richieste |
evaluating | Accetta le richieste | Accetta le richieste con un certificato client valido |
enforced | Rifiuta le richieste | Accetta le richieste con un certificato client valido |
La modalità si applica a questo traffico. Tutto il resto continua a funzionare in qualsiasi modalità.
| Traffico | Modalità enforced |
|---|---|
| Richieste API con una chiave API, un token OAuth o un token di account di servizio | L'endpoint standard le rifiuta con E02090. |
| Invio tramite SMTP | Rifiutato. SMTP non può presentare un certificato client. |
| Il server MCP ospitato | Non può raggiungere lo spazio di lavoro, perché non può presentare il tuo certificato client. |
| Sessioni della dashboard | Non interessate. |
| Automations | Nessun effetto. |
| Richieste con una credenziale dell'organizzazione su operazioni dell'organizzazione | Non verificate. La modalità appartiene a uno spazio di lavoro e queste richieste non ne indicano nessuno. |
| Trunk SIP | Nessun effetto. Un trunk continua ad autenticare le chiamate con una chiave API consentita, senza certificato. |
Una modifica della modalità si applica subito alle nuove richieste. Una sessione SMTP aperta riceve la nuova modalità al messaggio successivo.
Un certificato client valido è collegato tramite catena a una CA dello spazio di lavoro, rientra nel suo periodo di validità e ha l'utilizzo esteso della chiave clientAuth. Se imposti un nome alternativo del soggetto (SAN) obbligatorio, il certificato deve contenere anche quello. Confrontiamo nomi DNS e URI. Non usiamo il nome comune.
Aggiungi la tua autorità di certificazione
- Apri Workspace settings > mTLS.
- In Certificate authorities, seleziona Add certificate authority.
- Incolla il certificato PEM della tua CA oppure scegli un file.
- Seleziona Add certificate authority.
Il certificato deve avere il vincolo di base CA:true e l'utilizzo della chiave keyCertSign, e non deve essere scaduto. Uno spazio di lavoro può avere due CA.
Se la tua CA emette certificati anche per altre parti, imposta Required subject alternative name sull'identità riportata nei tuoi certificati client.
Esegui i test in modalità di valutazione
- In Mode, seleziona Evaluating, poi seleziona Save.
- Configura il client in modo che presenti il suo certificato. Se il certificato client è firmato da una CA intermedia, invia anche il certificato intermedio.
- Imposta come URL di base del client l'endpoint mTLS.
- Invia una richiesta di prova:
curl https://mtls.eu1.platform.bird.com/v1/workspace \
--cert client.pem \
--key client.key \
-H "Authorization: Bearer $BIRD_API_KEY"Una risposta diversa da 401 indica che il controllo del certificato è stato superato. Una risposta 401 contiene un codice di errore. Risoluzione dei problemi indica la causa di ogni codice.
Per individuare i chiamanti che la modalità enforced rifiuterebbe, filtra i log delle richieste dello spazio di lavoro per mTLS missing. I log delle richieste registrano le scritture, come le richieste POST, PATCH e DELETE, e gli invii SMTP. Non registrano le letture, quindi verifica separatamente i client che eseguono solo letture: anche questi vengono rifiutati dalla modalità enforced.
Rendi obbligatorio mTLS
- Sposta ogni integrazione sull'endpoint mTLS.
- In Mode, seleziona Enforced, quindi seleziona Save.
L'endpoint standard ora rifiuta con E02090 le richieste per lo spazio di lavoro con una chiave API, un token OAuth o un token di account di servizio.
Il server MCP ospitato non può raggiungere lo spazio di lavoro. Usa invece il server MCP locale della CLI di Bird.
L'endpoint SMTP rifiuta l'AUTH per lo spazio di lavoro con 535 5.7.8. Una sessione SMTP aperta riceve 530 5.7.0 al messaggio successivo. Invia invece le email tramite API sull'endpoint mTLS.
Una modifica alle CA o al SAN obbligatorio può richiedere fino a 15 minuti per applicarsi a ogni richiesta.
Usare la CLI di Bird
La CLI di Bird e il suo server MCP locale (bird mcp) presentano il tuo certificato client con queste impostazioni:
| Impostazione | Flag | Variabile d'ambiente |
|---|---|---|
| Catena di certificati, PEM, prima il certificato foglia | --client-cert | BIRD_CLIENT_CERT |
| Chiave privata, PEM, non cifrata | --client-key | BIRD_CLIENT_KEY |
| Invia le richieste all'endpoint mTLS | --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 --mtlsPer conservare le impostazioni con un login OAuth, passa i tre flag a bird auth login. Il profilo memorizza i percorsi dei file e i comandi successivi usano l'endpoint mTLS senza flag. bird auth status mostra l'impronta SHA-256 e la scadenza del certificato.
Usare un SDK
Fornisci all'SDK i percorsi della tua catena di certificati (PEM, prima il certificato foglia) e della sua chiave privata (PEM, non cifrata). L'SDK presenta il certificato a ogni richiesta e invia le richieste all'endpoint mTLS della regione della tua chiave API. Se imposti un URL di base, l'SDK usa quell'URL.
L'SDK rifiuta un certificato insieme a un client HTTP fornito da te. Per usare il tuo client HTTP, configura il certificato su quel client e imposta come URL di base l'endpoint mTLS.
// 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;Presenta un certificato client nelle consegne dei webhook
Generiamo una coppia di chiavi RSA 2048 e una CSR con il soggetto CN=<workspace ID>, O=Bird. La chiave privata resta a noi. La tua CA firma la CSR e noi presentiamo il certificato firmato quando il tuo ricevitore ne richiede uno.
Presentiamo il certificato nelle sottoscrizioni webhook e nei callback diretti, compresi i nuovi tentativi. Queste consegne non lo presentano:
- Eventi
realtime.* - Endpoint dei connettori
- Sottoscrizioni MCP Events
| Modalità | Comportamento della consegna |
|---|---|
disabled | Non presentiamo alcun certificato. |
evaluating | Presentiamo il certificato quando il ricevitore lo richiede. Se il ricevitore lo rifiuta, ripetiamo la consegna senza certificato. |
enforced | Presentiamo il certificato. Se il ricevitore non lo richiede o lo rifiuta, il tentativo di consegna non riesce. |
Firma e carica il certificato
- Apri Webhooks > mTLS.
- In Certificate, seleziona Create signing request.
- In Signing request, seleziona Download.
- Fai firmare la CSR dalla tua CA con l'utilizzo esteso della chiave
clientAuth. - Seleziona Upload certificate.
- Incolla prima il certificato firmato, poi ogni certificato intermedio nell'ordine corretto. Puoi anche scegliere un file.
- Seleziona Upload certificate.
Verifichiamo che il certificato corrisponda alla chiave della richiesta di firma, abbia l'utilizzo esteso della chiave clientAuth e rientri nel suo periodo di validità. La sezione Certificate mostra quindi soggetto, emittente, numero di serie, impronta SHA-256 e periodo di validità del certificato.
Configura i tuoi ricevitori
- Richiedi un certificato client durante l'handshake TLS.
- Considera attendibile la CA che ha firmato il nostro certificato.
- Presenta un certificato server emesso da una CA pubblicamente attendibile e corrispondente al nome host del ricevitore.
Per accettare il nostro certificato e nessun altro certificato della tua CA, verifica la corrispondenza del soggetto CN=<workspace ID> o dell'impronta SHA-256.
Applica l'mTLS ai webhook
- In Mode, seleziona Evaluating, poi seleziona Save.
- Invia un evento di test a ogni webhook con
POST /v1/webhooks/{webhook_id}/test. Verifica checlient_certificatesiapresented.not_requestedindica che il ricevitore non ha richiesto il certificato, mentrerejectedindica che non lo ha accettato. - Per gli URL di callback SMS, che non hanno un ID webhook, invia un SMS con
options.callback_urlimpostato sul ricevitore. Controlla i log del ricevitore e verifica che il callback presenti il nostro certificato. Inevaluating, un certificato rifiutato compare anche inGET /v1/webhook-callbacks/attemptscome tentativo non riuscito con unfailure_reason. - In Mode, seleziona Enforced, poi seleziona Save.
In modalità enforced, un certificato rifiutato compare come tentativo non riuscito nei tentativi di consegna del webhook.
Verificare la revoca
Imposta Certificate revocation list check su Full chain per verificare la revoca tramite le liste di revoca dei certificati (CRL).
- Sulle richieste API, verifichiamo il certificato client e ogni certificato intermedio sotto la tua CA.
- Sulle consegne webhook, verifichiamo il certificato server del tuo ricevitore e ogni certificato intermedio sotto la sua radice.
Verifichiamo ogni punto di distribuzione CRL del certificato. Gli URI http e https di un punto di distribuzione sono mirror della stessa CRL e usiamo il primo mirror che risponde. Un punto di distribuzione senza un URI http o https non supera la verifica. Un certificato senza punti di distribuzione CRL non viene verificato. Verifichiamo la firma di ogni CRL. Se non riusciamo a ottenere una CRL valida, rifiutiamo la richiesta o facciamo fallire il tentativo di consegna.
| Limite | Valore |
|---|---|
| Tempo di download di una CRL | 5 secondi per ogni download, 10 secondi per ogni richiesta |
| Dimensione di una CRL | 10 MiB |
| CRL per ogni spazio di lavoro | 10 per le richieste API e 10 per le consegne dei webhook |
Ruotare i certificati
Inviamo un'email ai contatti dello spazio di lavoro 30 giorni e 7 giorni prima della scadenza di una CA o del certificato client dei webhook.
Per ruotare la CA per le richieste API:
- Aggiungi la nuova CA. Lo spazio di lavoro ora considera attendibili entrambe le CA.
- Sposta ogni integrazione su un certificato client emesso dalla nuova CA.
- Rimuovi la vecchia CA.
Non puoi rimuovere l'ultima CA mentre la modalità è evaluating o enforced. In Bird i certificati client emessi dalla tua CA non richiedono alcuna azione.
Per ruotare il certificato client dei webhook:
- Seleziona Create new signing request.
- Fai firmare la nuova CSR e carica il certificato.
Il certificato attuale resta in uso finché non carichi quello nuovo. Gli invii di test usano subito il nuovo certificato, ma le consegne possono continuare a presentare quello precedente per qualche minuto. Fino ad allora i tuoi ricevitori devono accettare entrambi i certificati, tramite la CA o tramite l'impronta digitale.
Automatizzare con l'API
Ogni azione della dashboard ha un'operazione API corrispondente. Invia queste chiamate a un endpoint accettato dalla tua modalità: l'endpoint standard in modalità disabled o evaluating, e l'endpoint mTLS con un certificato client in modalità enforced. La chiave API deve avere accesso in scrittura all'ambito access_restrictions. Le chiavi master dell'organizzazione non possono usare queste operazioni.
| Operazione | Azione |
|---|---|
PATCH /v1/workspace/mtls-settings | Modificare state, expected_san o crl_check |
POST /v1/workspace/mtls-certificate-authorities | Aggiungere una CA |
DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id} | Rimuovere una CA |
PATCH /v1/workspace/webhook-client-certificate | Modificare state o crl_check |
POST /v1/workspace/webhook-client-certificate/signing-request | Creare una CSR |
POST /v1/workspace/webhook-client-certificate/certificate | Caricare il certificato firmato |
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"}'Risoluzione dei problemi
Le richieste API che non superano un controllo restituiscono 401 con uno di questi codici:
| Codice | Causa |
|---|---|
E02086 | La richiesta non ha presentato alcun certificato client. |
E02087 | Il certificato client non è valido per lo spazio di lavoro. |
E02088 | Un certificato della catena è revocato. |
E02089 | La modalità è disabled, quindi l'endpoint mTLS rifiuta la richiesta. |
E02090 | La modalità è enforced, quindi l'endpoint standard rifiuta la richiesta. |
E02091 | Non è stato possibile scaricare una CRL entro 5 secondi. |
E02092 | Una CRL supera i 10 MiB. |
E02093 | Lo spazio di lavoro usa già 10 CRL. |
E02094 | Una CRL ha una firma non valida o ha superato la data del prossimo aggiornamento. |
Una modifica delle impostazioni può restituire uno di questi codici:
E10027: l'mTLS per API non è abilitato per lo spazio di lavoro. Contatta il tuo referente Bird per abilitarlo.E10028: l'mTLS per i webhook non è abilitato per lo spazio di lavoro. Contatta il tuo referente Bird per abilitarlo.
Passaggi successivi
- Autenticazione: chiavi API, scope e account di servizio
- Webhook ed eventi: crea endpoint e verifica le firme
- Errori: la risposta di errore e come gestirla
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.