---
title: "mTLS"
description: "通过 mTLS 端点要求 API 请求提供客户端证书，并在向你的接收端投递 webhook 时出示客户端证书。"
canonical: "https://bird.com/zh-sg/wendang/guides/mtls"
availability: "on-request"
---

# mTLS

双向 TLS（mTLS）在 TLS 握手中为双方各加一道证书检查。每个方向都有各自的设置。你可以只设置一个方向，也可以同时设置两个方向。

| 方向         | TLS 客户端 | TLS 服务器 | 设置                                                                            |
| ------------ | ---------- | ---------- | ------------------------------------------------------------------------------- |
| API 请求     | 你的系统   | mTLS 端点  | [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls) |
| Webhook 投递 | 我们       | 你的接收端 | [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/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`](/docs/api/errors/E02090) 拒绝这些请求。       |
| [SMTP](/docs/guides/email/smtp) 提交               | 被拒绝。SMTP 无法出示客户端证书。                                   |
| 托管的 MCP 服务器                                  | 无法访问该工作区。它无法出示你的客户端证书。                        |
| 控制台会话                                         | 不受影响。                                                          |
| Automations                                        | 不受影响。                                                          |
| 使用组织凭据调用组织操作的请求                     | 不检查。该模式属于某个工作区，而这些请求不指定任何工作区。          |
| [SIP 中继](/docs/guides/voice/sip-trunks)          | 不受影响。中继继续使用允许的 API 密钥对呼叫进行身份验证，无需证书。 |

模式更改会立即对新请求生效。已打开的 SMTP 会话会在下一条消息时采用新模式。

有效的客户端证书须链接到该工作区的某个 CA，处于有效期内，并具有 `clientAuth` 扩展密钥用法。如果你设置了必需的使用者备用名称（SAN），证书还必须包含该名称。我们比对 DNS 名称和 URI，不使用通用名称。

### 添加证书颁发机构

1. 打开 [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls)。
2. 在 **Certificate authorities** 中，选择 **Add certificate authority**。
3. 粘贴你的 CA 的 PEM 证书，或选择一个文件。
4. 选择 **Add certificate authority**。

该证书必须具有 `CA:true` 基本约束和 `keyCertSign` 密钥用法，且不能已过期。一个工作区最多可以有两个 CA。

如果你的 CA 也向其他方颁发证书，请将 **Required subject alternative name** 设置为你的客户端证书所携带的身份。

### 在评估模式下测试

1. 在 **Mode** 中选择 **Evaluating**，然后选择 **Save**。
2. 将客户端配置为出示其证书。如果客户端证书由中间 CA 签名，还需发送中间证书。
3. 将客户端的基础 URL 改为 mTLS 端点。
4. 发送一个测试请求：

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

1. 将每个集成迁移到 mTLS 端点。
2. 在 **Mode** 中选择 **Enforced**，然后选择 **Save**。

此后，标准端点会以 [`E02090`](/docs/api/errors/E02090) 拒绝该工作区使用 API 密钥、OAuth 令牌或服务账号令牌发出的请求。

托管的 MCP 服务器无法访问该工作区。请改用 [Bird CLI](#使用-bird-cli) 的本地 MCP 服务器。

SMTP 端点会以 `535 5.7.8` 拒绝该工作区的 AUTH。已打开的 SMTP 会话会在下一条消息时收到 `530 5.7.0`。请改为通过 mTLS 端点上的 API 发送电子邮件。

对 CA 或必需 SAN 的更改最多需要 15 分钟才能对每个请求生效。

### 使用 Bird CLI

[Bird CLI](/docs/cli) 及其本地 MCP 服务器（`bird mcp`）通过以下设置出示你的客户端证书：

| 设置                         | 标志            | 环境变量           |
| ---------------------------- | --------------- | ------------------ |
| 证书链，PEM 格式，叶证书在前 | `--client-cert` | `BIRD_CLIENT_CERT` |
| 私钥，PEM 格式，未加密       | `--client-key`  | `BIRD_CLIENT_KEY`  |
| 将请求发送到 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
```

如需在 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 端点。

**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](/zh-sg/wendang/guides/mtls.ts.md) · [Python](/zh-sg/wendang/guides/mtls.py.md) · [Go](/zh-sg/wendang/guides/mtls.go.md) · [PHP](/zh-sg/wendang/guides/mtls.php.md)

## 在 webhook 投递中出示客户端证书

我们会生成一个 RSA 2048 密钥对和一个主题为 `CN=<workspace ID>, O=Bird` 的 CSR。私钥由我们保管。您的 CA 签署该 CSR，当您的接收端请求证书时，我们会出示签署后的证书。

我们会在 webhook 订阅和直接回调（包括重试）中出示该证书。以下投递不会出示证书：

- `realtime.*` 事件
- 连接器端点
- MCP Events 订阅

| 模式         | 投递行为                                                                       |
| ------------ | ------------------------------------------------------------------------------ |
| `disabled`   | 我们不出示证书。                                                               |
| `evaluating` | 接收端请求证书时，我们出示证书。如果接收端拒绝该证书，我们会不带证书再次投递。 |
| `enforced`   | 我们出示证书。如果接收端未请求证书或拒绝该证书，本次投递尝试失败。             |

### 签署并上传证书

1. 打开 [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls)。
2. 在 **Certificate** 中，选择 **Create signing request**。
3. 在 **Signing request** 中，选择 **Download**。
4. 让您的 CA 为该 CSR 签名，并加入 `clientAuth` 扩展密钥用法。
5. 选择 **Upload certificate**。
6. 先粘贴已签名的证书，再按顺序粘贴每个中间证书。您也可以选择文件。
7. 选择 **Upload certificate**。

