双向 TLS（mTLS，Mutual TLS）让 API 网关在 TLS 握手期间验证客户端提供的 X.509 证书及其对相应私钥的持有，同时客户端也验证网关的服务端证书。当证书颁发机构、签发流程、身份映射和私钥保管都处于受控状态时，mTLS 是一种强有力的机器间身份认证机制。
mTLS 并不是完整的 API 授权。有效证书只能在一个信任域中建立客户端身份；路由、租户、操作和对象权限仍需明确策略。实际可运维性还取决于重叠轮换、吊销或短期证书、资产清单、监控，以及安全的信任锚变更。
核心要点
- 为每个主机名和环境定义哪些证书颁发机构可以签发客户端身份。
- 从经过审查的证书字段或注册表映射身份，不能依赖任意转发请求头。
- 区分身份认证、路由授权和应用对象授权。
- 轮换客户端证书和 CA Bundle 时，应设置重叠窗口和回滚方案。
- 上线前测试证书缺失、过期、不受信任、不匹配和即将过期等情况；验证实际 TLS 终止节点的吊销行为，或明确记录其不支持吊销检查。
放置 mTLS 信任边界
先确定 TLS 在哪里终止、由哪个节点认证客户端：
1flowchart LR
2 C[持有证书的客户端] -->|mTLS| G[API 网关]
3 G -->|已认证主体与策略| A[应用]
4 G -->|可选的独立 mTLS| U[上游服务]
5 I[证书颁发机构] --> C
6 I --> G客户端到网关的 mTLS 与网关到上游的 mTLS 是两条独立连接，使用不同身份和信任存储。如果 CDN 或负载均衡器在网关之前终止客户端 mTLS，网关就不再直接验证原始证书，而必须信任一条受保护连接，以及来自该特定中间节点的已认证声明，同时关闭直接绕过路径。
需要定义：
- 服务端主机名和证书归属；
- 接受的客户端 CA 根证书与中间证书；
- 证书规范、密钥用途、Subject/SAN 约定和最长有效期；
- 谁可以签发、续期、吊销和恢复客户端身份；
- 证书身份映射到工作负载、组织、设备还是集成；
- 身份认证后，路由授权和对象授权分别在哪里执行。
不要把证书等同于权限
TLS 层验证的是到受信任 CA 的证书链、证书有效时间，以及客户端是否持有私钥。它不会自动证明主体可以调用 /v1/payments、访问租户 A 或修改发票 123。
应把已验证证书映射到稳定的内部主体。与其随意解析自由格式的 Common Name，不如使用受治理的 SAN 规范或注册表绑定。比较前要规范化字段，显式处理重命名，并确保不同颁发者无法创建相互冲突的身份。
然后，在网关执行路由或操作级授权，在拥有数据的服务中执行资源级授权。如果要把身份转发给上游，应先删除客户端提供的同名字段，并保护网关到上游的路径，确保请求头无法被伪造。
在 APISIX 中配置客户端验证
Apache APISIX 3.18 的客户端到 APISIX mTLS 教程在与 SNI 关联的 SSL 资源上配置客户端验证。以下片段使用占位符，切勿把私钥粘贴进源码仓库：
1curl "http://127.0.0.1:9180/apisix/admin/ssls/partner-api" \
2 -X PUT \
3 -H "X-API-KEY: ${admin_key}" \
4 -d '{
5 "snis": ["partner-api.example.com"],
6 "cert": "<server-certificate-chain>",
7 "key": "<server-private-key-from-secret-workflow>",
8 "client": {
9 "ca": "<trusted-client-ca-bundle>",
10 "depth": 2
11 }
12 }'
该 SSL 资源把 client.ca 设为对应 SNI 的客户端证书验证信任锚。证书链深度应与预期层级一致，不要接受不必要的宽泛证书链。请根据实际部署版本的文档确认具体 Schema。
APISIX 提供证书指纹、序列号、Subject DN 等 TLS 变量，验证结果则由单独的 $ssl_client_verify 表示。官方教程演示了如何使用 proxy-rewrite 转发证书属性。只有当 $ssl_client_verify 表示验证成功，并且请求路径未绕过 mTLS 时，才能把这些属性作为身份上下文。如果上游需要这类上下文，只转发经过审查的字段，使用内部请求头名称，覆盖客户端传入的同名字段，并限制上游只接收来自网关的流量。原始 Subject DN 并不天然是规范化账号标识。
避免意外绕过 mTLS
APISIX 在客户端验证配置中支持 skip_mtls_uri_regex。绕过机制可能适合健康检查或引导端点，但会改变该 SNI 下所有匹配路径的信任边界。
如果已认证流量和公共流量具有明显不同的信任要求，优先使用独立主机名或监听器。若无法避免绕过：
- 锚定正则表达式，并审查百分号编码、规范化和路径匹配；
- 确保绕过端点无法触达受保护操作；
- 按需增加独立认证与流量控制；
- 测试近似路径和路由变更；
- 审计绕过列表的每次变更。
除非经过明确测试，否则不要假设路由授权能够弥补过宽的 TLS 绕过规则。
设计证书签发与轮换
最安全的轮换应该是常态化、自动化且可观察的：
- 通过经过认证的注册流程签发新客户端证书；
- 通过获准的密钥或设备工作流分发证书和私钥；
- 设置旧身份和新身份都可识别的重叠期；
- 按主体和客户端群体确认新证书已经成功使用；
- 按策略删除或吊销旧证书；
- 在清单中记录颁发者、序列号、主体、负责人、签发时间、到期时间和状态。
轮换 CA 时，应先分发新信任锚，再用其签发客户端证书。重叠期内，验证两条证书链均可正常使用，并确认没有信任意外颁发者。只有在所有必要客户端完成迁移并作出回滚决策后，才能删除旧根证书。
短期证书可以在吊销检查难以实施时缩短风险窗口，却会增强系统对自动签发的依赖。长期证书需要更强的吊销、清单、告警和紧急替换流程。应主动选择策略，不能只把到期当作唯一事故响应手段。
保护私钥与信任存储
- 当风险要求较高时，在硬件支持或托管密钥存储中生成并保存私钥。
- 如果客户端支持不可导出密钥，应阻止私钥导出。
- 限制可以修改客户端 CA、服务端密钥和 SSL 资源的人员。
- 分离生产与非生产颁发机构。
- 监控证书清单，并在到期前足够早地发出告警。
- 把信任存储和身份映射变更记录为审计事件。
- 把 CA 泄露视为信任域事故，而不是单个客户端轮换。
切勿在工单、示例、测试夹具或日志中包含真实私钥或生产证书。
定义故障与可用性行为
未配置 skip_mtls_uri_regex 时，客户端证书故障通常会在普通 HTTP 请求处理之前终止 TLS 握手。配置 skip_mtls_uri_regex 后，APISIX 会允许握手继续，以便检查 URI；如果路径不属于绕过范围，则会在请求处理阶段以 HTTP 400 拒绝缺少证书或证书无效的请求。客户端需要关于必须提供证书、证书链不受信任、证书过期、主机名和协议错误的运维指引，但公共端点不应返回敏感诊断细节。
需要规划：
- 证书颁发者和注册系统中断；
- 服务端或客户端证书过期；
- 证书链不完整和时钟错误；
- 各网关实例上的信任 Bundle 不一致；
- 客户端无法在计划窗口内完成轮换；
- 紧急移除一个主体或整个颁发者；
- TLS 握手对容量和延迟的影响。
故障期间不要创建一个静默移除客户端认证的通用公共后备入口。恢复流程应重新建立可信身份，或将流量迁移到经过明确批准的替代边界。
测试完整生命周期
使用预发布信任域和合成身份验证：
- 有效客户端和受信任证书链成功连接；
- 没有客户端证书、CA 不受信任、证书过期和证书链不完整时失败；
- 不使用不安全客户端参数也能验证服务端主机名和证书链；
- 映射得到的主体稳定，且无法被请求头覆盖；
- 持有有效证书但没有权限时，收到预期授权拒绝；
- 重叠期内新旧证书都可使用，重叠期结束后旧证书失效；
- CA Bundle 变更到达每个网关实例；
- 绕过规则只匹配预期端点；
- 日志包含有用的序列号或指纹引用，却不包含私钥或过多证书数据；
- 到期前和握手失败率异常时触发告警。
mTLS 就绪检查清单
- 客户端 TLS 在哪里终止，流量能否绕过该节点？
- 信任哪些颁发者、证书规范、名称和证书链深度？
- 如何把已验证证书映射到唯一内部主体？
- 哪些权限仍由网关和应用层分别负责？
- 客户端和 CA 能否通过重叠窗口完成轮换并支持回滚？
- 如何移除已泄露、过期和失去负责人的证书？
- 私钥是否不可导出，或是否获得足够保护？
- 绕过规则是否足够精确、经过测试且可审计？
- 是否在不关闭服务端验证的情况下通过所有负向和生命周期测试？
总结
当网关控制信任锚、客户端妥善保护私钥时，mTLS 可以提供强客户端身份认证。但生产安全远不止一次握手：还要定义身份映射、分离授权、关闭绕过路径、自动轮换、盘点证书，并演练颁发者和客户端故障。应把 PKI 生命周期视为 API 平台的一部分。
FAQ
mTLS 能替代 OAuth 或应用授权吗？
不能。mTLS 认证证书持有者；OAuth 可以传递委托权限；应用策略仍需决定该主体可以访问哪些资源、执行哪些操作。
身份应该取自证书 Common Name 吗？
只有当证书规范明确治理该字段并保证唯一映射时才适合这样做。经过审查的 SAN 约定或颁发者注册表通常更容易约束和演进。
API 网关可以在请求头中转发证书身份吗？
可以，但必须先完成验证，覆盖客户端提供的同名字段，并保护网关到上游的路径。上游只能信任网关是该请求头的来源。
后续步骤
身份认证之后，继续应用细粒度 API 网关授权，并通过 API 网关 TLS 性能指南测量握手路径。如需集中管理网关安全，可进一步了解 API7 企业版。