OpenAI Terraform 项目与访问权限

本文创建一个 OpenAI 项目并建立可复用的访问控制：使用项目角色定义身份可以执行的操作，通过组织群组归集身份，再将群组与项目关联。

完成主要流程后，你将得到一套可重复使用的配置，用于：

为应用创建 OpenAI 项目。
定义遵循最小权限原则的项目角色。
为需要访问权限的身份创建组织群组。
通过角色授予群组访问项目的权限。
将已有组织用户加入群组。

开始之前

完成 Terraform 提供程序配置，并将管理 API 密钥导出为 OPENAI_ADMIN_KEY。你还需要一个已有组织用户的 ID，以及应用获准使用的权限标识符。评估此流程时使用测试组织。

销毁 openai_project 会归档项目，而不是永久删除项目。已归档项目无法恢复。

创建项目边界

为应用创建项目：

来源示例 1（terraform）：

## [中文] 声明应用项目，生成的project_id供其他项目资源引用；应用后创建项目。
resource "openai_project" "application" {
  name = "example-application-development"
}

项目为应用的 API 用量、服务账户、速率限制、支出告警和项目设置划定边界。Terraform 通过 openai_project.application.project_id 提供生成的项目 ID。项目级资源可引用这个值，从而让 Terraform 先创建项目，再创建这些资源。

这个聚焦示例使用具体名称，后面的完整示例会将其替换为变量，以便跨环境复用配置。

定义项目权限

使用应用获准的权限创建项目角色：

来源示例 2（terraform）：

## [中文] 声明仅具备读取Webhook配置权限的项目角色；替换为应用获准的最小权限集合。
resource "openai_project_role" "application" {
  project_id  = openai_project.application.project_id
  role_name   = "Application API access"
  description = "Permissions approved for this application"
  permissions = ["api.webhooks.read"]
}

openai_project_role 定义身份在项目内可以执行的操作。示例授予读取 Webhook 配置的权限。将 api.webhooks.read 替换为应用经过批准的权限标识符，并从应用确实需要的权限开始。

修改 permissions 会更新角色。应用变更前运行 terraform plan，检查每项新增或移除的权限。

创建或复用群组

如果群组生命周期应由 Terraform 管理，则创建组织群组：

来源示例 3（terraform）：

## [中文] 声明由Terraform管理生命周期的组织群组，后续通过角色分配授予项目权限。
resource "openai_group" "application_access" {
  name = "example-application-development-access"
}

群组存在于组织级别，可以跨项目复用。名称以 -access 结尾，表示成员身份会带来访问权限，而不仅用于描述团队。

如果已有群组由其他系统管理，则只读取它：

来源示例 4（terraform）：

## [中文] 只读取已有组织群组，不接管其生命周期，也不修改SCIM成员关系。
data "openai_group" "application_access" {
  group_id = "group_123"
}

数据源读取群组，但不会让当前配置承担该群组的生命周期管理责任。你可以读取由 SCIM 管理的群组，但成员关系的变更应继续在负责管理它们的身份系统中进行。

授予群组项目访问权限

在项目内，将群组与自定义角色关联：

来源示例 5（terraform）：

## [中文] 将项目、群组与自定义项目角色关联，群组成员由此继承该项目角色。
resource "openai_project_group_role" "application_access" {
  project_id = openai_project.application.project_id
  group_id   = openai_group.application_access.group_id
  role_id    = openai_project_role.application.role_id
}

此示例使用 Terraform 管理的群组。如果通过数据源复用了已有群组，请将 group_id 表达式替换为 data.openai_group.application_access.group_id。

角色分配关联三个对象：

project_id：指定群组在哪个项目获得访问权限。
group_id：指定哪一组身份获得权限。
role_id：指定群组获得哪些权限。

群组成员继承该项目中的自定义角色。仅创建角色或群组并不会授予访问权限；角色分配将两者连接起来。

添加用户及其他身份

通过 openai_group_user 将身份加入 Terraform 管理的组织群组：

来源示例 6（terraform）：

## [中文] 将已有用户加入受管群组；user_id也可使用服务账户的身份ID，成员关系变更会影响继承权限。
resource "openai_group_user" "application_developer" {
  group_id = openai_group.application_access.group_id
  user_id  = "user_123"
}

user_id 可以标识已有组织用户或服务账户。添加服务账户时，将 openai_project_service_account.application.id 用作 user_id。基于群组的服务账户访问、认证及凭证生命周期要求见服务账户。

如果不适合通过群组授予访问权限，可直接分配角色：

来源示例 7（terraform）：

## [中文] 直接向项目内的已有用户分配自定义角色，用于不适合群组授权的场景。
resource "openai_project_user_role" "application_developer" {
  project_id = openai_project.application.project_id
  user_id    = "user_123"
  role_id    = openai_project_role.application.role_id
}

