本指南說明如何建立 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 管理,從組態中移除對應的資源區塊後,下一次產生的計畫就會列出要刪除的遠端指派。請檢查計畫,並確認仍可透過其他途徑取得所需的存取權。
對於尚未納入管理的既有指派,請先宣告對應的資源,再使用文件指定的複合 ID 匯入指派。確認匯入後的第一份計畫不會造成任何變更,再從組態中移除該資源並套用刪除操作。
Terraform 只能移除已記錄在其狀態中的指派。若要移除現有的預設指派,請先將其匯入對應的 Terraform 資源,再從組態中移除該資源,並套用由此產生的銷毀計畫。如果組織不允許先匯入再銷毀的流程,請依照核准的程序,透過儀表板或 Administration API 移除該指派。
如需瞭解匯入格式,以及如何安全地將既有資源納入管理,請參閱匯入與狀態核對。
執行完整範例
前面的範例直接指定各項設定值,方便你看清資源之間的關係。完整組態改用變數來設定重複出現且因環境而異的值,讓你無須修改資源定義就能重複使用這份組態。
將以下組態儲存為 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。再次執行 terraform plan,確認這份組態不會產生其他變更。
若要加入更多真人使用者,請比照上述方式為每位使用者設定群組成員資格,並為每人指定不同的 Terraform 資源名稱。若要設定非人類身分,請參閱服務帳戶。若要為專案增設防護措施,請參閱模型、工具與資料控制及速率限制與支出。