mTLS

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

Le TLS mutuel (mTLS) ajoute une vérification de certificat dans les deux sens lors de la négociation TLS. Chaque sens a ses propres paramètres. Vous pouvez configurer un seul sens ou les deux.

Chaque partie conserve ses propres clés privées. Pour les requêtes API, vous nous fournissez le certificat public de votre autorité de certification (CA). Pour les livraisons de webhooks, nous vous fournissons une demande de signature de certificat (CSR), et vous nous renvoyez le certificat public signé.

Avant de commencer

• Contactez votre représentant Bird pour activer le mTLS API, le mTLS des webhooks, ou les deux, pour votre organisation. Chaque sens s'active séparément.
• Obtenez un rôle disposant d'un accès en écriture au scope access_restrictions dans l'espace de travail. Pour envoyer des événements de test de webhook, obtenez aussi un accès en écriture au scope webhooks.
• Pour les requêtes API, procurez-vous le certificat PEM de la CA qui émet vos certificats client. Préférez la CA émettrice à la CA racine : la vérification de la chaîne accepte tout certificat qui remonte jusqu'à une CA enregistrée, donc une CA racine laisse aussi passer les certificats de ses autres CA émettrices. Chaque certificat doit tout de même réussir les autres vérifications, comme l'usage étendu de clé clientAuth.
• Pour les livraisons de webhooks, préparez une CA capable de signer une CSR avec l'usage étendu de clé clientAuth.

Exiger des certificats client pour les requêtes API

Chaque région dispose d'un endpoint mTLS. Il propose les mêmes opérations que l'endpoint standard et demande un certificat à chaque client.

Le certificat client ne remplace pas vos identifiants. Chaque requête envoie toujours une clé API, un jeton OAuth ou un jeton de compte de service dans l'en-tête Authorization.

Le mode est un paramètre de l'espace de travail. Il détermine quel endpoint accepte les requêtes adressées à l'espace de travail avec une clé API, un jeton OAuth ou un jeton de compte de service.

Le mode s'applique au trafic suivant. Tout le reste continue de fonctionner, quel que soit le mode.

Un changement de mode s'applique immédiatement aux nouvelles requêtes. Une session SMTP ouverte reçoit le nouveau mode à son message suivant.

Un certificat client valide remonte jusqu’à une CA de l’espace de travail, se trouve dans sa période de validité et possède l’usage étendu de clé clientAuth. Si vous définissez un nom alternatif du sujet (SAN) obligatoire, le certificat doit aussi le contenir. Nous comparons les noms DNS et les URI. Nous n’utilisons pas le nom commun.

Ajouter votre autorité de certification

1. Ouvrez Workspace settings > mTLS.
2. Dans Certificate authorities, sélectionnez Add certificate authority.
3. Collez le certificat PEM de votre CA ou choisissez un fichier.
4. Sélectionnez Add certificate authority.

Le certificat doit posséder la contrainte de base CA:true et l’usage de clé keyCertSign, et il ne doit pas être expiré. Un espace de travail peut avoir deux CA.

Si votre CA émet aussi des certificats pour d’autres parties, définissez Required subject alternative name sur l’identité que portent vos certificats clients.

Tester en mode évaluation

1. Dans Mode, sélectionnez Evaluating, puis Save.
2. Configurez votre client pour qu’il présente son certificat. Si une CA intermédiaire signe le certificat client, envoyez aussi le certificat intermédiaire.
3. Remplacez l’URL de base de votre client par celle du point de terminaison mTLS.
4. Envoyez une requête de test :

curl https://mtls.eu1.platform.bird.com/v1/workspace \
  --cert client.pem \
  --key client.key \
  -H "Authorization: Bearer $BIRD_API_KEY"

Une réponse autre que 401 indique que la vérification du certificat a réussi. Une réponse 401 contient un code d'erreur. La section Dépannage indique la cause de chaque code.

