通过 X.509 工作负载身份联合,工作负载可以使用 TLS 客户端证书中的身份换取短期 OpenAI 访问令牌。随后,工作负载同时使用访问令牌和符合要求的客户端证书调用 OpenAI API。在此流程中,访问令牌取代了 API 密钥,客户端证书仍然必需。
OpenAI API 支持 X.509 工作负载身份联合。Codex 不支持此方式。请在 Codex 中使用 OIDC 令牌或 SPIFFE JWT-SVID。
有关令牌交换请求和响应的详细信息,请参阅工作负载身份令牌交换参考。有关双向 TLS 权限、证书要求、证书激活、mTLS 主机和证书轮换,请参阅双向 TLS 指南。
工作原理
X.509 工作负载身份交换分为五个步骤:
- 您的组织在现有的双向 TLS 设置中上传并激活受信任的根证书。
- X.509 工作负载身份提供方从经验证的客户端证书中派生
openai.*属性。其中必须包含一个非空的openai.subject值。 - 服务账号映射授权该派生身份使用某个项目中的一个 OpenAI 服务账号。
- 工作负载向
mtls.auth.openai.com上的 X.509 令牌端点出示证书,请求短期持有者令牌。证书通过 TLS 连接提供,请求体中不包含subject_token。 - 工作负载向
mtls.api.openai.com上的 API 路由出示持有者令牌和客户端证书,以获得 API 授权。
在处理 API 请求时,OpenAI 会分别检查持有者令牌和证书是否满足授权要求。仅凭证书无法获得调用 OpenAI API 的授权。
准备工作
您需要具备以下权限和资源:
- 管理组织的双向 TLS 证书和工作负载身份提供方的权限。
- 供工作负载使用的项目和服务账号。
- 客户端证书及其私钥,以及构建通往受信任根证书的证书链所需的所有中间证书。
- 已在组织或项目级别激活的受信任根证书。
请将私钥保存在版本控制系统之外,仅允许使用该私钥的工作负载访问它。请勿将私钥、证书内容或返回的访问令牌写入日志。
配置双向 TLS 证书信任
X.509 工作负载身份提供方复用组织现有的双向 TLS 证书配置。提供方不会上传证书,也不维护单独的证书信任库。
请参阅双向 TLS 指南,了解证书要求、mTLS 主机、证书激活后的行为、CEL 过滤器和客户端配置。然后打开组织设置 > 安全 > 双向 TLS,上传 PEM 格式的受信任证书,并为整个组织或每个将使用 X.509 工作负载身份联合的项目激活该证书。
如果客户端证书通过中间证书链接到根证书,请配置稳定的信任锚点,并在 TLS 握手期间先出示叶证书,再依次出示当前的中间证书。OpenAI 使用请求中提供的中间证书,不会从证书中的 URL 获取缺失的中间证书。
配置 X.509 提供方
要配置 X.509 提供方,请按以下步骤操作:
- 打开组织设置 > 安全 > 工作负载身份提供方,然后选择创建身份提供方。
- 选择 X.509 作为提供方类型,然后输入名称,也可以填写描述。X.509 提供方不使用 OIDC 的颁发者、受众、发现或 JWKS 设置。创建后无法更改提供方类型。
- 在高级设置下,您可以为属性条件添加 CEL 表达式,在查找匹配的映射之前拒绝不符合条件的证书。
- 在属性转换下,为必填的
openai.subject转换输入非空表达式。当您选择 X.509 时,控制台会添加subject行,并显示和应用openai.前缀。请选择能稳定标识工作负载的证书字段。 - 您可以添加其他转换,为每项转换指定唯一的
openai.*名称,然后选择创建。
例如,以下配置使用证书的通用名称作为规范主体标识,并将组织单位作为额外的映射属性:
[
{
"attribute": "openai.subject",
"expression": "assertion.subject.common_name"
},
{
"attribute": "openai.environment",
"expression": "assertion.subject.organizational_unit"
}
]
您可以通过 assertion.subject 和 assertion.subject_alt_names 访问证书字段。用于映射的转换结果必须是标量值。每项额外转换都必须使用唯一的 openai.* 名称。
例如,以下属性条件表达式将提供方可接受的证书限定为生产环境证书:
assertion.subject.organizational_unit == "Production"
创建服务账号映射
- 在 X.509 提供方详情页上,选择创建映射。
- 选择目标项目和服务账号,仅授予工作负载所需的 API 权限。
- 在键和值字段中指定
openai.subject必须精确匹配的值。X.509 映射允许不设置断言,此时用空对象({})表示。如果设置断言,所有键都必须以openai.开头。 - 选择创建。
例如:
| 键 | 值 |
|---|---|
openai.subject |
payments-service-prod |
X.509 映射使用派生的 openai.* 属性,不会匹配 sub、iss 或 aud 等原始 JWT 声明。
提供方列表中显示提供方 ID,映射详情中显示所选服务账号及其 ID。请记下这两个 ID,工作负载会在交换令牌时发送它们。
在 SDK 中使用 X.509 工作负载身份
为证书链、私钥、提供方和服务账号设置环境变量:
export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"
export OPENAI_IDENTITY_PROVIDER_ID="idp_example"
export OPENAI_SERVICE_ACCOUNT_ID="svc_acct_example"
在证书链文件中,应先放置叶证书,再依次放置中间证书(如有)。请勿在请求体中包含证书材料或 subject_token。
使用这些值配置 OpenAI SDK 客户端。SDK 会在令牌交换和 API 请求期间出示客户端证书,将 API 请求路由到 mTLS 端点,并自动续期短期访问令牌。
import { readFile } from "node:fs/promises";
import OpenAI from "openai";
import { workloadIdentity } from "openai/auth/x509-transport";
const certificatePath = process.env.OPENAI_MTLS_CERT_CHAIN;
const privateKeyPath = process.env.OPENAI_MTLS_KEY;
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;
if (
!certificatePath ||
!privateKeyPath ||
!identityProviderId ||
!serviceAccountId
) {
throw new Error(
"Set OPENAI_MTLS_CERT_CHAIN, OPENAI_MTLS_KEY, OPENAI_IDENTITY_PROVIDER_ID, and OPENAI_SERVICE_ACCOUNT_ID"
);
}
const credential = workloadIdentity.fromX509({
certificateChain: await readFile(certificatePath, "utf8"),
privateKey: await readFile(privateKeyPath, "utf8"),
identityProviderId,
serviceAccountId,
});
try {
const client = new OpenAI({ credential });
const response = await client.responses.create({
model: "gpt-6.1-terra",
input: "Say hello from X.509 workload identity federation.",
});
console.log(response.output_text);
} finally {
await credential.close();
}这些示例需要支持上述 X.509 配置的 OpenAI SDK。各语言的最低 SDK 版本为 TypeScript 7.8.0(还需安装对等依赖 undici)、Python 3.6.0、Go 3.54.0、Java 4.55.0 和 Ruby 0.83.0。
Java 示例加载 PKCS12 密钥库来构建 X509ExtendedKeyManager,并使用平台的默认信任库构建 X509TrustManager。运行此示例时,请设置 OPENAI_X509_KEYSTORE_PATH、OPENAI_X509_KEYSTORE_PASSWORD 和 OPENAI_X509_CERTIFICATE_ALIAS。您也可以向 SDK 提供基于 PEM 或硬件的管理器。
手动使用证书换取令牌
要直接检查或实现令牌交换协议,请向 X.509 令牌端点出示证书:
curl --cert "$OPENAI_MTLS_CERT_CHAIN" \
--key "$OPENAI_MTLS_KEY" \
--request POST "https://mtls.auth.openai.com/oauth/token" \
--header "Content-Type: application/json" \
--data @- <<JSON
{
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token_type": "urn:openai:params:oauth:token-type:x509",
"identity_provider_id": "${OPENAI_IDENTITY_PROVIDER_ID}",
"service_account_id": "${OPENAI_SERVICE_ACCOUNT_ID}"
}
JSON
交换成功后,端点会返回一个常规的短期持有者令牌:
{
"access_token": "eyJ...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600,
"expires_at": 1789045200,
"scope": "api.model.read api.model.request"
}
只有当匹配的服务账号映射具有权限时,响应才会包含 scope 属性。
上述有效期数值仅为示例。如果经验证的客户端证书更早到期,返回的令牌有效期可能更短。请参阅令牌交换响应字段,了解 expires_in 和 expires_at 的单位及含义。
从成功响应中读取 access_token 的值,并将其存入应用的凭据存储或 OPENAI_WIF_ACCESS_TOKEN 等环境变量。请妥善保密,不要打印该值、将其写入日志或提交到版本控制系统。
手动调用 OpenAI API
将 OPENAI_MODEL 设置为当前默认模型 gpt-6.2-astra,或目标项目可用的其他模型。然后向 API 的 mTLS 端点发送持有者令牌,并出示符合要求的客户端证书:
curl --request POST \
--cert "$OPENAI_MTLS_CERT_CHAIN" \
--key "$OPENAI_MTLS_KEY" \
--header "Authorization: Bearer $OPENAI_WIF_ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data "{\"model\":\"$OPENAI_MODEL\",\"input\":\"Say hello in one sentence.\"}" \
"https://mtls.api.openai.com/v1/responses"
使用持有者令牌代替 API 密钥,并在发送 API 请求时继续出示符合要求的客户端证书。
持有者令牌与证书之间没有密码学绑定。最简单的配置是在 API 请求中使用交换令牌时出示的证书。您也可以使用另一张证书,只要该证书本身满足当前同一套 API mTLS 策略即可。
令牌有效期和续期
X.509 工作负载身份令牌的有效期最长为一小时,且到期时间不会晚于经验证的客户端证书的到期时间。交换操作不会返回刷新令牌。要获取新的访问令牌,请再次使用证书交换令牌。
手动交换令牌时,请将 expires_at 与访问令牌一起保存,并安排在该时间戳之前再次交换令牌。请为时钟偏差和请求延迟预留时间。有关示例,请参阅令牌续期指南。
轮换中间证书时,无需更改已配置的根证书。在后续令牌交换和 API 请求中,请出示新的完整证书链。
排查令牌交换问题
X.509 令牌交换会返回通用 OAuth 错误,不会披露有关证书、根证书、提供方或映射的详细信息。
| 结果 | 常见原因 |
|---|---|
HTTP 403 |
请求的方法或路径与 POST /oauth/token 不完全匹配。该端点位于 mtls.auth.openai.com。 |
invalid_subject_token |
TLS 客户端证书缺失或无效,出示的证书链无法追溯到已激活的根证书,证书不在有效期内,或双向 TLS 证书准入规则拒绝了该证书。 |
invalid_grant |
提供方或映射无效或已停用,提供方的属性条件表达式拒绝了该身份,没有适用的根证书处于激活状态,或没有匹配的映射。 |
| 服务器错误 | OpenAI 返回了临时服务器错误。请按您通常用于处理临时错误的策略重试。 |
X.509 交换不会回退到 OIDC 或常规 OAuth 流程。
限制
- X.509 工作负载身份提供方不维护单独的证书信任库。
- 持有者令牌不与证书绑定,也不使用 DPoP 或
cnf声明。 - 使用证书换取令牌后,仍无法仅凭证书获得 API 授权。API 请求仍需提供持有者令牌和符合要求的客户端证书。
- OpenAI 不会从 AIA URL 获取缺失的中间证书。请在 TLS 协商期间出示完整证书链。
- 在此流程中,OpenAI 不会执行证书吊销列表(CRL)或 OCSP 检查。制定证书安全事件响应计划时,请考虑如何通过双向 TLS 根证书、提供方和映射控制访问,并考虑已签发令牌的短有效期。
- 此流程不支持 SPIFFE X.509-SVID。SPIFFE 指南仍使用 JWT-SVID。