mTLS
Available on requestContact your Bird representative to enable it for your organization.
双向 TLS(mTLS)在 TLS 握手中为双方各加一道证书检查。每个方向都有各自的设置。你可以只设置一个方向,也可以同时设置两个方向。
| 方向 | TLS 客户端 | TLS 服务器 | 设置 |
|---|---|---|---|
| API 请求 | 你的系统 | mTLS 端点 | Workspace settings > mTLS |
| Webhook 投递 | 我们 | 你的接收端 | Webhooks > mTLS |
双方各自保管自己的私钥。对于 API 请求,你向我们提供你的证书颁发机构(CA)的公钥证书。对于 Webhook 投递,我们向你提供证书签名请求(CSR),你返回签名后的公钥证书。
开始之前
- 联系你的 Bird 代表,为你的组织启用 API mTLS、Webhook mTLS 或两者。每个方向需分别启用。
- 在工作区中获取对
access_restrictions范围具有写入权限的角色。如需发送 Webhook 测试事件,还需获取对webhooks范围的写入权限。 - 对于 API 请求,获取签发你的客户端证书的 CA 的 PEM 证书。优先使用签发 CA,而不是根 CA:证书链检查会接受所有能链接到已注册 CA 的证书,因此注册根 CA 也会让其下其他签发 CA 颁发的证书通过检查。每个证书仍需通过其他检查,例如
clientAuth扩展密钥用法。 - 对于 Webhook 投递,准备一个能够以
clientAuth扩展密钥用法签署 CSR 的 CA。
要求 API 请求提供客户端证书
每个区域都有一个 mTLS 端点。它提供与标准端点相同的操作,并要求每个客户端提供证书。
| 区域 | 标准端点 | 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 |
客户端证书不能替代你的凭据。每个请求仍需在 Authorization 请求头中发送 API 密钥、OAuth 令牌或服务账号令牌。
模式是一项工作区设置。它决定由哪个端点接受该工作区使用 API 密钥、OAuth 令牌或服务账号令牌发出的请求。
| 模式 | 标准端点 | mTLS 端点 |
|---|---|---|
disabled | 接受请求 | 拒绝请求 |
evaluating | 接受请求 | 接受带有效客户端证书的请求 |
enforced | 拒绝请求 | 接受带有效客户端证书的请求 |
模式适用于以下流量。其他所有功能在每种模式下都照常运行。
| 流量 | enforced 模式 |
|---|---|
| 使用 API 密钥、OAuth 令牌或服务账号令牌的 API 请求 | 标准端点以 E02090 拒绝这些请求。 |
| SMTP 提交 | 被拒绝。SMTP 无法出示客户端证书。 |
| 托管的 MCP 服务器 | 无法访问该工作区。它无法出示你的客户端证书。 |
| 控制台会话 | 不受影响。 |
| Automations | 不受影响。 |
| 使用组织凭据调用组织操作的请求 | 不检查。该模式属于某个工作区,而这些请求不指定任何工作区。 |
| SIP 中继 | 不受影响。中继继续使用允许的 API 密钥对呼叫进行身份验证,无需证书。 |
模式更改会立即对新请求生效。已打开的 SMTP 会话会在下一条消息时采用新模式。
有效的客户端证书须链接到该工作区的某个 CA,处于有效期内,并具有 clientAuth 扩展密钥用法。如果你设置了必需的使用者备用名称(SAN),证书还必须包含该名称。我们比对 DNS 名称和 URI,不使用通用名称。
添加证书颁发机构
- 打开 Workspace settings > mTLS。
- 在 Certificate authorities 中,选择 Add certificate authority。
- 粘贴你的 CA 的 PEM 证书,或选择一个文件。
- 选择 Add certificate authority。
该证书必须具有 CA:true 基本约束和 keyCertSign 密钥用法,且不能已过期。一个工作区最多可以有两个 CA。
如果你的 CA 也向其他方颁发证书,请将 Required subject alternative name 设置为你的客户端证书所携带的身份。
在评估模式下测试
- 在 Mode 中选择 Evaluating,然后选择 Save。
- 将客户端配置为出示其证书。如果客户端证书由中间 CA 签名,还需发送中间证书。
- 将客户端的基础 URL 改为 mTLS 端点。
- 发送一个测试请求:
curl https://mtls.eu1.platform.bird.com/v1/workspace \
--cert client.pem \
--key client.key \
-H "Authorization: Bearer $BIRD_API_KEY"如果响应不是 401,说明证书检查已通过。401 响应包含错误代码。故障排除列出了每个代码的原因。
要找出 enforced 模式会拒绝的调用方,请在工作区的请求日志中按 mTLS missing 筛选。请求日志记录写入操作,例如 POST、PATCH 和 DELETE 请求,以及 SMTP 提交。请求日志不记录读取操作,因此请单独检查只执行读取的客户端:enforced 模式同样会拒绝它们。
强制执行 mTLS
- 将每个集成迁移到 mTLS 端点。
- 在 Mode 中选择 Enforced,然后选择 Save。
此后,标准端点会以 E02090 拒绝该工作区使用 API 密钥、OAuth 令牌或服务账号令牌发出的请求。
托管的 MCP 服务器无法访问该工作区。请改用 Bird CLI 的本地 MCP 服务器。
SMTP 端点会以 535 5.7.8 拒绝该工作区的 AUTH。已打开的 SMTP 会话会在下一条消息时收到 530 5.7.0。请改为通过 mTLS 端点上的 API 发送电子邮件。
对 CA 或必需 SAN 的更改最多需要 15 分钟才能对每个请求生效。
使用 Bird CLI
Bird CLI 及其本地 MCP 服务器(bird mcp)通过以下设置出示你的客户端证书:
| 设置 | 标志 | 环境变量 |
|---|---|---|
| 证书链,PEM 格式,叶证书在前 | --client-cert | BIRD_CLIENT_CERT |
| 私钥,PEM 格式,未加密 | --client-key | BIRD_CLIENT_KEY |
| 将请求发送到 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 --mtls如需在 OAuth 登录时保留这些设置,请将这三个标志传给 bird auth login。配置文件会保存文件路径,之后的命令无需标志即可使用 mTLS 端点。bird auth status 会显示证书的 SHA-256 指纹和到期时间。
使用 SDK
向 SDK 提供证书链(PEM 格式,叶证书在前)及其私钥(PEM 格式,未加密)的路径。SDK 会在每个请求中出示证书,并将请求发送到你的 API 密钥所属区域的 mTLS 端点。如果你设置了基础 URL,SDK 会使用该 URL。
如果你同时提供证书和自己的 HTTP 客户端,SDK 会拒绝。要使用你自己的 HTTP 客户端,请在该客户端上配置证书,并将基础 URL 设置为 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;在 webhook 投递中出示客户端证书
我们会生成一个 RSA 2048 密钥对和一个主题为 CN=<workspace ID>, O=Bird 的 CSR。私钥由我们保管。您的 CA 签署该 CSR,当您的接收端请求证书时,我们会出示签署后的证书。
我们会在 webhook 订阅和直接回调(包括重试)中出示该证书。以下投递不会出示证书:
realtime.*事件- 连接器端点
- MCP Events 订阅
| 模式 | 投递行为 |
|---|---|
disabled | 我们不出示证书。 |
evaluating | 接收端请求证书时,我们出示证书。如果接收端拒绝该证书,我们会不带证书再次投递。 |
enforced | 我们出示证书。如果接收端未请求证书或拒绝该证书,本次投递尝试失败。 |
签署并上传证书
- 打开 Webhooks > mTLS。
- 在 Certificate 中,选择 Create signing request。
- 在 Signing request 中,选择 Download。
- 让您的 CA 为该 CSR 签名,并加入
clientAuth扩展密钥用法。 - 选择 Upload certificate。
- 先粘贴已签名的证书,再按顺序粘贴每个中间证书。您也可以选择文件。
- 选择 Upload certificate。
我们会检查该证书是否与签名请求的密钥匹配、是否具有 clientAuth 扩展密钥用法,以及是否处于有效期内。随后,Certificate 部分会显示证书的主体、颁发者、序列号、SHA-256 指纹和有效期。
配置接收端
- 在 TLS 握手期间请求客户端证书。
- 信任为我们的证书签名的 CA。
- 出示由公共受信任 CA 颁发、且与接收端主机名匹配的服务器证书。
如果只接受我们的证书,而不接受您的 CA 颁发的其他证书,请匹配主体 CN=<workspace ID> 或 SHA-256 指纹。
强制启用 Webhook mTLS
- 在 Mode 中选择 Evaluating,然后选择 Save。
- 使用
POST /v1/webhooks/{webhook_id}/test向每个 webhook 发送一个测试事件。确认client_certificate为presented。not_requested表示接收端没有请求证书,rejected表示接收端没有接受证书。 - SMS 回调 URL 没有 webhook ID。对于这类 URL,请发送一个 SMS,并将
options.callback_url设为该接收端。查看接收端的日志,确认回调出示了我们的证书。在evaluating模式下,被拒绝的证书还会在GET /v1/webhook-callbacks/attempts中显示为带有failure_reason的失败尝试。 - 在 Mode 中选择 Enforced,然后选择 Save。
在 enforced 模式下,被拒绝的证书会在该 webhook 的投递尝试中显示为失败尝试。
检查吊销状态
将 Certificate revocation list check 设为 Full chain,即可通过证书吊销列表(CRL)检查吊销状态。
- 对于 API 请求,我们会检查客户端证书,以及您的 CA 之下的每个中间证书。
- 对于 webhook 投递,我们会检查您接收端的服务器证书,以及其根证书之下的每个中间证书。
我们会检查证书的每个 CRL 分发点。同一分发点的 http 和 https URI 是同一 CRL 的镜像,我们使用第一个响应的镜像。没有 http 或 https URI 的分发点无法通过检查。没有 CRL 分发点的证书不会被检查。我们会验证每个 CRL 的签名。如果无法获取有效的 CRL,我们会拒绝该请求,或将该投递尝试判定为失败。
| 限制 | 值 |
|---|---|
| CRL 下载时间 | 每次下载 5 秒,每个请求 10 秒 |
| CRL 大小 | 10 MiB |
| 每个工作区的 CRL 数量 | API 请求 10 个,webhook 投递 10 个 |
轮换证书
在 CA 或 webhook 客户端证书到期前 30 天和 7 天,我们会向工作区联系人发送电子邮件。
要轮换 API 请求的 CA:
- 添加新 CA。此时工作区同时信任两个 CA。
- 将每个集成切换为使用新 CA 签发的客户端证书。
- 移除旧 CA。
当模式为 evaluating 或 enforced 时,您无法移除最后一个 CA。在 Bird 模式下,由您的 CA 签发的客户端证书无需任何操作。
轮换 webhook 客户端证书:
- 选择 Create new signing request。
- 让新的 CSR 完成签名,然后上传证书。
在您上传新证书之前,当前证书会继续使用。测试发送会立即使用新证书,但投递在最多几分钟内仍可能出示旧证书。在此之前,您的接收端必须通过 CA 或指纹同时接受这两个证书。
使用 API 实现自动化
每个控制台操作都有对应的 API 操作。请将这些调用发送到您的模式所接受的端点:disabled 或 evaluating 模式下使用标准端点,enforced 模式下使用 mTLS 端点并附带客户端证书。API 密钥需要具有 access_restrictions 范围的写入权限。组织主密钥无法调用这些操作。
| 操作 | 作用 |
|---|---|
PATCH /v1/workspace/mtls-settings | 更改 state、expected_san 或 crl_check |
POST /v1/workspace/mtls-certificate-authorities | 添加 CA |
DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id} | 移除 CA |
PATCH /v1/workspace/webhook-client-certificate | 更改 state 或 crl_check |
POST /v1/workspace/webhook-client-certificate/signing-request | 创建 CSR |
POST /v1/workspace/webhook-client-certificate/certificate | 上传已签名的证书 |
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"}'故障排查
未通过检查的 API 请求会返回 401,并附带以下代码之一:
| 代码 | 原因 |
|---|---|
E02086 | 请求未提供客户端证书。 |
E02087 | 客户端证书对该工作区无效。 |
E02088 | 证书链中有证书已被吊销。 |
E02089 | 模式为 disabled,因此 mTLS 端点拒绝该请求。 |
E02090 | 模式为 enforced,因此标准端点拒绝该请求。 |
E02091 | 我们未能在 5 秒内下载 CRL。 |
E02092 | CRL 大于 10 MiB。 |
E02093 | 该工作区已使用 10 个 CRL。 |
E02094 | CRL 的签名无效,或已超过其下次更新时间。 |
更改设置时可能返回以下代码之一:
后续步骤
- 身份验证:API 密钥、权限范围和服务账号
- Webhook 与事件:创建端点并验证签名
- 错误:错误响应及其处理方式