我们会检查该证书是否与签名请求的密钥匹配、是否具有 `clientAuth` 扩展密钥用法，以及是否处于有效期内。随后，**Certificate** 部分会显示证书的主体、颁发者、序列号、SHA-256 指纹和有效期。

### 配置接收端

1. 在 TLS 握手期间请求客户端证书。
2. 信任为我们的证书签名的 CA。
3. 出示由公共受信任 CA 颁发、且与接收端主机名匹配的服务器证书。

如果只接受我们的证书，而不接受您的 CA 颁发的其他证书，请匹配主体 `CN=<workspace ID>` 或 SHA-256 指纹。

### 强制启用 Webhook mTLS

1. 在 **Mode** 中选择 **Evaluating**，然后选择 **Save**。
2. 使用 [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook) 向每个 webhook 发送一个测试事件。确认 `client_certificate` 为 `presented`。`not_requested` 表示接收端没有请求证书，`rejected` 表示接收端没有接受证书。
3. [SMS 回调 URL](/docs/guides/sms/callbacks) 没有 webhook ID。对于这类 URL，请发送一个 SMS，并将 `options.callback_url` 设为该接收端。查看接收端的日志，确认回调出示了我们的证书。在 `evaluating` 模式下，被拒绝的证书还会在 [`GET /v1/webhook-callbacks/attempts`](/docs/api/reference/list-webhook-callback-attempts) 中显示为带有 `failure_reason` 的失败尝试。
4. 在 **Mode** 中选择 **Enforced**，然后选择 **Save**。

在 `enforced` 模式下，被拒绝的证书会在该 webhook 的[投递尝试](/docs/guides/webhooks#replaying-failed-deliveries)中显示为失败尝试。

## 检查吊销状态

将 **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：

1. 添加新 CA。此时工作区同时信任两个 CA。
2. 将每个集成切换为使用新 CA 签发的客户端证书。
3. 移除旧 CA。

当模式为 `evaluating` 或 `enforced` 时，您无法移除最后一个 CA。在 Bird 模式下，由您的 CA 签发的客户端证书无需任何操作。

轮换 webhook 客户端证书：

1. 选择 **Create new signing request**。
2. 让新的 CSR 完成签名，然后上传证书。

在您上传新证书之前，当前证书会继续使用。测试发送会立即使用新证书，但投递在最多几分钟内仍可能出示旧证书。在此之前，您的接收端必须通过 CA 或指纹同时接受这两个证书。

## 使用 API 实现自动化

每个控制台操作都有对应的 API 操作。请将这些调用发送到您的模式所接受的端点：`disabled` 或 `evaluating` 模式下使用标准端点，`enforced` 模式下使用 mTLS 端点并附带客户端证书。API 密钥需要具有 `access_restrictions` 范围的写入权限。组织主密钥无法调用这些操作。

| 操作                                                                                                                                               | 作用                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| [`PATCH /v1/workspace/mtls-settings`](/docs/api/reference/update-workspace-mtls-settings)                                                          | 更改 `state`、`expected_san` 或 `crl_check` |
| [`POST /v1/workspace/mtls-certificate-authorities`](/docs/api/reference/create-workspace-mtls-certificate-authority)                               | 添加 CA                                     |
| [`DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}`](/docs/api/reference/delete-workspace-mtls-certificate-authority)  | 移除 CA                                     |
| [`PATCH /v1/workspace/webhook-client-certificate`](/docs/api/reference/update-workspace-webhook-client-certificate)                                | 更改 `state` 或 `crl_check`                 |
| [`POST /v1/workspace/webhook-client-certificate/signing-request`](/docs/api/reference/create-workspace-webhook-client-certificate-signing-request) | 创建 CSR                                    |
| [`POST /v1/workspace/webhook-client-certificate/certificate`](/docs/api/reference/submit-workspace-webhook-client-certificate)                     | 上传已签名的证书                            |

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

## 故障排查

未通过检查的 API 请求会返回 `401`，并附带以下代码之一：

| 代码                                | 原因                                          |
| ----------------------------------- | --------------------------------------------- |
| [`E02086`](/docs/api/errors/E02086) | 请求未提供客户端证书。                        |
| [`E02087`](/docs/api/errors/E02087) | 客户端证书对该工作区无效。                    |
| [`E02088`](/docs/api/errors/E02088) | 证书链中有证书已被吊销。                      |
| [`E02089`](/docs/api/errors/E02089) | 模式为 `disabled`，因此 mTLS 端点拒绝该请求。 |
| [`E02090`](/docs/api/errors/E02090) | 模式为 `enforced`，因此标准端点拒绝该请求。   |
| [`E02091`](/docs/api/errors/E02091) | 我们未能在 5 秒内下载 CRL。                   |
| [`E02092`](/docs/api/errors/E02092) | CRL 大于 10 MiB。                             |
| [`E02093`](/docs/api/errors/E02093) | 该工作区已使用 10 个 CRL。                    |
| [`E02094`](/docs/api/errors/E02094) | CRL 的签名无效，或已超过其下次更新时间。      |

更改设置时可能返回以下代码之一：

- [`E10027`](/docs/api/errors/E10027)：该工作区未启用 API mTLS。请联系你的 Bird 代表启用该功能。
- [`E10028`](/docs/api/errors/E10028)：该工作区未启用 Webhook mTLS。请联系你的 Bird 代表启用该功能。

## 后续步骤

- [身份验证](/docs/guides/authentication)：API 密钥、权限范围和服务账号
- [Webhook 与事件](/docs/guides/webhooks)：创建端点并验证签名
- [错误](/docs/guides/errors)：错误响应及其处理方式

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