如需组织范围的权限，可创建组织角色并直接分配，或通过群组分配：

来源示例 8（terraform）：

## [中文] 通过变量声明组织级权限集合，创建组织角色并直接分配给用户；组织角色与项目角色作用域不同。
variable "organization_role_permissions" {
  type = list(string)
}

resource "openai_role" "platform_operator" {
  role_name   = "Platform operator"
  description = "Organization permissions for the platform team"
  permissions = var.organization_role_permissions
}

resource "openai_user_role" "platform_operator" {
  user_id = "user_123"
  role_id = openai_role.platform_operator.role_id
}

将 organization_role_permissions 设置为经过批准的组织级权限标识符。组织权限与项目权限应分别配置，使每次分配都保持在所需的最小作用域。

检查当前角色分配

修改访问权限前，读取某个身份已获分配的组织角色和项目角色：

来源示例 9（terraform）：

## [中文] 只读取用户的组织与项目角色分配并输出，不接管这些分配关系。
data "openai_user_roles" "current" {
  user_id = "user_123"
}

data "openai_project_user_roles" "current" {
  project_id = openai_project.application.project_id
  user_id    = "user_123"
}

output "organization_roles" {
  value = data.openai_user_roles.current.roles
}

output "project_roles" {
  value = data.openai_project_user_roles.current.roles
}

数据源只报告当前分配，不会让 Terraform 接管这些分配关系。

移除角色分配

如果 Terraform 已在管理某项分配，从配置中移除其资源块后，下一个计划会提出删除远程分配。检查计划，并确认仍有其他路径授予必须保留的访问权限。

对于预先存在的分配，应先声明匹配的资源，再使用文档规定的复合 ID 导入。确认第一个计划无变更后，才将它从配置中移除，并应用删除操作。

Terraform 只能移除已记录在其状态中的分配。要移除已有默认分配，先将其导入相应的 Terraform 资源，再从配置中移除该资源，应用由此产生的销毁计划。如果组织不允许这种“先导入再销毁”的流程，则通过批准的控制台或管理 API 流程移除分配。

导入格式及安全的接管顺序见导入与状态协调。

运行完整示例

前面的聚焦示例使用具体值，以便说明各种关联。完整配置将重复出现、随环境变化的值改为变量，使你不必修改资源定义便可复用。

将以下配置保存为 main.tf：

来源示例 10（terraform）：

## [中文] 完整创建应用项目、自定义项目角色、组织群组、群组角色分配和用户成员关系；资源引用使项目及依赖先后创建。
terraform {
  required_version = ">= 1.0"

  required_providers {
    openai = {
      source  = "openai/openai"
      version = ">= 1.0.0"
    }
  }
}

provider "openai" {}

variable "project_name" {
  type = string
}

variable "project_role_permissions" {
  type = list(string)
}

variable "user_id" {
  type = string
}

resource "openai_project" "application" {
  name = var.project_name
}

resource "openai_project_role" "application" {
  project_id  = openai_project.application.project_id
  role_name   = "Application API access"
  description = "Permissions approved for this application"
  permissions = var.project_role_permissions
}

resource "openai_group" "application_access" {
  name = "${var.project_name}-access"
}

resource "openai_project_group_role" "application_access" {
  project_id = openai_project.application.project_id
  group_id   = openai_group.application_access.group_id
  role_id    = openai_project_role.application.role_id
}

resource "openai_group_user" "application_developer" {
  group_id = openai_group.application_access.group_id
  user_id  = var.user_id
}

output "project_id" {
  value = openai_project.application.project_id
}

output "group_id" {
  value = openai_group.application_access.group_id
}

output "project_role_id" {
  value = openai_project_role.application.role_id
}

创建 terraform.tfvars，填入唯一项目名称、已有组织用户 ID 和经过批准的权限：

来源示例 11（terraform）：

## [中文] 填写唯一项目名称、已有组织用户ID和经过批准的项目权限；不要扩大权限集合。
project_name = "example-application-development"
user_id      = "user_123"

project_role_permissions = [
  "api.webhooks.read",
]

初始化 Terraform，然后检查并应用保存的计划：

来源示例 12（bash）：

## [中文] 初始化并检查配置，保存及查看计划后应用；预期新增五个资源，应用后再次生成计划验证无变更。
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan

第一个计划应包含五个待新增资源。应用后，用户会通过群组继承自定义项目角色，terraform output 会输出项目、群组和项目角色的 ID。再次运行 terraform plan，确认配置不再产生变更。

添加更多人员用户时，为每个用户使用唯一的 Terraform 资源名称，重复群组成员关系配置。非人类身份的配置见服务账户。通过模型、工具与数据控制以及速率限制与支出为项目增加约束。