OpenAI 服務帳戶是隸屬於專案的非人員身分。你可以使用 Terraform 建立沒有預設角色的帳戶,依最小權限原則定義一組權限,再透過群組將這組權限授予帳戶。服務帳戶的 API 金鑰則需在 Terraform 之外透過管理 API 建立及管理。
本指南採用常見的服務帳戶設定流程:
- 建立服務帳戶時,不指派預設專案角色,也不產生 API 金鑰。
- 透過群組指派自訂專案角色,只授予工作負載所需的權限。
- 建立限定權限範圍的 API 金鑰,並將金鑰存入機密管理工具。
開始之前
完成 Terraform 提供者設定,將管理員 API 金鑰匯出為環境變數 OPENAI_ADMIN_KEY,並將現有專案的 ID 匯出為 PROJECT_ID。
評估服務帳戶的建立、匯入、替換及刪除操作時,請使用測試組織。
建立沒有預設角色的服務帳戶
使用 Terraform 建立服務帳戶:
resource "openai_project_service_account" "application" {
project_id = "proj_123"
name = "example-application-development-service-account"
}
output "service_account_id" {
value = openai_project_service_account.application.service_account_id
}
將 proj_123 換成服務帳戶所屬的現有專案 ID。
提供者會建立服務帳戶身分,但不會產生 API 金鑰或指派預設專案角色。Terraform 會將服務帳戶 ID 和其他非敏感中繼資料儲存在狀態中。此時,服務帳戶尚無任何專案權限。
依最小權限原則授權
定義自訂專案角色,只納入工作負載所需的權限。建立群組,將服務帳戶加入群組,再將角色指派給群組。以下範例允許群組成員建立回應:
resource "openai_project_role" "application" {
project_id = openai_project_service_account.application.project_id
role_name = "Application response writer"
description = "Allows the application to create responses"
permissions = ["api.responses.write"]
}
resource "openai_group" "application_access" {
name = "example-application-development-access"
}
resource "openai_group_user" "application" {
group_id = openai_group.application_access.group_id
user_id = openai_project_service_account.application.id
}
resource "openai_project_group_role" "application_access" {
project_id = openai_project_service_account.application.project_id
group_id = openai_group.application_access.group_id
role_id = openai_project_role.application.role_id
}
openai_project_role 資源定義工作負載所需的最小權限集合,openai_group_user 將服務帳戶加入群組,而 openai_project_group_role 將角色指派給該群組。加入群組的每個服務帳戶都會繼承相同的專案角色。請將 api.responses.write 換成已核准且足以執行工作負載的最小權限集合。如需進一步瞭解如何透過群組管理專案存取權,請參閱專案與存取權。
檢查並套用設定:
terraform plan
terraform apply
如果自訂專案角色已提供工作負載所需的權限,請勿指派內建的 member 或 owner 角色。僅授予已核准的那組權限。
建立限定權限範圍的 API 金鑰
套用 Terraform 設定後,透過建立專案服務帳戶 API 金鑰端點建立 API 金鑰。API 只會傳回一次完整的金鑰值,因此請在送出請求前設定存取權限,以保護回應檔案:
SERVICE_ACCOUNT_ID="$(terraform output -raw service_account_id)"
umask 077
curl -X POST \
"https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID/api_keys" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production App",
"scopes": ["api.responses.write"]
}' \
--output service-account-api-key.json
請將權限範圍限縮到工作負載所需的最低限度。API 金鑰的權限範圍可以進一步限制服務帳戶的權限,但無法授予超出該帳戶專案角色的權限。
將 value 欄位的值從 service-account-api-key.json 傳入已核准的機密管理流程,過程中請勿印出該值。機密管理工具儲存並驗證金鑰後,請刪除回應檔案:
rm service-account-api-key.json
只要 service-account-api-key.json 仍然存在,就必須將它視為機密。請勿將檔案提交至版本控制系統,也不要將金鑰寫入 Terraform 設定、透過 Terraform 輸出公開金鑰值,或將金鑰當成 Terraform 變數傳遞。
API 參考文件列出了回應結構及各程式語言的範例。支援工作負載身分聯盟的工作負載可使用相同的服務帳戶和最小權限角色,無須建立 API 金鑰。
匯入現有服務帳戶
使用 Terraform 建立的服務帳戶無須匯入。若要讓 Terraform 接管在其他地方建立的服務帳戶,請使用與現有帳戶相同的專案 ID 和帳戶名稱宣告資源:
resource "openai_project_service_account" "application" {
project_id = "proj_123"
name = "example-application-development-service-account"
}
在依一般流程套用設定之前,請先匯入現有身分:
SERVICE_ACCOUNT_ID="<existing-service-account-id>"
terraform import \
openai_project_service_account.application \
"$PROJECT_ID/$SERVICE_ACCOUNT_ID"
terraform plan
匯入後的第一份計畫應顯示服務帳戶無須變更。如果計畫顯示需要替換帳戶,請先調整設定,使名稱和專案與現有帳戶相符,再套用設定。
匯入服務帳戶不會取回或儲存 API 金鑰,也不會變更帳戶現有的專案角色或匯入其群組成員資格。若要讓 Terraform 管理這些資源,請宣告並匯入現有的 openai_project_role、openai_group、openai_group_user 和 openai_project_group_role 資源。工作負載會繼續從機密管理工具讀取現有的機密資料。
請先匯入服務帳戶,再套用資源宣告。如果先套用宣告,Terraform 會另外建立一個服務帳戶,無法接管現有身分。
復原或輪替憑證
只有建立 API 金鑰時的回應才會提供完整金鑰值。之後查詢專案 API 金鑰時,傳回的值會經過遮蔽,因此遺失的金鑰無法取回。
若憑證遺失或需要輪替,可依下列步驟更換憑證,讓工作負載持續運作:
- 將新帳戶宣告為新的
openai_project_service_account資源,並使用與舊帳戶不同的 Terraform 資源名稱。 - 套用設定以建立新的服務帳戶。
- 使用
openai_group_user將新帳戶加入現有群組,使其繼承最小權限專案角色。 - 透過管理 API 為新帳戶建立 API 金鑰,並依照已核准的機密管理流程儲存金鑰。
- 部署新金鑰,並確認工作負載使用新帳戶時能正常運作。
- 從 Terraform 設定中移除舊的
openai_project_service_account及其openai_group_user資源。保留新服務帳戶仍在使用的角色、群組及群組角色指派。 - 檢查並套用刪除舊服務帳戶及其群組成員資格的計畫,再執行
terraform plan,並確認結果顯示無須變更。
刪除 openai_project_service_account 資源會一併刪除遠端服務帳戶。這項變更必須經過明確審查,尤其是在工作負載仍使用舊憑證處理請求時。
如需進一步瞭解如何將資源納入 Terraform 狀態管理,以及移除資源時的行為,請參閱匯入與狀態調和。
執行完整範例
前面的範例使用具體的值,分別說明如何建立服務帳戶、指派角色及建立 API 金鑰。以下完整設定改用變數指定各專案的值和權限,方便你在不同環境中重複使用。
將以下設定儲存為 main.tf:
terraform {
required_version = ">= 1.0"
required_providers {
openai = {
source = "openai/openai"
version = ">= 1.0.0"
}
}
}
provider "openai" {}
variable "project_id" {
type = string
description = "ID of the existing OpenAI project."
}
variable "service_account_name" {
type = string
description = "Name of the application service account."
}
variable "project_role_permissions" {
type = list(string)
description = "Least-privilege project permissions for the application."
validation {
condition = length(var.project_role_permissions) > 0
error_message = "Provide at least one approved project permission."
}
}
resource "openai_project_service_account" "application" {
project_id = var.project_id
name = var.service_account_name
}
resource "openai_project_role" "application" {
project_id = var.project_id
role_name = "Application API access"
description = "Least-privilege permissions approved for the application"
permissions = var.project_role_permissions
}
resource "openai_group" "application_access" {
name = "${var.service_account_name}-access"
}
resource "openai_group_user" "application" {
group_id = openai_group.application_access.group_id
user_id = openai_project_service_account.application.id
}
resource "openai_project_group_role" "application_access" {
project_id = var.project_id
group_id = openai_group.application_access.group_id
role_id = openai_project_role.application.role_id
}
output "project_id" {
value = var.project_id
}
output "service_account_id" {
value = openai_project_service_account.application.service_account_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_id = "proj_123"
service_account_name = "example-application-development-service-account"
project_role_permissions = [
"api.responses.write",
]
初始化 Terraform,再檢查並套用已儲存的計畫:
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan
第一份計畫應列出五項要新增的資源:服務帳戶、自訂專案角色、群組、群組成員資格及群組角色指派。再次執行 terraform plan,確認這份設定不會產生其他變更。
在 Terraform 之外建立服務帳戶的 API 金鑰:
PROJECT_ID="$(terraform output -raw project_id)"
SERVICE_ACCOUNT_ID="$(terraform output -raw service_account_id)"
umask 077
curl -X POST \
"https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID/api_keys" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production App",
"scopes": ["api.responses.write"]
}' \
--output service-account-api-key.json
將傳回的 API 金鑰值存入已核准的機密管理工具,再刪除 service-account-api-key.json。請勿將金鑰儲存在 Terraform 設定、狀態或輸出中。