---
title: "mTLS"
description: "Richiedi un certificato client sulle richieste API tramite l'endpoint mTLS e presenta un certificato client nelle consegne dei webhook ai tuoi ricevitori."
canonical: "https://bird.com/it-it/documentazione/guides/mtls"
availability: "on-request"
---

# mTLS

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**](https://bird.com/dashboard/w/settings/mtls) |
| Consegne dei webhook | Noi            | I tuoi ricevitori | [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/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_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.

| 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`](/docs/api/errors/E02090).                                        |
| Invio tramite [SMTP](/docs/guides/email/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](/docs/guides/voice/sip-trunks)                                          | 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

1. Apri [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/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:

```bash
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](#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`](/docs/api/errors/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](#usare-la-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](/docs/cli) 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`        |

```bash
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.

**TypeScript**

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

Examples: [TypeScript](/it-it/documentazione/guides/mtls.ts.md) · [Python](/it-it/documentazione/guides/mtls.py.md) · [Go](/it-it/documentazione/guides/mtls.go.md) · [PHP](/it-it/documentazione/guides/mtls.php.md)

## 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

1. Apri [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/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`](/docs/api/reference/test-webhook). 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](/docs/guides/sms/callbacks), 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`](/docs/api/reference/list-webhook-callback-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](/docs/guides/webhooks#replaying-failed-deliveries) 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:

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.

| Operazione                                                                                                                                         | Azione                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [`PATCH /v1/workspace/mtls-settings`](/docs/api/reference/update-workspace-mtls-settings)                                                          | Modificare `state`, `expected_san` o `crl_check` |
| [`POST /v1/workspace/mtls-certificate-authorities`](/docs/api/reference/create-workspace-mtls-certificate-authority)                               | Aggiungere una CA                                |
| [`DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}`](/docs/api/reference/delete-workspace-mtls-certificate-authority)  | Rimuovere una CA                                 |
| [`PATCH /v1/workspace/webhook-client-certificate`](/docs/api/reference/update-workspace-webhook-client-certificate)                                | Modificare `state` o `crl_check`                 |
| [`POST /v1/workspace/webhook-client-certificate/signing-request`](/docs/api/reference/create-workspace-webhook-client-certificate-signing-request) | Creare una CSR                                   |
| [`POST /v1/workspace/webhook-client-certificate/certificate`](/docs/api/reference/submit-workspace-webhook-client-certificate)                     | Caricare il certificato firmato                  |

```bash
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`](/docs/api/errors/E02086) | La richiesta non ha presentato alcun certificato client.                          |
| [`E02087`](/docs/api/errors/E02087) | Il certificato client non è valido per lo spazio di lavoro.                       |
| [`E02088`](/docs/api/errors/E02088) | Un certificato della catena è revocato.                                           |
| [`E02089`](/docs/api/errors/E02089) | La modalità è `disabled`, quindi l'endpoint mTLS rifiuta la richiesta.            |
| [`E02090`](/docs/api/errors/E02090) | La modalità è `enforced`, quindi l'endpoint standard rifiuta la richiesta.        |
| [`E02091`](/docs/api/errors/E02091) | Non è stato possibile scaricare una CRL entro 5 secondi.                          |
| [`E02092`](/docs/api/errors/E02092) | Una CRL supera i 10 MiB.                                                          |
| [`E02093`](/docs/api/errors/E02093) | Lo spazio di lavoro usa già 10 CRL.                                               |
| [`E02094`](/docs/api/errors/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`](/docs/api/errors/E10027): l'mTLS per API non è abilitato per lo spazio di lavoro. Contatta il tuo referente Bird per abilitarlo.
- [`E10028`](/docs/api/errors/E10028): l'mTLS per i webhook non è abilitato per lo spazio di lavoro. Contatta il tuo referente Bird per abilitarlo.

## Passaggi successivi

- [Autenticazione](/docs/guides/authentication): chiavi API, scope e account di servizio
- [Webhook ed eventi](/docs/guides/webhooks): crea endpoint e verifica le firme
- [Errori](/docs/guides/errors): la risposta di errore e come gestirla

## Related resources

- [Webhooks done right: reliable delivery events](/learn/basics/webhooks-done-right-reliable-delivery-events) (video)
- [How do I verify a webhook signature?](/explained/platform/how-do-i-verify-a-webhook-signature) (answer)
- [SMTP relay](/email-api/features/smtp) (product)
- [Operate messaging reliably](/learn/paths/reliability) (course)