Pour identifier les appelants que le mode enforced refuserait, filtrez les journaux de requêtes de l'espace de travail sur mTLS missing. Les journaux de requêtes enregistrent les écritures, comme les requêtes POST, PATCH et DELETE, ainsi que les envois SMTP. Ils n'enregistrent pas les lectures : vérifiez donc séparément les clients qui ne font que lire, car le mode enforced les refuse aussi.

Imposer mTLS

1. Faites passer chaque intégration sur le point de terminaison mTLS.
2. Dans Mode, sélectionnez Enforced, puis sélectionnez Save.

L'endpoint standard rejette désormais les requêtes accompagnées d'une clé API, d'un jeton OAuth ou d'un jeton de compte de service de l'espace de travail avec E02090.

Le serveur MCP hébergé ne peut pas accéder à l'espace de travail. Utilisez plutôt le serveur MCP local de la CLI Bird.

L'endpoint SMTP refuse l'AUTH pour l'espace de travail avec 535 5.7.8. Une session SMTP ouverte reçoit 530 5.7.0 à son message suivant. Envoyez plutôt les e-mails via l'API sur l'endpoint mTLS.

Une modification des CA ou du SAN requis peut mettre jusqu'à 15 minutes à s'appliquer à chaque requête.

Utiliser la CLI Bird

La CLI Bird et son serveur MCP local (bird mcp) présentent votre certificat client avec ces paramètres :

export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtls

Pour conserver ces paramètres avec une connexion OAuth, passez les trois options à bird auth login. Le profil enregistre les chemins des fichiers, et les commandes suivantes utilisent l'endpoint mTLS sans options. bird auth status affiche l'empreinte SHA-256 et la date d'expiration du certificat.

Utiliser un SDK

Indiquez au SDK les chemins de votre chaîne de certificats (PEM, certificat feuille en premier) et de sa clé privée (PEM, non chiffrée). Le SDK présente le certificat à chaque requête et envoie les requêtes au point de terminaison mTLS de la région de votre clé API. Si vous définissez une URL de base, le SDK utilise cette URL.

Le SDK refuse un certificat fourni avec un client HTTP que vous fournissez vous-même. Pour utiliser votre propre client HTTP, configurez le certificat sur ce client et définissez l’URL de base sur le point de terminaison 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;

Présenter un certificat client lors des livraisons de webhooks

Nous générons une paire de clés RSA 2048 et une CSR avec le sujet CN=<workspace ID>, O=Bird. La clé privée reste chez nous. Votre CA signe la CSR, et nous présentons le certificat signé lorsque votre récepteur en demande un.

Nous présentons le certificat pour les abonnements webhook et les rappels directs, y compris lors des nouvelles tentatives. Les livraisons suivantes ne le présentent pas :

• Événements realtime.*
• Points de terminaison des connecteurs
• Abonnements MCP Events

Signer et téléverser le certificat

1. Ouvrez Webhooks > mTLS.
2. Dans Certificate, sélectionnez Create signing request.
3. Dans Signing request, sélectionnez Download.
4. Faites signer la CSR par votre CA avec l'utilisation étendue de clé clientAuth.
5. Sélectionnez Upload certificate.
6. Collez d'abord le certificat signé, puis chaque certificat intermédiaire dans l'ordre. Vous pouvez aussi choisir un fichier.
7. Sélectionnez Upload certificate.

Nous vérifions que le certificat correspond à la clé de la demande de signature, qu'il possède l'utilisation étendue de clé clientAuth et qu'il est dans sa période de validité. La section Certificate affiche ensuite son sujet, son émetteur, son numéro de série, son empreinte SHA-256 et sa période de validité.

Configurer vos récepteurs

1. Demandez un certificat client lors de la négociation TLS.
2. Faites confiance à la CA qui a signé notre certificat.
3. Présentez un certificat serveur émis par une CA publiquement reconnue et correspondant au nom d'hôte du récepteur.

Pour accepter notre certificat et aucun autre certificat émis par votre CA, vérifiez le sujet CN=<workspace ID> ou l'empreinte SHA-256.

