双向 TLS(mTLS)为 OpenAI API 请求增加了 TLS 客户端证书验证。在组织或项目中激活受信任的证书后,该范围内的请求除了提供常规的 Bearer 凭据,还必须提供符合验证要求的客户端证书。
如果工作负载能够安全保管客户端私钥,并且您希望 OpenAI 在授权 API 请求前通过证书验证工作负载的身份,可以使用 mTLS。mTLS 不能替代 API 密钥、服务账号凭据或工作负载身份访问令牌。
X.509 工作负载身份联合使用相同的已激活 mTLS 信任锚。通过证书交换获得短期 Bearer 令牌后,后续 API 调用仍需同时发送该令牌和符合 API mTLS 验证要求的证书。请参阅使用 X.509 证书配置工作负载身份联合。
配置 mTLS 前的准备
任何 API 组织都可以通过常规的基于角色的访问控制 (RBAC) 管理 mTLS:
api.mtls.read允许主体列出、查看和测试证书设置。api.mtls.write允许主体上传、更新、激活、停用和删除证书。
组织所有者角色包含这些权限,您也可以通过自定义角色授予这些权限。有关详细信息,请参阅管理 OpenAI 平台权限。
请做好以下准备:
- 为每个工作负载准备客户端证书及其私钥。
- 准备构建从客户端证书到信任锚的路径所需的所有中间证书。
- 准备一个稳定的、采用 PEM 编码的信任锚,以便在组织或项目级别激活。
- 为生产流量启用 mTLS 之前,准备一个非关键项目,并测试恢复方案。
请勿将私钥纳入版本控制,也不要将私钥、证书内容或 Bearer 凭据写入日志。
上传并激活信任锚
上传只会存储证书。激活证书后,才会对相应请求强制执行 mTLS 验证。
- 打开组织设置 > 安全 > 双向 TLS。
- 为每个证书对象上传一个采用 PEM 编码的信任锚。为其命名时,请注明颁发机构和轮换代次。
- 如有需要,添加 CEL 过滤器,限定该信任锚可以接受哪些已通过验证的客户端证书。
- 先在一个非关键项目中激活证书。让每个预计会使用该证书的工作负载通过 mTLS API 主机发送有代表性的请求。
- 验证成功后,再为其他项目或整个组织激活证书。
您也可以通过 API 管理证书:
| 任务 | 端点 |
|---|---|
| 上传证书 | POST /v1/organization/certificates |
| 列出组织证书 | GET /v1/organization/certificates |
| 获取、更新或删除证书 | GET、POST 或 DELETE /v1/organization/certificates/{certificate_id} |
| 为组织激活或停用证书 | POST /v1/organization/certificates/activate 或 POST /v1/organization/certificates/deactivate |
| 列出项目证书,或为项目激活或停用证书 | GET /v1/organization/projects/{project_id}/certificates、POST /v1/organization/projects/{project_id}/certificates/activate 或 POST /v1/organization/projects/{project_id}/certificates/deactivate |
请使用具备所需 api.mtls.read 或 api.mtls.write 权限的凭据。有关请求和响应的模式,请参阅组织证书 API 参考。
证书要求
每个证书对象应使用一个采用 PEM 编码的信任锚。上传的内容必须包含有效证书,且证书在上传时的剩余有效期必须超过一天。客户端证书必须包含颁发机构密钥标识符(AKI),以供验证请求时使用。
请求必须满足以下条件才能通过 mTLS 验证:
- 客户端证书在请求时必须有效,且适用于 TLS 客户端身份验证。
- 必须能够构建一条从客户端证书到已激活的组织级或项目级信任锚的有效路径。
- 如果路径包含中间证书,客户端必须在 TLS 握手期间提供这些证书。
- 配置的信任锚和客户端证书链必须通过标准的 X.509 客户端证书路径验证。
如果一次上传多个采用 PEM 编码的证书,验证请求所提供的证书链时,只会使用配置中的第一个证书作为信任锚。请勿依赖 PEM 证书包的处理规则。
OpenAI 不会从颁发机构信息访问(AIA)URL 获取缺失的中间证书,也不会执行证书吊销列表(CRL)或在线证书状态协议(OCSP)检查。请提供所需的完整证书链,并通过轮换证书、停用证书以及您自己的证书生命周期管理措施来应对安全事件。
了解验证顺序
OpenAI 先检查已激活的项目级证书,再检查已激活的组织级证书。如果这两个范围内都没有已激活的证书,mTLS 就不会对请求增加证书检查。
存在已激活的证书时,OpenAI 按以下顺序验证客户端身份:
- OpenAI 首先尝试现有的直接验证方式,直接使用已激活的信任锚验证客户端证书,不使用请求中的中间证书。
- 如果直接验证正常执行但未找到匹配项,OpenAI 会使用 TLS 连接中提供的客户端证书和中间证书,尝试验证请求提供的证书链。
- 如果证书路径通过验证,并且已激活的证书配置了 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。
例如,以下表达式要求证书中的组织单位为 Production,且至少有一个 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.openai.com |
默认的 API mTLS 主机。 |
mtls-us.api.openai.com |
美国区域的 API mTLS 主机。 |
mtls-eu.api.openai.com |
欧盟区域的 API mTLS 主机。 |
mTLS 按主机启用。请使用您在相应 API 上调用的同一 /v1 路由,并测试工作负载使用的每个 API 和模型。不同区域主机提供的路由和模型可能有所不同。
例如,向默认的 mTLS 主机发送常规 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 身份验证。有关完整的请求格式,请参阅工作负载身份令牌交换参考。
轮换证书
轮换信任锚时,请留出新旧信任锚同时生效的过渡期,以确保现有工作负载持续运行:
- 上传新的信任锚,同时保持旧信任锚处于激活状态。
- 在每个目标项目中或在组织级别激活新信任锚。
- 更新工作负载,使其提供的客户端证书能通过证书链追溯到新信任锚,然后测试这些工作负载使用的每个 mTLS 主机和 API 接口。
- 所有工作负载都完成迁移后,停用旧信任锚。
- 只有在组织和所有项目中都已停用旧证书后,才能将其删除。
您可以在不更改已配置信任锚的情况下轮换中间证书。请在后续请求中提供新的完整证书链。
排查请求问题
您可以根据稳定的错误码区分配置错误和临时服务错误:
| 错误码 | 排查要点 |
|---|---|
certificate_required |
有已激活的证书适用于该请求,但请求未提供所需的客户端证书材料。 |
invalid_certificate |
OpenAI 无法解码或解析客户端证书,或者证书缺少验证所需的 AKI。 |
certificate_verification_failed |
客户端证书或提供的证书链无法追溯到已激活的信任锚。 |
certificate_attribute_verification_failed |
证书路径已通过验证,但 CEL 过滤器拒绝了已通过验证的客户端证书。 |
authentication_temporarily_unavailable |
验证器超时、内部依赖项错误或 CEL 求值器错误导致服务返回 HTTP 503。请按常规的临时错误处理策略重试。 |
对于证书管理请求,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 专用网络访问 API,请参阅 Private Link。
- 支持的 API mTLS 主机为
mtls.api.openai.com、mtls-us.api.openai.com和mtls-eu.api.openai.com。请勿假定其他区域的 API 主机都有对应的 mTLS 主机。 - X.509 工作负载身份联合不会返回刷新令牌,也不使用 DPoP、
cnf声明或与证书绑定的 Bearer 令牌。请参阅使用 X.509 证书配置工作负载身份联合。