OpenAI 工作负载身份令牌交换

配置受信任的身份提供方和服务账户映射后，可以使用本参考文档，将外部签发的身份令牌交换为短期 OpenAI 访问令牌。本文也介绍 X.509 证书交换。概念、控制台配置和设置步骤见工作负载身份联邦指南。

交换 JWT 主体令牌

在 OpenAI 令牌端点交换外部主体令牌：

来源示例 1（bash）：

## [中文] 将外部OIDC令牌及已配置的身份提供方、服务账户ID提交到JWT令牌交换端点；请求scope不会额外授予权限。
curl https://auth.openai.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "subject_token": "'"$EXTERNAL_OIDC_JWT"'",
    "identity_provider_id": "'"$IDENTITY_PROVIDER_ID"'",
    "service_account_id": "'"$SERVICE_ACCOUNT_ID"'"
  }'

请求参数

令牌交换使用匹配的服务账户映射上配置的权限。请求体中的 scope 值不会授予访问权限。

交换 X.509 证书

在与专用 X.509 令牌端点进行 TLS 协商时提交客户端证书。不要在请求体中包含 subject_token。

身份提供方和服务账户映射的配置步骤见 X.509 证书设置指南。证书要求、激活、mTLS 主机、CEL 筛选条件和轮换方式见双向 TLS 指南。

来源示例 2（bash）：

## [中文] 在TLS协商时提交证书链和私钥，用X.509模式交换访问令牌；证书路径与映射ID来自安全配置，请求体不传subject_token。
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

X.509 请求参数

X.509 端点只接受发往 mtls.auth.openai.com 的精确 POST /oauth/token 请求。其他方法和路径返回 HTTP 403。

身份验证过程

JWT 主体令牌验证

解析映射前，OpenAI 会验证外部主体令牌。令牌必须满足以下条件：

• 是 JWT，头部包含 kid 和受支持的 alg。
• 包含 iss、aud、sub、exp 和 iat 声明。
• 与所配置的工作负载身份提供方的签发方和受众一致。
• 使用所配置 JWKS 来源中的密钥签名。

如果验证失败，令牌交换返回身份验证错误，不会签发 OpenAI 访问令牌。

主体令牌验证成功后，OpenAI 会根据令牌的原始声明和派生属性，解析所请求的服务账户映射。映射不匹配时，令牌交换会在映射解析阶段失败。

X.509 证书验证

OpenAI 根据已解析的组织和项目上下文中处于启用状态的双向 TLS 根证书，验证客户端证书。客户端必须提交构建证书链所需的所有中间证书；OpenAI 不会从证书 URL 下载缺失的中间证书。

验证证书时，OpenAI 会应用启用的双向 TLS 根证书所配置的证书准入规则。验证成功后，OpenAI 求值身份提供方的 Attribute conditions（属性条件），派生其 openai.* 属性，并为所请求的服务账户解析出恰好一个已启用的映射。X.509 身份提供方必须派生出一个非空的 openai.subject 值。

证书材料格式错误或缺失、证书链无效、根证书不匹配、证书不在有效期内，或被双向 TLS 证书准入规则拒绝，都会返回 invalid_subject_token。被身份提供方的 Attribute conditions（属性条件） 表达式拒绝时，返回 invalid_grant。其他身份提供方、映射或启用根证书的配置错误也会返回 invalid_grant。X.509 请求绝不会回退到 OIDC 或其他 OAuth 流程。

响应

成功响应包含一个短期 Bearer 令牌：

来源示例 3（json）：

中文译释：

access_token为访问令牌；issued_token_type为签发的令牌类型；token_type: Bearer为Bearer令牌；expires_in: 3600示意从签发时起3600秒的有效期；expires_at为绝对过期Unix时间戳；scope列出映射授予的权限，此处为api.model.read和api.model.request。这些值仅供格式演示，不是可用凭证或有效期承诺。

{
  "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"
}

JWT 和 X.509 两种交换的响应都包含以下过期字段：

只有解析得到的映射配置了权限，响应才会返回 scope 属性。访问令牌最多一小时后过期。JWT 交换得到的令牌不会比外部主体令牌存活更久；X.509 交换得到的令牌也不会比经过验证的客户端证书存活更久。令牌交换不会返回刷新令牌。

示例中的过期值仅用于演示。如果外部主体令牌或经过验证的客户端证书更早过期，实际返回的有效期会更短。如何安排下一次交换，见令牌续期指南。

令牌交换错误

令牌交换失败时，OpenAI 不会签发访问令牌。常见原因如下：

多数主体令牌问题可以通过在本地解码 JWT 载荷，并将其 iss、aud、sub、exp、iat 及身份提供方专用声明，与工作负载身份提供方及服务账户映射配置逐项比较来排查。

如果令牌交换成功，但之后的 OpenAI API 请求失败，应将已签发访问令牌的问题作为授权问题排查。它仍受到普通 OpenAI API 请求适用的项目、服务账户、端点授权、IP 允许列表和其他策略检查约束。对于 X.509 工作负载，向 mtls.api.openai.com 发送 API 请求时，还必须提交受接受的客户端证书。

授权行为

工作负载身份访问令牌由 OpenAI 服务账户和项目支持。在 OpenAI API 中，它们按服务账户 API 凭证的方式进行授权，而不是按用户 OAuth 令牌的方式授权。

如果映射定义了权限，这些权限会进一步缩小通过该映射签发的令牌的有效 API 访问范围。如果映射没有定义权限，OpenAI 不会额外施加工作负载身份联邦专属的 scope 限制，而是根据所映射服务账户的项目和组织角色决定授权。

工作负载身份令牌不会绕过常规端点授权。目标端点仍必须允许令牌所携带的有效权限和项目访问范围。

对于 X.509 交换，Bearer 令牌替代的是 API 密钥，而不是客户端证书。Bearer 凭证与 API mTLS 证书分别验证。Bearer 令牌不与证书绑定，也不使用 DPoP 或 cnf 声明。

限制

工作负载身份联邦目前有以下限制：

• 工作负载身份访问令牌不能调用 Admin API 端点。Admin API 应使用管理员 API 密钥。
• 每个组织最多创建 50 个工作负载身份提供方。每个提供方最多配置 50 个服务账户映射。
• 以下端点不接受工作负载身份访问令牌：DELETE /v1/models/{id} 和 POST /v1/images/request_audit。
• 暂不支持设置指南所列提供方以外的任意 OIDC 签发方端点。
• X.509 工作负载身份提供方复用启用的双向 TLS 根证书，不使用独立的证书信任存储。
• X.509 证书交换不执行证书吊销列表（CRL）或 OCSP 检查。
• SPIFFE 支持仅限 JWT-SVID 主体令牌。这个令牌交换端点不支持 X.509-SVID。