mTLS
Available on requestContact your Bird representative to enable it for your organization.
Mutual TLS (mTLS) menambahkan pemeriksaan sertifikat ke handshake TLS di kedua arah. Setiap arah memiliki pengaturannya sendiri. Anda dapat menyiapkan satu arah atau keduanya.
| Arah | Klien TLS | Server TLS | Pengaturan |
|---|---|---|---|
| Permintaan API | Sistem Anda | Endpoint mTLS | Workspace settings > mTLS |
| Pengiriman webhook | Kami | Penerima Anda | Webhooks > mTLS |
Setiap pihak menyimpan kunci privatnya sendiri. Untuk permintaan API, Anda memberi kami sertifikat publik dari otoritas sertifikat (CA) Anda. Untuk pengiriman webhook, kami memberi Anda permintaan penandatanganan sertifikat (CSR), lalu Anda mengembalikan sertifikat publik yang sudah ditandatangani.
Sebelum memulai
- Hubungi perwakilan Bird Anda untuk mengaktifkan mTLS API, mTLS webhook, atau keduanya untuk organisasi Anda. Setiap arah diaktifkan secara terpisah.
- Dapatkan peran dengan akses tulis ke cakupan
access_restrictionsdi workspace. Untuk mengirim peristiwa uji webhook, dapatkan juga akses tulis ke cakupanwebhooks. - Untuk permintaan API, dapatkan sertifikat PEM dari CA yang menerbitkan sertifikat klien Anda. Gunakan CA penerbit, bukan CA root. Pemeriksaan rantai menerima setiap sertifikat yang memiliki rantai ke CA terdaftar, sehingga CA root juga meloloskan sertifikat dari CA penerbit lain di bawahnya. Setiap sertifikat tetap harus lolos pemeriksaan lainnya, seperti extended key usage
clientAuth. - Untuk pengiriman webhook, siapkan CA yang dapat menandatangani CSR dengan extended key usage
clientAuth.
Wajibkan sertifikat klien pada permintaan API
Setiap region memiliki endpoint mTLS. Endpoint ini melayani operasi yang sama dengan endpoint standar dan meminta sertifikat dari setiap klien.
| Region | Endpoint standar | 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 |
Sertifikat klien tidak menggantikan kredensial Anda. Setiap permintaan tetap mengirimkan kunci API, token OAuth, atau token akun layanan di header Authorization.
Mode adalah pengaturan workspace. Mode menentukan endpoint mana yang menerima permintaan untuk workspace dengan kunci API, token OAuth, atau token akun layanan.
| Mode | Endpoint standar | Endpoint mTLS |
|---|---|---|
disabled | Menerima permintaan | Menolak permintaan |
evaluating | Menerima permintaan | Menerima permintaan yang menyertakan sertifikat klien yang valid |
enforced | Menolak permintaan | Menerima permintaan yang menyertakan sertifikat klien yang valid |
Mode berlaku untuk lalu lintas berikut. Semua lalu lintas lain tetap berfungsi di setiap mode.
| Lalu lintas | Mode enforced |
|---|---|
| Permintaan API dengan kunci API, token OAuth, atau token akun layanan | Endpoint standar menolaknya dengan E02090. |
| Pengiriman SMTP | Ditolak. SMTP tidak dapat menyajikan sertifikat klien. |
| Server MCP yang di-host | Tidak dapat menjangkau workspace. Server ini tidak dapat menyajikan sertifikat klien Anda. |
| Sesi dasbor | Tidak terpengaruh. |
| Automations | Tidak terpengaruh. |
| Permintaan dengan kredensial organisasi pada operasi organisasi | Tidak diperiksa. Mode dimiliki oleh workspace, sedangkan permintaan ini tidak menyebutkan workspace apa pun. |
| Trunk SIP | Tidak terpengaruh. Trunk tetap mengautentikasi panggilan dengan kunci API yang diizinkan, tanpa sertifikat. |
Perubahan mode langsung berlaku untuk permintaan baru. Sesi SMTP yang sedang terbuka menerapkan mode baru pada pesan berikutnya.
Sertifikat klien yang valid memiliki rantai ke CA milik workspace, masih dalam masa berlakunya, dan memiliki extended key usage clientAuth. Jika Anda menetapkan subject alternative name (SAN) wajib, sertifikat juga harus memuatnya. Kami membandingkan nama DNS dan URI. Kami tidak menggunakan common name.
Tambahkan otoritas sertifikat Anda
- Buka Workspace settings > mTLS.
- Di Certificate authorities, pilih Add certificate authority.
- Tempelkan sertifikat PEM dari CA Anda, atau pilih file.
- Pilih Add certificate authority.
Sertifikat harus memiliki basic constraint CA:true dan key usage keyCertSign, serta tidak boleh kedaluwarsa. Satu workspace dapat memiliki dua CA.
Jika CA Anda juga menerbitkan sertifikat untuk pihak lain, atur Required subject alternative name ke identitas yang dimuat sertifikat klien Anda.
Uji dalam mode evaluasi
- Di Mode, pilih Evaluating, lalu pilih Save.
- Konfigurasikan klien Anda agar menyajikan sertifikatnya. Jika CA perantara menandatangani sertifikat klien, kirim juga sertifikat perantara tersebut.
- Ubah URL dasar klien Anda ke endpoint mTLS.
- Kirim permintaan uji:
curl https://mtls.eu1.platform.bird.com/v1/workspace \
--cert client.pem \
--key client.key \
-H "Authorization: Bearer $BIRD_API_KEY"Respons selain 401 menunjukkan bahwa pemeriksaan sertifikat berhasil. Respons 401 berisi kode kesalahan. Pemecahan masalah menjelaskan penyebab setiap kode.
Untuk menemukan pemanggil yang akan ditolak oleh mode enforced, filter log permintaan workspace berdasarkan mTLS missing. Log permintaan mencatat operasi tulis, seperti permintaan POST, PATCH, dan DELETE, serta pengiriman SMTP. Log ini tidak mencatat operasi baca, jadi periksa secara terpisah klien yang hanya membaca, karena mode enforced juga menolaknya.
Terapkan mTLS secara wajib
- Pindahkan setiap integrasi ke endpoint mTLS.
- Di Mode, pilih Enforced, lalu pilih Save.
Endpoint standar kini menolak permintaan dengan kunci API, token OAuth, atau token akun layanan untuk workspace tersebut dengan E02090.
Server MCP yang di-host tidak dapat menjangkau workspace. Sebagai gantinya, gunakan server MCP lokal dari Bird CLI.
Endpoint SMTP menolak AUTH untuk workspace dengan 535 5.7.8. Sesi SMTP yang sedang terbuka menerima 530 5.7.0 pada pesan berikutnya. Sebagai gantinya, kirim email melalui API di endpoint mTLS.
Perubahan pada CA atau SAN wajib dapat memerlukan waktu hingga 15 menit sebelum berlaku untuk setiap permintaan.
Gunakan Bird CLI
Bird CLI dan server MCP lokalnya (bird mcp) menyajikan sertifikat klien Anda dengan pengaturan berikut:
| Pengaturan | Flag | Variabel lingkungan |
|---|---|---|
| Rantai sertifikat, PEM, sertifikat leaf terlebih dahulu | --client-cert | BIRD_CLIENT_CERT |
| Kunci privat, PEM, tidak terenkripsi | --client-key | BIRD_CLIENT_KEY |
| Kirim permintaan ke 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 --mtlsAgar pengaturan tetap tersimpan dengan login OAuth, berikan ketiga flag tersebut ke bird auth login. Profil menyimpan path file, dan perintah berikutnya menggunakan endpoint mTLS tanpa flag. bird auth status menampilkan sidik jari SHA-256 dan kedaluwarsa sertifikat.
Gunakan SDK
Berikan path rantai sertifikat Anda (PEM, sertifikat leaf terlebih dahulu) dan kunci privatnya (PEM, tidak terenkripsi) kepada SDK. SDK menyajikan sertifikat pada setiap permintaan dan mengirim permintaan ke endpoint mTLS di region kunci API Anda. Jika Anda menetapkan URL dasar, SDK menggunakan URL tersebut.
SDK menolak sertifikat yang diberikan bersama klien HTTP milik Anda sendiri. Untuk menggunakan klien HTTP Anda sendiri, konfigurasikan sertifikat pada klien tersebut dan tetapkan URL dasar ke 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;Sajikan sertifikat klien pada pengiriman webhook
Kami membuat pasangan kunci RSA 2048 dan CSR dengan subjek CN=<workspace ID>, O=Bird. Kunci privat tetap berada di pihak kami. CA Anda menandatangani CSR tersebut, dan kami menyajikan sertifikat yang telah ditandatangani saat penerima Anda memintanya.
Kami menyajikan sertifikat pada langganan webhook dan callback langsung, termasuk saat coba lagi. Pengiriman berikut tidak menyajikannya:
- Peristiwa
realtime.* - Endpoint konektor
- Langganan MCP Events
| Mode | Perilaku pengiriman |
|---|---|
disabled | Kami tidak menyajikan sertifikat. |
evaluating | Kami menyajikan sertifikat saat penerima memintanya. Jika penerima menolaknya, kami mengirim ulang tanpa sertifikat. |
enforced | Kami menyajikan sertifikat. Jika penerima tidak memintanya atau menolaknya, upaya pengiriman gagal. |
Tandatangani dan unggah sertifikat
- Buka Webhooks > mTLS.
- Di Certificate, pilih Create signing request.
- Di Signing request, pilih Download.
- Minta CA Anda menandatangani CSR dengan extended key usage
clientAuth. - Pilih Upload certificate.
- Tempelkan sertifikat yang sudah ditandatangani terlebih dahulu, lalu setiap sertifikat perantara secara berurutan. Anda juga dapat memilih file.
- Pilih Upload certificate.
Kami memeriksa bahwa sertifikat cocok dengan kunci dari permintaan penandatanganan, memiliki extended key usage clientAuth, dan berada dalam masa berlakunya. Bagian Certificate kemudian menampilkan subjek, penerbit, nomor seri, sidik jari SHA-256, dan masa berlakunya.
Konfigurasikan penerima Anda
- Minta sertifikat klien selama handshake TLS.
- Percayai CA yang menandatangani sertifikat kami.
- Tunjukkan sertifikat server dari CA tepercaya publik yang cocok dengan hostname penerima.
Untuk menerima sertifikat kami dan menolak sertifikat lain dari CA Anda, cocokkan subjek CN=<workspace ID> atau sidik jari SHA-256.
Terapkan mTLS webhook
- Di Mode, pilih Evaluating, lalu pilih Save.
- Kirim event uji ke setiap webhook dengan
POST /v1/webhooks/{webhook_id}/test. Pastikanclient_certificatebernilaipresented.not_requestedberarti penerima tidak meminta sertifikat, danrejectedberarti penerima tidak menerimanya. - Untuk URL callback SMS, yang tidak memiliki ID webhook, kirim SMS dengan
options.callback_urldiatur ke penerima. Periksa log penerima, dan pastikan callback menyajikan sertifikat kami. Dalam modeevaluating, sertifikat yang ditolak juga muncul diGET /v1/webhook-callbacks/attemptssebagai percobaan gagal denganfailure_reason. - Di Mode, pilih Enforced, lalu pilih Save.
Dalam mode enforced, sertifikat yang ditolak muncul sebagai percobaan gagal di percobaan pengiriman webhook tersebut.
Memeriksa pencabutan
Atur Certificate revocation list check ke Full chain untuk memeriksa pencabutan dengan daftar pencabutan sertifikat (CRL).
- Pada permintaan API, kami memeriksa sertifikat klien dan setiap sertifikat perantara di bawah CA Anda.
- Pada pengiriman webhook, kami memeriksa sertifikat server penerima Anda dan setiap sertifikat perantara di bawah root-nya.
Kami memeriksa setiap titik distribusi CRL pada sertifikat. URI http dan https dari satu titik distribusi adalah mirror dari CRL yang sama, dan kami menggunakan mirror pertama yang merespons. Titik distribusi tanpa URI http atau https gagal dalam pemeriksaan. Sertifikat tanpa titik distribusi CRL tidak diperiksa. Kami memverifikasi tanda tangan setiap CRL. Jika kami tidak bisa mendapatkan CRL yang valid, kami menolak permintaan atau menggagalkan percobaan pengiriman.
| Batas | Nilai |
|---|---|
| Waktu unduh CRL | 5 detik untuk setiap unduhan, 10 detik untuk setiap permintaan |
| Ukuran CRL | 10 MiB |
| CRL untuk setiap workspace | 10 untuk permintaan API dan 10 untuk pengiriman webhook |
Merotasi sertifikat
Kami mengirim email kepada kontak workspace 30 hari dan 7 hari sebelum CA atau sertifikat klien webhook kedaluwarsa.
Untuk merotasi CA bagi permintaan API:
- Tambahkan CA baru. Workspace kini memercayai kedua CA.
- Pindahkan setiap integrasi ke sertifikat klien dari CA baru.
- Hapus CA lama.
Anda tidak dapat menghapus CA terakhir selama mode adalah evaluating atau enforced. Sertifikat klien dari CA Anda tidak memerlukan tindakan apa pun dalam mode Bird.
Untuk merotasi sertifikat klien webhook:
- Pilih Create new signing request.
- Minta CSR baru ditandatangani, lalu unggah sertifikatnya.
Sertifikat saat ini tetap digunakan sampai Anda mengunggah sertifikat baru. Pengiriman uji langsung menggunakan sertifikat baru, tetapi pengiriman biasa dapat tetap menyajikan sertifikat sebelumnya hingga beberapa menit. Hingga saat itu, penerima Anda harus menerima kedua sertifikat, berdasarkan CA atau sidik jari.
Otomatiskan dengan API
Setiap tindakan di dasbor memiliki operasi API. Kirim panggilan ini ke endpoint yang diterima oleh mode Anda: endpoint standar dalam mode disabled atau evaluating, dan endpoint mTLS dengan sertifikat klien dalam mode enforced. Kunci API memerlukan akses tulis ke cakupan access_restrictions. Kunci master organisasi tidak dapat menggunakan operasi ini.
| Operasi | Tindakan |
|---|---|
PATCH /v1/workspace/mtls-settings | Mengubah state, expected_san, atau crl_check |
POST /v1/workspace/mtls-certificate-authorities | Menambahkan CA |
DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id} | Menghapus CA |
PATCH /v1/workspace/webhook-client-certificate | Mengubah state atau crl_check |
POST /v1/workspace/webhook-client-certificate/signing-request | Membuat CSR |
POST /v1/workspace/webhook-client-certificate/certificate | Mengunggah sertifikat yang telah ditandatangani |
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"}'Pemecahan masalah
Permintaan API yang gagal dalam pemeriksaan mengembalikan 401 dengan salah satu kode berikut:
| Kode | Penyebab |
|---|---|
E02086 | Permintaan tidak menyertakan sertifikat klien. |
E02087 | Sertifikat klien tidak valid untuk workspace. |
E02088 | Salah satu sertifikat dalam rantai telah dicabut. |
E02089 | Mode diatur ke disabled, sehingga endpoint mTLS menolak permintaan. |
E02090 | Mode diatur ke enforced, sehingga endpoint standar menolak permintaan. |
E02091 | Kami tidak dapat mengunduh CRL dalam 5 detik. |
E02092 | Ukuran CRL lebih dari 10 MiB. |
E02093 | Workspace sudah menggunakan 10 CRL. |
E02094 | Tanda tangan CRL tidak valid, atau waktu pembaruan berikutnya sudah terlewati. |
Perubahan pengaturan dapat mengembalikan salah satu kode berikut:
E10027: mTLS API belum diaktifkan untuk workspace. Hubungi perwakilan Bird Anda untuk mengaktifkannya.E10028: mTLS webhook belum diaktifkan untuk workspace. Hubungi perwakilan Bird Anda untuk mengaktifkannya.
Langkah berikutnya
- Autentikasi: kunci API, cakupan, dan akun layanan
- Webhook & event: membuat endpoint dan memverifikasi tanda tangan
- Error: respons kesalahan dan cara menanganinya
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.