工作负载身份联合

工作负载身份联合允许受信任的工作负载将外部颁发的身份令牌兑换为短期有效的 OpenAI 访问令牌。请使用以下指南来配置您的外部身份提供者、创建 OpenAI 服务账号映射，并在无需存储长期有效的 API 密钥的情况下对工作负载进行身份验证。

有关令牌兑换请求和响应的详细信息、授权行为以及当前的限制，请参阅 工作负载身份令牌兑换参考.

工作原理

工作负载身份联合包含四个部分：

1. A 工作负载身份提供者 用于描述受信任的颁发者。它存储了用于验证外部主体令牌的预期 OIDC 颁发者、受众和密钥来源。
2. A 服务账号映射 授权特定的外部令牌属性，以为项目内的特定 OpenAI 服务账号签发令牌。
3. A 令牌兑换 请求将外部主体令牌发送至 OpenAI，并返回一个短期有效的 OpenAI 访问令牌。
4. 工作负载使用 OpenAI 颁发的访问令牌作为持有者凭据，对向 OpenAI API 发起的请求进行身份验证。

您必须是组织所有者才能配置此功能。若要访问该功能，请前往 组织设置 > 安全 > 工作负载身份提供者。从工作负载身份提供商详情页配置服务账号映射。

选择一份设置指南

请从与您工作负载运行环境相匹配的指南开始：

OpenAI 支持文档中列出的、与 OIDC 兼容的 JWT 主体令牌配置。如果您需要未列出的 OIDC 提供者，请联系我们。

每个提供者指南都说明了如何在该平台上颁发和检查主体令牌，以及如何配置 OpenAI SDK 以将其兑换为短期有效的 OpenAI 访问令牌。

配置工作负载身份提供者

为您信任的每个外部颁发者创建一个工作负载身份提供者。工作负载身份联合支持 OIDC JWT 主体令牌。

工作负载身份提供者配置包含以下控制台选项：

使用 CEL 转换令牌声明

属性转换使用通用表达式语言 (CEL)。OpenAI 支持中指定的标准 CEL 运算符， langdef.md 并且不添加自定义的 Workload Identity Federation 特定函数。每个表达式接收一个根对象：

• assertion: 经过验证的 JWT 声明集。

In the dashboard, the openai. 前缀会自动应用。请输入后缀，例如 subject,以及一个表达式,例如 assertion.sub。API 会将派生属性存储为 openai.subject.

1
2
3
4
5
6
7
8
9
10
[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

使用 CEL 语言规范定义的 CEL 语法。例如，您可以使用如下表达式读取声明值 assertion.sub or assertion.repository。不支持的语法或函数会导致映射解析失败。

1
2
3
4
5
6
7
8
9
10
[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

转换结果必须是标量值：字符串、布尔值、整数或有限数字。数组、对象、null 值和求值错误会导致映射解析失败。OpenAI 会在将标量转换结果与映射值进行比较之前，将其转换为字符串。例如， true 变为 "true" and 7 变为 "7".

以下列前缀开头的映射键 openai. 仅从属性映射中解析。已经使用 openai. 前缀的原始主体令牌声明不会影响映射决策，除非您配置了匹配的映射规则。

管理 JWKS 和密钥轮换

OpenAI 使用在 Workload Identity Provider 上配置的密钥源来验证 OIDC 主体令牌。

• OIDC 发现： OpenAI 获取颁发者的 /.well-known/openid-configuration，然后获取所发现的 jwks_uri。发现文档和远程 JWKS 负载会被缓存 600 秒。
• 未命中时刷新密钥： 如果令牌 kid 未在缓存的 JWKS 中找到，OpenAI 会刷新 JWKS 并在拒绝该令牌之前再次尝试查找。
• 上传的 JWKS： 当 使用上传的 JWKS 进行令牌验证 处于启用状态时，OpenAI 将使用存储在 Workload Identity Provider 上的已上传 JWKS，并且不执行 OIDC 发现或远程 JWKS 获取。在保存提供者更新且该更新可用于令牌交换后，新的交换将使用已保存的 JWKS。
• 多个密钥： 一个 JWKS 可以包含多个公钥，并且每个密钥必须具有唯一的非空 kid.

在签名密钥轮换期间，请在轮换窗口期内同时在颁发者 JWKS 中发布新旧公钥。这允许由旧密钥签名的令牌继续有效，同时 OpenAI 也会接受由新密钥签名的令牌。对于已上传 JWKS 的模式，请在颁发使用新 kid;OpenAI 会拒绝由不在所配置 JWKS 中的密钥签名的令牌。

配置服务账号映射

服务账号映射定义了哪些外部身份可以为 OpenAI 服务账号生成访问令牌。

映射配置包含以下控制台选项：

属性断言值必须是标量 JSON 值。字符串值可以使用一个尾部通配符，例如 repo:example/*。通配符必须包含非空前缀； * 单独使用是不受支持的。

有效的通配符值：

• repo:openai/*
• repository:my-org/*

无效的通配符值：

• *
• repo:*:prod
• repo/*/main

控制台会将映射级别的限制显示为 权限。令牌交换响应暴露与 OAuth 作用域相同的限制，在 scope 属性。Admin API 权限范围无法分配给工作负载身份提供者映射，并且在 OpenAI 签发令牌后，下游 API 授权依然适用。

映射解析示例

在 OpenAI 验证外部主体令牌后，映射解析开始。OpenAI 会查找请求的映射 identity_provider_id and service_account_id, 跳过已禁用的映射，仅评估每个映射所需的属性，并且只有在恰好一个已启用的映射与所有已配置的属性匹配时才会颁发令牌。

例如，一个 GitHub Actions 令牌可能包含以下声明：

1
2
3
4
5
6
7
{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

Workload Identity Provider 可以定义一个派生属性：

1
2
3
4
5
6
[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

然后，服务账号映射可以同时要求原始属性和派生属性：

此映射仅当所有三个属性均匹配时才会生效。 sub 值使用了尾部通配符，因此它可以匹配任何具有前缀 repo:my-org/my-repo:。该 openai.repository_ref 的值，该键由属性转换解析而来；OpenAI 不会使用名为 openai.repository_ref.

的原始令牌声明。如果多个启用的映射匹配同一个令牌交换，OpenAI 会拒绝该交换。OpenAI 会为每个 (provider, service account) 对强制执行唯一映射，并且不会组合多个映射的权限。

安全建议

• 为每个应用或工作负载使用专用的 OpenAI 服务账号。
• 隔离生产环境和非生产环境。
• 优先使用精确的声明匹配，而不是宽泛的属性模式。
• 仅授予所需的最低 OpenAI 权限。
• 定期审查并移除未使用的映射。
• 监控令牌交换失败和异常的访问模式。
• 避免在无关的工作负载之间共享身份。