如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

使用 X.509 证书配置工作负载身份联合

使用经验证的客户端证书身份换取短期 OpenAI 访问令牌。

通过 X.509 工作负载身份联合,工作负载可以使用 TLS 客户端证书中的身份换取短期 OpenAI 访问令牌。随后,工作负载同时使用访问令牌和符合要求的客户端证书调用 OpenAI API。在此流程中,访问令牌取代了 API 密钥,客户端证书仍然必需。

OpenAI API 支持 X.509 工作负载身份联合。Codex 不支持此方式。请在 Codex 中使用 OIDC 令牌或 SPIFFE JWT-SVID。

有关令牌交换请求和响应的详细信息,请参阅工作负载身份令牌交换参考。有关双向 TLS 权限、证书要求、证书激活、mTLS 主机和证书轮换,请参阅双向 TLS 指南。

工作原理

X.509 工作负载身份交换分为五个步骤:

  1. 您的组织在现有的双向 TLS 设置中上传并激活受信任的根证书。
  2. X.509 工作负载身份提供方从经验证的客户端证书中派生 openai.* 属性。其中必须包含一个非空的 openai.subject 值。
  3. 服务账号映射授权该派生身份使用某个项目中的一个 OpenAI 服务账号。
  4. 工作负载向 mtls.auth.openai.com 上的 X.509 令牌端点出示证书,请求短期持有者令牌。证书通过 TLS 连接提供,请求体中不包含 subject_token。
  5. 工作负载向 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 提供方,请按以下步骤操作:

  1. 打开组织设置 > 安全 > 工作负载身份提供方,然后选择创建身份提供方。
  2. 选择 X.509 作为提供方类型,然后输入名称,也可以填写描述。X.509 提供方不使用 OIDC 的颁发者、受众、发现或 JWKS 设置。创建后无法更改提供方类型。
  3. 在高级设置下,您可以为属性条件添加 CEL 表达式,在查找匹配的映射之前拒绝不符合条件的证书。
  4. 在属性转换下,为必填的 openai.subject 转换输入非空表达式。当您选择 X.509 时,控制台会添加 subject 行,并显示和应用 openai. 前缀。请选择能稳定标识工作负载的证书字段。
  5. 您可以添加其他转换,为每项转换指定唯一的 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"

创建服务账号映射

  1. 在 X.509 提供方详情页上,选择创建映射。
  2. 选择目标项目和服务账号,仅授予工作负载所需的 API 权限。
  3. 在键和值字段中指定 openai.subject 必须精确匹配的值。X.509 映射允许不设置断言,此时用空对象({})表示。如果设置断言,所有键都必须以 openai. 开头。
  4. 选择创建。

例如:

键 值
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 端点,并自动续期短期访问令牌。

使用 X.509 客户端证书进行身份验证
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。