Appliquer le mTLS des webhooks

1. Dans Mode, sélectionnez Evaluating, puis Save.
2. Envoyez un événement de test à chaque webhook avec POST /v1/webhooks/{webhook_id}/test. Vérifiez que client_certificate vaut presented. not_requested signifie que le récepteur n'a pas demandé le certificat, et rejected signifie qu'il ne l'a pas accepté.
3. Pour les URL de rappel SMS, qui n'ont pas d'ID de webhook, envoyez un SMS avec options.callback_url défini sur le récepteur. Consultez les journaux du récepteur et vérifiez que le rappel présente notre certificat. En mode evaluating, un certificat refusé apparaît aussi dans GET /v1/webhook-callbacks/attempts comme une tentative échouée avec un failure_reason.
4. Dans Mode, sélectionnez Enforced, puis Save.

En mode enforced, un certificat refusé apparaît comme une tentative échouée dans les tentatives de livraison du webhook.

Vérifier la révocation

Définissez Certificate revocation list check sur Full chain pour vérifier la révocation à l'aide des listes de révocation de certificats (CRL).

• Pour les requêtes API, nous vérifions le certificat client et chaque certificat intermédiaire situé sous votre autorité de certification.
• Pour les livraisons de webhooks, nous vérifions le certificat serveur de votre récepteur et chaque certificat intermédiaire situé sous sa racine.

Nous vérifions chaque point de distribution de CRL du certificat. Les URI http et https d'un même point de distribution sont des miroirs de la même CRL, et nous utilisons le premier miroir qui répond. Un point de distribution sans URI http ou https fait échouer la vérification. Un certificat sans point de distribution de CRL n'est pas vérifié. Nous vérifions la signature de chaque CRL. Si nous ne pouvons pas obtenir de CRL valide, nous refusons la requête ou faisons échouer la tentative de livraison.

Renouveler les certificats

Nous envoyons un e-mail aux contacts de l'espace de travail 30 jours et 7 jours avant l'expiration d'une CA ou du certificat client des webhooks.

Pour renouveler la CA des requêtes API :

1. Ajoutez la nouvelle CA. L'espace de travail fait alors confiance aux deux CA.
2. Faites passer chaque intégration à un certificat client émis par la nouvelle CA.
3. Supprimez l'ancienne CA.

Vous ne pouvez pas supprimer la dernière CA tant que le mode est evaluating ou enforced. Les certificats client émis par votre CA ne demandent aucune action en mode Bird.

Pour renouveler le certificat client des webhooks :

1. Sélectionnez Create new signing request.
2. Faites signer la nouvelle CSR, puis importez le certificat.

Le certificat actuel reste utilisé jusqu'à ce que vous importiez le nouveau. Les envois de test utilisent immédiatement le nouveau certificat, mais les livraisons peuvent continuer à présenter l'ancien pendant quelques minutes au plus. D'ici là, vos récepteurs doivent accepter les deux certificats, par CA ou par empreinte.

Automatiser avec l'API

Chaque action du dashboard correspond à une opération API. Envoyez ces appels à un endpoint accepté par votre mode : l'endpoint standard en mode disabled ou evaluating, et l'endpoint mTLS avec un certificat client en mode enforced. La clé API doit disposer d'un accès en écriture au scope access_restrictions. Les clés maîtres d'organisation ne peuvent pas utiliser ces opérations.

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

Dépannage

Les requêtes API qui échouent à une vérification renvoient 401 avec l'un des codes suivants :

Une modification de paramètre peut renvoyer l’un de ces codes :

• E10027 : le mTLS API n’est pas activé pour l’espace de travail. Contactez votre représentant Bird pour l’activer.
• E10028 : le mTLS des webhooks n’est pas activé pour l’espace de travail. Contactez votre représentant Bird pour l’activer.

Étapes suivantes

• Authentification : clés API, portées et comptes de service
• Webhooks et événements : créer des endpoints et vérifier les signatures
• Erreurs : la réponse d'erreur et comment la traiter