OpenAI 双向 TLS

双向 TLS（mTLS）为 OpenAI API 增加 TLS 客户端证书验证。组织或项目激活受信任证书后，该范围的请求除正常 bearer 凭证外，还须提交被接受的客户端证书。

它适用于能安全保存客户端私钥、希望在 API 授权前验证证书身份的工作负载，不替代 API 密钥、服务账户凭证或工作负载身份访问令牌。X.509 身份联合复用活动 mTLS 信任锚，交换得到短期 bearer 令牌；之后 API 调用仍须同时提供令牌及被接受的证书。

配置 mTLS 前

任何 API 组织均可通过 RBAC 管理 mTLS：api.mtls.read 允许列出、查看、测试证书设置；api.mtls.write 允许上传、更新、激活、停用、删除。组织所有者拥有这些权限，也可通过自定义角色授予，参见权限管理。

准备每个工作负载的证书和私钥、连接到信任锚所需的中间证书、可在组织或项目激活的稳定 PEM 信任锚，以及生产启用前的非关键测试项目和已验证恢复路径。私钥不进入版本库，不记录私钥、证书内容或 bearer 凭证。

上传并激活信任

上传只保存证书，激活才改变请求行为。

1. 打开组织设置 > Security > Mutual TLS。
2. 每个证书对象上传一个 PEM 信任锚，名称标明签发机构与轮换批次。
3. 可添加 CEL 过滤器，约束该锚接受哪些已验证证书。
4. 先为非关键项目激活，从每个预期工作负载通过 mTLS 主机发送代表性请求。
5. 验证通过后为其他项目或组织激活。

也可通过管理接口操作：

凭证须具备对应的 api.mtls.read 或 api.mtls.write 权限。结构见组织证书参考。

证书要求

每个对象使用一个 PEM 信任锚。上传证书须有效，且到期时间在上传后超过一天。客户端证书必须带 Authority Key Identifier（AKI）。请求验证要求证书在当时有效、适合 TLS 客户端认证，并能形成通往活动组织/项目信任锚的有效路径；所需中间证书由客户端在握手时提供，信任锚及证书链须通过标准 X.509 客户端路径验证。

若上传多个 PEM 证书，请求链验证只使用配置中的第一个作为锚，不能依赖 PEM 捆绑包语义。OpenAI 不从 AIA URL 获取缺失中间证书，也不执行 CRL 或 OCSP 吊销检查。须提交完整链，并通过轮换、停用和自己的证书生命周期控制响应事件。

理解验证顺序

先检查活动项目级证书，再检查组织级证书。两个范围都无活动证书时，不增加证书检查。有活动证书时：

1. 先尝试原有直接路径，不使用请求中间证书，直接对活动锚验证客户端证书。
2. 普通不匹配后，再使用 TLS 提交的客户端和中间证书验证请求链。
3. 路径通过后，若该锚有 CEL 过滤器，再对已验证客户端证书执行过滤。

请求链验证默认可用，但只是普通不匹配的回退，不是所有直接路径错误的恢复机制。缺失/畸形证书、缺 AKI，或直接路径选定锚后的确定性错误，都可能直接失败而不尝试请求链。

用 CEL 过滤客户端证书

可为上传证书添加 Common Expression Language（CEL）表达式，必须返回布尔值，在直接和请求链路径上都针对已验证的客户端证书执行。可访问：

• subject.common_name、subject.country_code、subject.organization、subject.organizational_unit、subject.locality、subject.province、subject.street_address、subject.postal_code。
• subject_alt_names 列表，元素有 type、value、oid；SAN 类型包括 DNS、EMAIL、IP_ADDRESS、URI、CUSTOM。

下例要求生产组织单元和特定命名空间的 DNS SAN：

来源示例 1（text）：

中文说明：来源配置或结果示例，按所在小节的字段、作用域与权限要求解释；JSON保持合法格式，CEL/声明匹配文本不是可独立运行的应用。

subject.organizational_unit == "Production" &&
subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))

证书验证通过但不满足过滤器时，返回 certificate_attribute_verification_failed。保存时不通过校验的策略会被拒绝。

使用 mTLS 主机

API 流量使用下列主机，替代 api.openai.com：

mTLS 基于主机启用，沿用相应 API 的 /v1 路径。逐个测试工作负载使用的 API 与模型，不同区域主机的路由和模型可用性可能不同。

向默认主机同时发送正常 bearer 凭证和客户端证书：

来源示例 2（bash）：

## [中文] 客户端在本地使用私钥完成TLS握手签名，向mTLS主机呈交证书链，并在Authorization中携带正常Bearer凭证；私钥不发送，链中叶证书在前，不关闭服务器证书验证。
export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"

curl https://mtls.api.openai.com/v1/models \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_API_KEY"

证书链文件先放客户端证书，再放所需中间证书，不把证书放在 HTTP 请求头或请求体中。

X.509 交换使用独立且精确的 POST https://mtls.auth.openai.com/oauth/token，它产生短期 bearer 令牌，并不提供仅凭证书的 API 认证。请求结构见交换参考。

轮换证书

采用重叠轮换，避免中断：先上传新锚，不停用旧锚；在目标项目或组织激活新锚；工作负载改用链到新锚的证书并测试全部主机与 API；全部迁移后停用旧锚；仅在组织及所有项目均停用后删除旧证书。

中间证书可以在不改变信任锚的情况下轮换，后续请求提交新的完整链。

请求故障排查

通过稳定错误代码区分配置问题和暂时故障：

管理请求中，mtls_certificate_invalid 表示上传 PEM 不合格；expired_certificate 表示已到期或过早到期；mtls_cel_policy_invalid 表示过滤器不合格；certificate_in_use 表示删除前须先停用。

当前限制

• 每组织最多上传 50 个证书对象。
• mTLS 增加证书验证，不替代正常 API 认证与授权。
• 不获取 AIA 中间证书，不做 CRL/OCSP 检查。
• 与 Private Link 不兼容。
• 仅列出的 mtls.api.openai.com、mtls-us.api.openai.com、mtls-eu.api.openai.com 受支持，不假设每个区域都有对应 mTLS 主机。
• X.509 联合不返回刷新令牌，不使用 DPoP、cnf 或证书绑定 bearer 令牌；参见 X.509 配置。