如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

使用 Terraform 管理專案與存取權

建立專案,並透過角色與群組設定存取權。

本指南說明如何建立 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 資源名稱。若要設定非人類身分,請參閱服務帳戶。若要為專案增設防護措施,請參閱模型、工具與資料控制及速率限制與支出。