双向 TLS

双向 TLS（mTLS）为 OpenAI API 请求增加了 TLS 客户端证书验证。在您为组织或项目激活受信任的证书后，该范围内的请求除了提供常规的 bearer 凭证，还必须提供可接受的客户端证书。

如果工作负载能够安全地保管客户端私钥，并且您希望 OpenAI 在授权 API 请求之前验证其证书身份，请使用 mTLS。mTLS 不会取代 API 密钥、服务账户凭证或工作负载身份访问令牌。

配置 mTLS 前的准备工作

任何 API 组织都可以通过常规的基于角色的访问控制（RBAC）来管理 mTLS：

• api.mtls.read 允许主体列出、查看和测试证书设置。
• api.mtls.write 允许主体上传、更新、激活、停用和 删除证书。

组织所有者角色包含这些权限，但您也可以 通过自定义角色授予这些权限。有关更多信息，请参阅在 OpenAI 平台中 管理权限。

请准备：

• 每个工作负载的客户端证书及其私钥。
• 构建从客户端证书到您的信任锚的路径所需的所有中间证书。
• 一个稳定的 PEM 编码信任锚，可在组织或项目级别激活。
• 在为生产环境流量启用 mTLS 之前，准备一个非关键项目和经过测试的恢复方案。

不要将私钥纳入源代码版本控制。不要在日志中记录私钥、证书内容或 bearer 凭证。

上传并激活信任锚

上传操作只会存储证书，不会强制执行 mTLS。激活证书才会改变请求行为。

1. 打开组织设置 > 安全 > 双向 TLS。
2. 为每个证书对象上传一个 PEM 编码的信任锚。为其指定一个能够标识颁发机构和轮换代次的名称。
3. 您可以选择添加一个 CEL 过滤器， 限制该信任锚可接受哪些已通过验证的客户端证书。
4. 先为一个非关键项目激活证书。 让每个预期使用的工作负载通过 mTLS API 主机 发送具有代表性的请求。
5. 验证成功后，再为其他项目或组织激活证书。

您也可以通过 API 管理证书：

请使用具有所需 api.mtls.read 或 api.mtls.write 权限的凭证。有关请求和响应的模式，请参阅组织 证书 API 参考。

证书要求

每个证书对象应使用一个 PEM 编码的信任锚。上传内容必须包含有效证书，且该证书在上传后的剩余有效期必须超过一天。客户端证书必须包含颁发机构密钥标识符（AKI），以用于请求验证。

要使请求通过 mTLS 验证，必须满足以下条件：

• 客户端证书在请求时必须有效，并且适用于 TLS 客户端身份验证。
• 客户端证书必须能够构建一条通向已激活的组织级或项目级信任锚的有效路径。
• 如果路径包含中间证书，客户端必须在 TLS 握手期间提供这些证书。
• 配置的信任锚和客户端证书链必须通过标准的 X.509 客户端证书路径验证。

如果上传内容包含多个 PEM 编码的证书，请求证书链验证只会使用配置中的第一个证书作为信任锚；请勿依赖 PEM 证书包语义。

OpenAI 不会从颁发机构信息访问（AIA）URL 获取缺失的中间证书，也不会执行证书吊销列表（CRL）或在线证书状态协议（OCSP）检查。请提供所需的完整证书链，并通过证书轮换、停用以及您自己的证书生命周期控制措施来应对安全事件。

了解验证顺序

OpenAI 会先检查已激活的项目级证书，再检查已激活的组织级证书。如果这两个范围内都没有已激活的证书，mTLS 不会对请求增加证书检查。

存在已激活的证书时，OpenAI 会按以下顺序验证客户端身份：

1. OpenAI 首先尝试现有的直接验证路径，不使用请求中的中间证书，直接依据已激活的信任锚验证客户端证书。
2. 如果直接验证路径正常执行但未找到匹配项，OpenAI 会使用 TLS 连接提供的客户端证书和中间证书，尝试进行请求证书链验证。
3. 如果某条路径通过验证，且已激活的证书配置了 CEL 过滤器，OpenAI 就会针对已通过验证的客户端证书计算该过滤器的结果。

请求证书链验证默认可用。

请求证书链路径是在正常执行但未找到匹配项后使用的回退路径，并非用于恢复所有直接验证路径错误的途径。如果证书材料缺失或格式错误、缺少 AKI，或直接验证路径选定信任锚后出现确定性错误，请求可能会直接失败，而不会尝试使用提供的证书链。

使用 CEL 过滤客户端证书

您可以为已上传的证书附加一个通用表达式语言（CEL）过滤器，限制该信任锚可接受哪些已通过验证的客户端证书。表达式的计算结果必须为布尔值，并且在直接验证路径和请求证书链路径中都会针对已通过验证的客户端证书运行。

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 位于指定的命名空间内：

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

如果证书通过验证但不符合过滤条件，请求将失败并返回 certificate_attribute_verification_failed。如果策略未通过验证，OpenAI 会在您保存时拒绝该策略。

使用 mTLS 主机

将 API 流量发送到 mTLS 主机，而非 api.openai.com：

mTLS 基于主机生效。请使用您在相应 API 接口上调用的同一 /v1 路由， 并测试您的工作负载使用的每个 API 和模型。 不同区域主机支持的路由和模型可能有所不同。

例如，将常规持有者凭据和客户端证书发送到默认 mTLS 主机：

1234567export 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。此交换会生成 短期有效的持有者 Token；它不提供仅凭证书进行 API 身份验证的功能。 如需了解完整的请求结构，请参阅工作负载身份 Token 交换 参考资料。

轮换证书

轮换信任锚时，请保留新旧信任锚同时有效的过渡期，以确保现有工作负载持续运行：

1. 上传新的信任锚，同时保持旧信任锚处于激活状态。
2. 在每个目标项目中或在组织级别激活新信任锚。
3. 更新工作负载，使其提供可通过证书链连接到新信任锚的客户端证书，然后测试它们使用的每个 mTLS 主机和 API 接口。
4. 所有工作负载迁移完成后，停用旧信任锚。
5. 只有在组织及每个项目中停用旧证书后，才能将其删除。

您可以轮换中间证书，无需更改已配置的信任锚。请在后续请求中提供新的完整证书链。

排查请求问题

使用稳定的错误代码来区分配置错误和临时服务错误：

对于管理请求，mtls_certificate_invalid 表示上传的 PEM 未通过验证；expired_certificate 表示证书的剩余有效期过短 或已过期；mtls_cel_policy_invalid 表示过滤器未通过验证； certificate_in_use 表示您必须先停用证书， 然后才能将其删除。

当前限制

• 一个组织最多可以上传 50 个证书对象。
• mTLS 在常规 API 身份验证的基础上增加了证书验证；它不提供仅凭证书进行 API 授权的功能。
• OpenAI 不会通过 AIA 获取中间证书，也不会执行 CRL 或 OCSP 检查。
• Private Link 与 mTLS 不兼容。如果您需要使用专用 Azure 网络路径， 请参阅 Private Link。
• 支持的 API mTLS 主机为 mtls.api.openai.com、 mtls-us.api.openai.com 和 mtls-eu.api.openai.com。请勿假定 其他每个区域 API 主机都有对应的 mTLS 主机。
• X.509 工作负载身份联合不会返回刷新 Token， 也不使用 DPoP、cnf 声明或与证书绑定的持有者 Token。请参阅 使用 X.509 证书 配置工作负载身份联合。