使用 Terraform 管理專案與存取權

按照本指南建立 OpenAI 專案，並設定可重複使用的存取控制。你將透過專案角色定義各身分可執行的操作，將身分集中到組織群組中，再將群組連結至專案。

完成主要工作流程後，你將擁有一套可重複使用的組態，用來：

• 為應用程式建立 OpenAI 專案。
• 定義符合最小權限原則的專案角色。
• 為需要存取權的身分建立組織群組。
• 透過角色授予群組專案存取權。
• 將現有的組織使用者加入群組。

開始之前

完成 Terraform 供應器設定，並將管理 API 金鑰匯出為 OPENAI_ADMIN_KEY 環境變數。你還需要現有組織使用者的 ID，以及已核准供應用程式使用的權限識別碼。評估此工作流程時，請使用測試組織。

銷毀 openai_project 會將專案封存，而非永久刪除。已封存的專案無法還原。

建立專案邊界

為應用程式建立專案：

123resource "openai_project" "application" {
  name = "example-application-development"
}

專案為應用程式的 API 使用量、服務帳戶、速率限制、支出警示及專案設定劃定邊界。Terraform 會透過 openai_project.application.project_id 提供產生的 ID。專案層級的資源可以參照這個值，因此 Terraform 會先建立專案，再建立這些資源。

這個單項範例使用具體名稱。後面的完整範例會將名稱改為變數，讓你可以在不同環境中重複使用組態。

定義專案權限

建立專案角色，並賦予已核准供應用程式使用的權限：

123456resource "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 管理，請建立組織群組：

123resource "openai_group" "application_access" {
  name = "example-application-development-access"
}

群組存在於組織層級，可在不同專案間重複使用。名稱以 -access 結尾，表示加入該群組即可取得存取權，而不僅是用來標示團隊。

如果現有群組由其他系統管理，則改為讀取該群組：

123data "openai_group" "application_access" {
  group_id = "group_123"
}

資料來源會讀取群組，但不會讓這份組態負責管理其生命週期。你可以讀取由 SCIM 管理的群組，但成員資格的變更仍應在負責管理該群組的身分系統中進行。

授予群組專案存取權

將群組連結至專案內的自訂角色：

12345resource "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 管理的組織群組：

1234resource "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。如需了解透過群組授予服務帳戶存取權、身分驗證及憑證生命週期的相關要求，請參閱服務帳戶。

如果不適合透過群組授予存取權，請直接指派角色：

12345resource "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
}

若需要組織範圍的權限，請建立組織角色，並直接指派或透過群組指派：

1234567891011121314variable "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 設為已核准的組織層級權限識別碼。請將組織權限與專案權限分開，讓每項指派的範圍都限於必要的最小範圍。

檢查目前的指派

變更存取權前，請先讀取已指派給該身分的組織角色與專案角色：

12345678910111213141516data "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 匯入。確認第一份計畫不會進行任何變更後，再從組態中移除該資源並套用刪除作業。

如需了解匯入格式與安全的納管步驟，請參閱匯入與調和。

執行完整範例

各單項範例使用具體值，讓每項關係清楚易懂。完整組態會將重複出現且因環境而異的值改為變數，讓你不必變更資源定義就能重複使用組態。

將下列組態儲存為 main.tf：

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162terraform {
  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，以及已核准的權限：

123456project_name = "example-application-development"
user_id      = "user_123"

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

初始化 Terraform，然後審查並套用已儲存的計畫：

123456terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan

第一份計畫應包含五個待新增的資源。套用後，使用者會透過群組繼承自訂專案角色，而 terraform output 會輸出專案、群組與專案角色的 ID。請再次執行 terraform plan，確認組態不會產生其他變更。

若要新增更多真人使用者，請重複使用群組成員資格的設定方式，並為每位使用者指定唯一的 Terraform 資源名稱。若要設定非人類身分，請參閱服務帳戶。請依照模型、工具與資料控管和速率限制與支出的說明，新增專案防護機制。