Sign inGet Started

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.

DirezioneClient TLSServer TLSImpostazioni
Richieste APII tuoi sistemiL'endpoint mTLSWorkspace settings > mTLS
Consegne dei webhookNoiI tuoi ricevitoriWebhooks > 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_restrictions nello spazio di lavoro. Per inviare eventi di test dei webhook, ottieni anche l'accesso in scrittura allo scope webhooks.
  • 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.

RegioneEndpoint standardEndpoint mTLS
eu1https://eu1.platform.bird.comhttps://mtls.eu1.platform.bird.com
us1https://us1.platform.bird.comhttps://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 standardEndpoint mTLS
disabledAccetta le richiesteRifiuta le richieste
evaluatingAccetta le richiesteAccetta le richieste con un certificato client valido
enforcedRifiuta le richiesteAccetta le richieste con un certificato client valido

La modalità si applica a questo traffico. Tutto il resto continua a funzionare in qualsiasi modalità.

TrafficoModalità enforced
Richieste API con una chiave API, un token OAuth o un token di account di servizioL'endpoint standard le rifiuta con E02090.
Invio tramite SMTPRifiutato. SMTP non può presentare un certificato client.
Il server MCP ospitatoNon può raggiungere lo spazio di lavoro, perché non può presentare il tuo certificato client.
Sessioni della dashboardNon interessate.
AutomationsNessun effetto.
Richieste con una credenziale dell'organizzazione su operazioni dell'organizzazioneNon verificate. La modalità appartiene a uno spazio di lavoro e queste richieste non ne indicano nessuno.
Trunk SIPNessun 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

  1. Apri Workspace settings > mTLS.
  2. In Certificate authorities, seleziona Add certificate authority.
  3. Incolla il certificato PEM della tua CA oppure scegli un file.
  4. 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

  1. In Mode, seleziona Evaluating, poi seleziona Save.
  2. Configura il client in modo che presenti il suo certificato. Se il certificato client è firmato da una CA intermedia, invia anche il certificato intermedio.
  3. Imposta come URL di base del client l'endpoint mTLS.
  4. Invia una richiesta di prova:
Esempio di codice
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

  1. Sposta ogni integrazione sull'endpoint mTLS.
  2. 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:

ImpostazioneFlagVariabile d'ambiente
Catena di certificati, PEM, prima il certificato foglia--client-certBIRD_CLIENT_CERT
Chiave privata, PEM, non cifrata--client-keyBIRD_CLIENT_KEY
Invia le richieste all'endpoint mTLS--mtlsBIRD_MTLS=1
Esempio di codice
export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtls

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

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
disabledNon presentiamo alcun certificato.
evaluatingPresentiamo il certificato quando il ricevitore lo richiede. Se il ricevitore lo rifiuta, ripetiamo la consegna senza certificato.
enforcedPresentiamo il certificato. Se il ricevitore non lo richiede o lo rifiuta, il tentativo di consegna non riesce.

Firma e carica il certificato

  1. Apri Webhooks > mTLS.
  2. In Certificate, seleziona Create signing request.
  3. In Signing request, seleziona Download.
  4. Fai firmare la CSR dalla tua CA con l'utilizzo esteso della chiave clientAuth.
  5. Seleziona Upload certificate.
  6. Incolla prima il certificato firmato, poi ogni certificato intermedio nell'ordine corretto. Puoi anche scegliere un file.
  7. 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

  1. Richiedi un certificato client durante l'handshake TLS.
  2. Considera attendibile la CA che ha firmato il nostro certificato.
  3. 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

  1. In Mode, seleziona Evaluating, poi seleziona Save.
  2. Invia un evento di test a ogni webhook con POST /v1/webhooks/{webhook_id}/test. Verifica che client_certificate sia presented. not_requested indica che il ricevitore non ha richiesto il certificato, mentre rejected indica che non lo ha accettato.
  3. Per gli URL di callback SMS, che non hanno un ID webhook, invia un SMS con options.callback_url impostato sul ricevitore. Controlla i log del ricevitore e verifica che il callback presenti il nostro certificato. In evaluating, un certificato rifiutato compare anche in GET /v1/webhook-callbacks/attempts come tentativo non riuscito con un failure_reason.
  4. 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.

LimiteValore
Tempo di download di una CRL5 secondi per ogni download, 10 secondi per ogni richiesta
Dimensione di una CRL10 MiB
CRL per ogni spazio di lavoro10 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:

  1. Aggiungi la nuova CA. Lo spazio di lavoro ora considera attendibili entrambe le CA.
  2. Sposta ogni integrazione su un certificato client emesso dalla nuova CA.
  3. 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:

  1. Seleziona Create new signing request.
  2. 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.

Esempio di codice
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:

CodiceCausa
E02086La richiesta non ha presentato alcun certificato client.
E02087Il certificato client non è valido per lo spazio di lavoro.
E02088Un certificato della catena è revocato.
E02089La modalità è disabled, quindi l'endpoint mTLS rifiuta la richiesta.
E02090La modalità è enforced, quindi l'endpoint standard rifiuta la richiesta.
E02091Non è stato possibile scaricare una CRL entro 5 secondi.
E02092Una CRL supera i 10 MiB.
E02093Lo spazio di lavoro usa già 10 CRL.
E02094Una 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

Continua con la documentazione, le guide e gli esempi per questo argomento.