mTLS
Available on requestContact your Bird representative to enable it for your organization.
Wzajemny TLS (mTLS) dodaje do uzgadniania TLS sprawdzanie certyfikatu w obu kierunkach. Każdy kierunek ma własne ustawienia. Możesz skonfigurować jeden kierunek lub oba.
| Kierunek | Klient TLS | Serwer TLS | Ustawienia |
|---|---|---|---|
| Żądania API | Twoje systemy | Punkt końcowy mTLS | Workspace settings > mTLS |
| Dostarczanie webhooków | My | Twoje odbiorniki | Webhooks > mTLS |
Każda strona przechowuje własne klucze prywatne. W przypadku żądań API przekazujesz nam publiczny certyfikat swojego urzędu certyfikacji (CA). W przypadku dostarczania webhooków przekazujemy Ci żądanie podpisania certyfikatu (CSR), a Ty odsyłasz podpisany certyfikat publiczny.
Zanim zaczniesz
- Skontaktuj się z przedstawicielem Bird, aby włączyć dla swojej organizacji mTLS dla API, mTLS dla webhooków lub oba. Każdy kierunek włącza się osobno.
- Uzyskaj w obszarze roboczym rolę z uprawnieniami zapisu w zakresie
access_restrictions. Aby wysyłać testowe zdarzenia webhooków, uzyskaj też uprawnienia zapisu w zakresiewebhooks. - W przypadku żądań API pobierz certyfikat PEM urzędu certyfikacji, który wystawia Twoje certyfikaty klienta. Wybierz urząd wystawiający zamiast głównego urzędu certyfikacji: sprawdzanie łańcucha akceptuje każdy certyfikat, którego łańcuch prowadzi do zarejestrowanego urzędu certyfikacji, więc główny urząd certyfikacji przepuszcza też certyfikaty swoich pozostałych urzędów wystawiających. Każdy certyfikat musi nadal przejść pozostałe sprawdzenia, na przykład rozszerzonego użycia klucza
clientAuth. - W przypadku dostarczania webhooków przygotuj urząd certyfikacji, który może podpisać CSR z rozszerzonym użyciem klucza
clientAuth.
Wymagaj certyfikatów klienta w żądaniach API
Każdy region ma endpoint mTLS. Obsługuje on te same operacje co endpoint standardowy i żąda certyfikatu od każdego klienta.
| Region | Standardowy endpoint | 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 |
Certyfikat klienta nie zastępuje Twoich danych uwierzytelniających. Każde żądanie nadal wysyła klucz API, token OAuth lub token konta usługi w nagłówku Authorization.
Tryb jest ustawieniem obszaru roboczego. Określa, który endpoint akceptuje żądania dla obszaru roboczego z kluczem API, tokenem OAuth lub tokenem konta usługi.
| Tryb | Standardowy endpoint | Endpoint mTLS |
|---|---|---|
disabled | Akceptuje żądania | Odrzuca żądania |
evaluating | Akceptuje żądania | Akceptuje żądania z ważnym certyfikatem klienta |
enforced | Odrzuca żądania | Akceptuje żądania z ważnym certyfikatem klienta |
Tryb dotyczy tego ruchu. Wszystko inne działa dalej w każdym trybie.
| Ruch | Tryb enforced |
|---|---|
| Żądania API z kluczem API, tokenem OAuth lub tokenem konta usługi | Standardowy endpoint odrzuca je, zwracając E02090. |
| Wysyłanie przez SMTP | Odrzucane. SMTP nie może przedstawić certyfikatu klienta. |
| Hostowany serwer MCP | Nie ma dostępu do obszaru roboczego. Nie może przedstawić Twojego certyfikatu klienta. |
| Sesje panelu | Bez wpływu. |
| Automations | Bez zmian. |
| Żądania z danymi uwierzytelniającymi organizacji w operacjach organizacji | Niesprawdzane. Tryb należy do obszaru roboczego, a te żądania nie wskazują żadnego obszaru roboczego. |
| Trunki SIP | Bez zmian. Trunk nadal uwierzytelnia połączenia dozwolonym kluczem API, bez certyfikatu. |
Zmiana trybu od razu obowiązuje dla nowych żądań. Otwarta sesja SMTP przechodzi na nowy tryb przy następnej wiadomości.
Prawidłowy certyfikat klienta tworzy łańcuch do urzędu certyfikacji obszaru roboczego, jest w okresie ważności i ma rozszerzone użycie klucza clientAuth. Jeśli ustawisz wymaganą alternatywną nazwę podmiotu (SAN), certyfikat musi ją również zawierać. Porównujemy nazwy DNS i identyfikatory URI. Nie używamy nazwy pospolitej (CN).
Dodaj urząd certyfikacji
- Otwórz Workspace settings > mTLS.
- W sekcji Certificate authorities wybierz Add certificate authority.
- Wklej certyfikat PEM swojego urzędu certyfikacji lub wybierz plik.
- Wybierz Add certificate authority.
Certyfikat musi mieć ograniczenie podstawowe CA:true i użycie klucza keyCertSign oraz nie może być wygasły. Obszar roboczy może mieć dwa urzędy certyfikacji.
Jeśli Twój urząd certyfikacji wystawia certyfikaty również innym podmiotom, ustaw w polu Required subject alternative name tożsamość zawartą w Twoich certyfikatach klienta.
Przetestuj w trybie ewaluacji
- W polu Mode wybierz Evaluating, a następnie wybierz Save.
- Skonfiguruj klienta tak, aby przedstawiał swój certyfikat. Jeśli certyfikat klienta podpisuje pośredni urząd certyfikacji, wysyłaj również certyfikat pośredni.
- Zmień bazowy adres URL klienta na endpoint mTLS.
- Wyślij żądanie testowe:
curl https://mtls.eu1.platform.bird.com/v1/workspace \
--cert client.pem \
--key client.key \
-H "Authorization: Bearer $BIRD_API_KEY"Odpowiedź inna niż 401 oznacza, że sprawdzenie certyfikatu się powiodło. Odpowiedź 401 zawiera kod błędu. Przyczynę każdego kodu podaje sekcja Rozwiązywanie problemów.
Aby znaleźć wywołujących, których odrzuciłby tryb enforced, przefiltruj logi żądań obszaru roboczego według mTLS missing. Logi żądań rejestrują zapisy, takie jak żądania POST, PATCH i DELETE, oraz wysyłki SMTP. Nie rejestrują odczytów, więc klientów, którzy tylko odczytują dane, sprawdź osobno: tryb enforced również ich odrzuca.
Wymuś mTLS
- Przenieś każdą integrację na endpoint mTLS.
- W polu Mode wybierz Enforced, a następnie wybierz Save.
Standardowy endpoint odrzuca teraz żądania z kluczem API, tokenem OAuth lub tokenem konta usługi dla tego obszaru roboczego, zwracając E02090.
Hostowany serwer MCP nie ma dostępu do obszaru roboczego. Zamiast niego użyj lokalnego serwera MCP z Bird CLI.
Endpoint SMTP odmawia AUTH dla obszaru roboczego, zwracając 535 5.7.8. Otwarta sesja SMTP otrzymuje 530 5.7.0 przy następnej wiadomości. Zamiast tego wysyłaj e-maile przez API na endpoincie mTLS.
Zastosowanie zmiany urzędów certyfikacji lub wymaganej nazwy SAN do każdego żądania może potrwać do 15 minut.
Korzystanie z Bird CLI
Bird CLI i jego lokalny serwer MCP (bird mcp) przedstawiają Twój certyfikat klienta na podstawie tych ustawień:
| Ustawienie | Flaga | Zmienna środowiskowa |
|---|---|---|
| Łańcuch certyfikatów, PEM, najpierw certyfikat końcowy | --client-cert | BIRD_CLIENT_CERT |
| Klucz prywatny, PEM, niezaszyfrowany | --client-key | BIRD_CLIENT_KEY |
| Wysyłanie żądań do endpointu 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 --mtlsAby zachować te ustawienia przy logowaniu OAuth, przekaż trzy flagi do bird auth login. Profil zapisuje ścieżki plików, a kolejne polecenia używają endpointu mTLS bez flag. bird auth status pokazuje odcisk SHA-256 i datę wygaśnięcia certyfikatu.
Korzystanie z SDK
Przekaż do SDK ścieżki łańcucha certyfikatów (PEM, najpierw certyfikat końcowy) i jego klucza prywatnego (PEM, niezaszyfrowany). SDK przedstawia certyfikat przy każdym żądaniu i wysyła żądania do endpointu mTLS regionu Twojego klucza API. Jeśli ustawisz bazowy adres URL, SDK używa tego adresu URL.
SDK odrzuca certyfikat podany razem z klientem HTTP, który dostarczasz samodzielnie. Aby korzystać z własnego klienta HTTP, skonfiguruj certyfikat w tym kliencie i ustaw bazowy adres URL na 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;Przedstawianie certyfikatu klienta przy dostarczaniu webhooków
Generujemy parę kluczy RSA 2048 i CSR z podmiotem CN=<workspace ID>, O=Bird. Klucz prywatny pozostaje u nas. Twój urząd certyfikacji podpisuje CSR, a my przedstawiamy podpisany certyfikat, gdy Twój odbiornik o niego poprosi.
Przedstawiamy certyfikat w subskrypcjach webhooków i bezpośrednich wywołaniach zwrotnych, łącznie z ponownymi próbami. Następujące dostarczenia go nie przedstawiają:
- Zdarzenia
realtime.* - Endpointy konektorów
- Subskrypcje MCP Events
| Tryb | Sposób dostarczania |
|---|---|
disabled | Nie przedstawiamy certyfikatu. |
evaluating | Przedstawiamy certyfikat, gdy odbiorca o niego poprosi. Jeśli odbiorca go odrzuci, dostarczamy ponownie bez certyfikatu. |
enforced | Przedstawiamy certyfikat. Jeśli odbiorca o niego nie poprosi lub go odrzuci, próba dostarczenia kończy się niepowodzeniem. |
Podpisz i prześlij certyfikat
- Otwórz Webhooks > mTLS.
- W sekcji Certificate wybierz Create signing request.
- W sekcji Signing request wybierz Download.
- Podpisz CSR swoim CA z rozszerzonym użyciem klucza
clientAuth. - Wybierz Upload certificate.
- Wklej najpierw podpisany certyfikat, a potem kolejno każdy certyfikat pośredni. Możesz też wybrać plik.
- Wybierz Upload certificate.
Sprawdzamy, czy certyfikat pasuje do klucza z żądania podpisania, ma rozszerzone użycie klucza clientAuth i jest w okresie ważności. Sekcja Certificate pokazuje wtedy jego podmiot, wystawcę, numer seryjny, odcisk SHA-256 i okres ważności.
Skonfiguruj odbiorniki
- Żądaj certyfikatu klienta podczas uzgadniania TLS.
- Ustaw zaufanie do CA, które podpisało nasz certyfikat.
- Przedstawiaj certyfikat serwera od publicznie zaufanego CA, zgodny z nazwą hosta odbiornika.
Aby akceptować nasz certyfikat i żaden inny certyfikat od swojego CA, dopasowuj podmiot CN=<workspace ID> lub odcisk SHA-256.
Wymuś mTLS dla webhooków
- W polu Mode wybierz Evaluating, a następnie wybierz Save.
- Wyślij zdarzenie testowe do każdego webhooka za pomocą
POST /v1/webhooks/{webhook_id}/test. Sprawdź, czyclient_certificatema wartośćpresented.not_requestedoznacza, że odbiorca nie zażądał certyfikatu, arejectedoznacza, że go nie zaakceptował. - W przypadku adresów URL wywołań zwrotnych SMS, które nie mają identyfikatora webhooka, wyślij SMS z
options.callback_urlustawionym na odbiorcę. Sprawdź logi odbiorcy i upewnij się, że wywołanie zwrotne przedstawia nasz certyfikat. W trybieevaluatingodrzucony certyfikat jest też widoczny wGET /v1/webhook-callbacks/attemptsjako nieudana próba zfailure_reason. - W polu Mode wybierz Enforced, a następnie wybierz Save.
W trybie enforced odrzucony certyfikat jest widoczny jako nieudana próba w próbach dostarczenia webhooka.
Sprawdzanie unieważnienia
Aby sprawdzać unieważnienie za pomocą list unieważnionych certyfikatów (CRL), ustaw Certificate revocation list check na Full chain.
- W żądaniach API sprawdzamy certyfikat klienta i każdy certyfikat pośredni poniżej Twojego CA.
- Przy dostarczaniu webhooków sprawdzamy certyfikat serwera Twojego odbiorcy i każdy certyfikat pośredni poniżej jego certyfikatu głównego.
Sprawdzamy każdy punkt dystrybucji CRL certyfikatu. Adresy URI http i https jednego punktu dystrybucji są kopiami tej samej listy CRL, a my używamy pierwszej kopii, która odpowie. Punkt dystrybucji bez adresu URI http ani https nie przechodzi sprawdzenia. Certyfikat bez punktów dystrybucji CRL nie jest sprawdzany. Weryfikujemy podpis każdej listy CRL. Jeśli nie możemy pobrać prawidłowej listy CRL, odrzucamy żądanie lub próba dostarczenia kończy się niepowodzeniem.
| Limit | Wartość |
|---|---|
| Czas pobierania CRL | 5 sekund na każde pobranie, 10 sekund na każde żądanie |
| Rozmiar CRL | 10 MiB |
| Liczba CRL na obszar roboczy | 10 dla żądań API i 10 dla dostarczania webhooków |
Rotacja certyfikatów
Wysyłamy e-mail do kontaktów obszaru roboczego 30 dni i 7 dni przed wygaśnięciem CA lub certyfikatu klienta webhooków.
Aby wymienić CA dla żądań API:
- Dodaj nowe CA. Obszar roboczy ufa wtedy obu CA.
- Przenieś każdą integrację na certyfikat klienta wystawiony przez nowe CA.
- Usuń stare CA.
Nie możesz usunąć ostatniego CA, gdy tryb to evaluating lub enforced. Certyfikaty klienta wystawione przez Twoje CA nie wymagają żadnych działań w trybie Bird.
Aby wymienić certyfikat klienta dla webhooków:
- Wybierz Create new signing request.
- Podpisz nowy CSR i prześlij certyfikat.
Bieżący certyfikat pozostaje w użyciu, dopóki nie prześlesz nowego. Testowe wysyłki od razu używają nowego certyfikatu, ale dostarczenia mogą jeszcze przez kilka minut przedstawiać poprzedni. Do tego czasu Twoje odbiorniki muszą akceptować oba certyfikaty, na podstawie CA lub odcisku.
Automatyzacja za pomocą API
Każdej akcji w panelu odpowiada operacja API. Wysyłaj te wywołania do punktu końcowego, który akceptuje Twój tryb: do standardowego punktu końcowego w trybie disabled lub evaluating, a do punktu końcowego mTLS z certyfikatem klienta w trybie enforced. Klucz API wymaga uprawnień do zapisu w zakresie access_restrictions. Klucze główne organizacji nie mogą korzystać z tych operacji.
| Operacja | Akcja |
|---|---|
PATCH /v1/workspace/mtls-settings | Zmiana state, expected_san lub crl_check |
POST /v1/workspace/mtls-certificate-authorities | Dodaj urząd certyfikacji |
DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id} | Usuń urząd certyfikacji |
PATCH /v1/workspace/webhook-client-certificate | Zmień state lub crl_check |
POST /v1/workspace/webhook-client-certificate/signing-request | Utwórz CSR |
POST /v1/workspace/webhook-client-certificate/certificate | Prześlij podpisany certyfikat |
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"}'Rozwiązywanie problemów
Żądania API, które nie przejdą sprawdzenia, zwracają 401 z jednym z tych kodów:
| Kod | Przyczyna |
|---|---|
E02086 | Żądanie nie przedstawiło certyfikatu klienta. |
E02087 | Certyfikat klienta nie jest ważny dla obszaru roboczego. |
E02088 | Jeden z certyfikatów w łańcuchu został unieważniony. |
E02089 | Tryb to disabled, więc punkt końcowy mTLS odrzuca żądanie. |
E02090 | Tryb to enforced, więc standardowy punkt końcowy odrzuca żądanie. |
E02091 | Nie udało nam się pobrać listy CRL w ciągu 5 sekund. |
E02092 | Lista CRL jest większa niż 10 MiB. |
E02093 | Obszar roboczy używa już 10 list CRL. |
E02094 | Lista CRL ma nieprawidłowy podpis lub minął termin jej następnej aktualizacji. |
Zmiana ustawienia może zwrócić jeden z tych kodów:
E10027: mTLS dla API nie jest włączone w obszarze roboczym. Skontaktuj się z przedstawicielem Bird, aby je włączyć.E10028: mTLS dla webhooków nie jest włączone w obszarze roboczym. Skontaktuj się z przedstawicielem Bird, aby je włączyć.
Następne kroki
- Uwierzytelnianie: klucze API, zakresy i konta usług
- Webhooki i zdarzenia: tworzenie punktów końcowych i weryfikacja podpisów
- Błędy: odpowiedź z błędem i sposób jej obsługi
Powiązane zasoby
Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.