按照本指南创建 OpenAI 项目,并设置可复用的访问控制。您将通过项目角色规定身份可在项目中执行哪些操作,将需要访问权限的身份加入组织组,再将该组与项目关联。
完成主要步骤后,您将得到一套可重复使用的配置,用于:
- 为应用创建 OpenAI 项目。
- 定义遵循最小权限原则的项目角色。
- 为需要访问权限的身份创建组织组。
- 通过项目角色向组授予项目访问权限。
- 将现有组织用户加入组。
开始之前
完成 Terraform 提供程序设置,并将管理 API 密钥导出为环境变量 OPENAI_ADMIN_KEY。您还需要一名现有组织用户的 ID,以及已获准供应用使用的权限标识符。评估此流程时,请使用测试组织。
销毁 openai_project 时,项目会被归档,而不会被永久删除。项目一旦归档便无法恢复。
划定项目范围
为应用创建项目:
resource "openai_project" "application" {
name = "example-application-development"
}
项目划定了应用的 API 用量、服务账号、速率限制、支出提醒和项目设置的管理范围。Terraform 通过 openai_project.application.project_id 提供生成的项目 ID。项目级资源可以引用此值,因此 Terraform 会先创建项目,再创建引用它的资源。
这个分步示例使用具体的项目名称。后面的完整示例改用变量,以便您在不同环境中复用配置。
定义项目权限
使用已获准供应用使用的权限创建项目角色:
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 管理组的生命周期,请创建一个组织组:
resource "openai_group" "application_access" {
name = "example-application-development-access"
}
组属于组织,可以跨项目复用。组名以 -access 结尾,表明加入该组即可获得访问权限,组名不只是团队名称。
如果现有组由其他系统管理,请通过数据源读取该组:
data "openai_group" "application_access" {
group_id = "group_123"
}
数据源会读取组的信息,组的生命周期仍由原系统管理。您可以读取通过 SCIM 管理的组,但如需更改成员关系,请在负责管理该组的身份系统中操作。
向组授予项目访问权限
在项目中将组与自定义角色关联:
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 管理的组织组:
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。有关如何通过组为服务账号授予访问权限,以及身份验证和凭据生命周期管理方面的要求,请参阅服务账号。
如果不适合通过组授予访问权限,请直接分配角色:
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
}
要授予适用于整个组织的权限,请创建组织角色,然后直接分配该角色,或通过组分配:
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 设为已获批准的组织级权限标识符列表。将组织权限与项目权限分开,确保每次分配的权限都限于所需的最小范围。
查看当前的角色分配
更改某个身份的访问权限之前,请查看已分配给该身份的组织角色和项目角色:
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 管理,从配置中移除其资源块后,下一次生成的执行计划就会列出要删除的远程角色分配。请检查计划,并确认仍可通过其他途径获得所需的访问权限。
对于已有但尚未纳入 Terraform 管理的角色分配,请先声明对应的资源,并按文档说明使用复合 ID 将其导入。确认首次生成的计划不包含任何变更后,再从配置中移除该资源并执行删除操作。
Terraform 只能移除已记录在其状态中的角色分配。要移除现有的默认角色分配,请先将其导入对应的 Terraform 资源。然后从配置中移除该资源,并应用由此生成的销毁计划。如果您的组织不允许先导入再销毁,请通过获准使用的控制台或管理 API 流程移除该分配。
有关导入格式以及如何安全地将现有资源纳入 Terraform 管理,请参阅导入与状态核对。
运行完整示例
前面的分步示例使用具体值来说明资源之间的关系。完整配置将反复出现且因环境而异的值替换为变量,以便您在不同环境中复用配置,无需修改资源定义。
将以下配置保存为 main.tf:
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 和已获批准的权限:
project_name = "example-application-development"
user_id = "user_123"
project_role_permissions = [
"api.webhooks.read",
]
初始化 Terraform,然后生成并保存执行计划,检查后再应用:
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan
首次生成的计划应列出五个待添加的资源。应用计划后,用户会通过组继承自定义项目角色,运行 terraform output 会输出项目 ID、组 ID 和项目角色 ID。再次运行 terraform plan,确认配置不会产生进一步变更。
要添加更多真人用户,请按上述方式将每位用户加入组,并为每位用户使用唯一的 Terraform 资源名称。要配置非人类身份,请参阅服务账号。要为项目设置使用限制和支出提醒,请参阅模型、工具和数据控制以及速率限制和支出。