Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Dienstkonten mit Terraform verwalten

Erstelle technische Identitäten mit minimalen Berechtigungen und stelle ihre API-Schlüssel außerhalb von Terraform aus.

Ein OpenAI-Dienstkonto ist eine technische Identität, die einem Projekt gehört. Mit Terraform kannst du das Konto ohne Standardrolle erstellen, nur die erforderlichen Berechtigungen in einer Rolle bündeln und diese über eine Gruppe zuweisen. Erstelle und verwalte die API-Schlüssel des Dienstkontos außerhalb von Terraform über die Administration API.

So richtest du ein Dienstkonto typischerweise ein:

  1. Erstelle ein Dienstkonto ohne Standardprojektrolle und ohne API-Schlüssel.
  2. Weise dem Konto über eine Gruppe eine benutzerdefinierte Projektrolle zu, die nur die für den Workload erforderlichen Berechtigungen gewährt.
  3. Erstelle einen API-Schlüssel mit eingeschränktem Geltungsbereich und speichere ihn in deinem Secrets-Manager.

Voraussetzungen

Schließe das Setup für den Terraform-Provider ab. Exportiere einen Admin-API-Schlüssel als OPENAI_ADMIN_KEY und die ID des bestehenden Projekts als PROJECT_ID.

Verwende eine Testorganisation, wenn du das Erstellen, Importieren, Ersetzen und Löschen von Dienstkonten ausprobierst.

Dienstkonto ohne Standardrolle erstellen

Erstelle das Dienstkonto mit 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
}

Ersetze proj_123 durch die ID des bestehenden Projekts, dem das Dienstkonto gehören soll.

Der Provider erstellt die Identität des Dienstkontos, ohne einen API-Schlüssel zu generieren oder eine Standardprojektrolle zuzuweisen. Terraform speichert die ID des Dienstkontos und weitere nicht vertrauliche Metadaten im State. Zu diesem Zeitpunkt hat das Dienstkonto keine Projektberechtigungen.

Nur die erforderlichen Berechtigungen zuweisen

Definiere eine benutzerdefinierte Projektrolle, die nur die für den Workload erforderlichen Berechtigungen umfasst. Erstelle eine Gruppe, füge das Dienstkonto hinzu und weise der Gruppe die Rolle zu. In diesem Beispiel dürfen Gruppenmitglieder Antworten erstellen:

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
}

Die Ressource openai_project_role legt die erforderlichen Berechtigungen fest. Mit openai_group_user fügst du das Dienstkonto zur Gruppe hinzu und mit openai_project_group_role weist du der Gruppe die Rolle zu. Jedes Dienstkonto, das du zur Gruppe hinzufügst, erbt dieselbe Projektrolle. Ersetze api.responses.write durch die kleinstmögliche Auswahl der für deinen Workload genehmigten Berechtigungen. Mehr über den gruppenbasierten Projektzugriff erfährst du im Leitfaden Projekte und Zugriff.

Prüfe die Konfiguration und wende sie an:

terraform plan
terraform apply

Weise keine der integrierten Rollen member oder owner zu, wenn eine benutzerdefinierte Projektrolle die Berechtigungen gewährt, die dein Workload benötigt. Beschränke den Zugriff auf die genehmigten Berechtigungen.

API-Schlüssel mit eingeschränktem Geltungsbereich erstellen

Nachdem du die Terraform-Konfiguration angewendet hast, erstelle über den Endpunkt API-Schlüssel für ein Projektdienstkonto erstellen einen API-Schlüssel. Die API gibt den vollständigen Schlüsselwert nur einmal zurück. Schütze deshalb die Antwortdatei, bevor du die Anfrage sendest:

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

Wähle die Scopes so, dass sie nur die vom Workload benötigten Zugriffsrechte abdecken. Die Scopes des API-Schlüssels können die Berechtigungen des Dienstkontos weiter einschränken. Sie können keine Berechtigungen gewähren, die über die zugewiesene Projektrolle hinausgehen.

Übergib den Inhalt des Feldes value aus service-account-api-key.json an den für deinen Secrets-Manager freigegebenen Workflow, ohne den Wert auszugeben. Sobald dein Secrets-Manager das Secret gespeichert und überprüft hat, lösche die Antwortdatei:

rm service-account-api-key.json

Behandle service-account-api-key.json als Secret, solange die Datei existiert. Nimm die Datei in keinen Commit auf. Schreibe den Schlüssel nicht in die Terraform-Konfiguration, gib ihn nicht über eine Terraform-Ausgabe aus und übergib ihn nicht als Terraform-Variable.

Die API-Referenz beschreibt die Struktur der Antwort und enthält Beispiele für verschiedene Programmiersprachen. Workloads, die Identitätsföderation für Workloads unterstützen, können dasselbe Dienstkonto und dieselbe Rolle mit minimalen Berechtigungen nutzen, ohne einen API-Schlüssel zu erstellen.

Bestehendes Dienstkonto importieren

Ein Dienstkonto, das Terraform erstellt hat, musst du nicht importieren. Um ein außerhalb von Terraform erstelltes Dienstkonto zu übernehmen, deklariere es mit derselben Projekt-ID und demselben Namen:

resource "openai_project_service_account" "application" {
  project_id = "proj_123"
  name       = "example-application-development-service-account"
}

Importiere die bestehende Identität, bevor du die Konfiguration wie gewohnt anwendest:

SERVICE_ACCOUNT_ID="<existing-service-account-id>"

terraform import \
  openai_project_service_account.application \
  "$PROJECT_ID/$SERVICE_ACCOUNT_ID"

terraform plan

Der erste Plan nach dem Import sollte keine Änderungen am Dienstkonto vorsehen. Falls der Plan vorsieht, das Konto zu ersetzen, passe den Namen und das Projekt in der Konfiguration an das bestehende Konto an, bevor du die Konfiguration anwendest.

Beim Import stellt Terraform keinen API-Schlüssel wieder her und speichert auch keinen. Die bestehende Projektrolle des Dienstkontos bleibt erhalten. Die Gruppenmitgliedschaft wird nicht mitimportiert. Deklariere und importiere die bestehenden Ressourcen openai_project_role, openai_group, openai_group_user und openai_project_group_role, wenn Terraform sie verwalten soll. Der Workload liest vorhandene Secrets weiterhin aus deinem Secrets-Manager.

Importiere das Dienstkonto, bevor du die Ressourcendeklaration anwendest. Wendest du die Deklaration zuerst an, erstellt Terraform ein anderes Dienstkonto, statt die bestehende Identität zu übernehmen.

Zugangsdaten wiederherstellen oder rotieren

Die API gibt den vollständigen Schlüsselwert nur beim Erstellen des API-Schlüssels zurück. Wenn du den API-Schlüssel später für das Projekt abrufst, erhältst du nur einen maskierten Wert. Einen verlorenen Schlüssel kannst du deshalb nicht wiederherstellen.

So ersetzt du einen verlorenen Schlüssel oder rotierst deine Zugangsdaten, ohne den Workload zu unterbrechen:

  1. Deklariere das Ersatzkonto als neue Ressource vom Typ openai_project_service_account. Verwende einen anderen Terraform-Ressourcennamen als für das alte Konto.
  2. Wende die Konfiguration an, um das Ersatzkonto zu erstellen.
  3. Füge das Ersatzkonto mit openai_group_user zur bestehenden Gruppe hinzu, damit es die Projektrolle mit den minimalen Berechtigungen erbt.
  4. Erstelle über die Administration API einen API-Schlüssel für das Ersatzkonto und speichere ihn über den für deinen Secrets-Manager freigegebenen Workflow.
  5. Stelle den neuen Schlüssel bereit und prüfe, ob der Workload mit dem Ersatzkonto funktioniert.
  6. Entferne die alte Ressource openai_project_service_account und die zugehörige Ressource openai_group_user aus der Terraform-Konfiguration. Behalte die Rolle, die Gruppe und die Rollenzuweisung für die Gruppe bei, da das Ersatzkonto alle drei weiterhin nutzt.
  7. Prüfe den Plan, der das Löschen des alten Dienstkontos und seiner Gruppenmitgliedschaft vorsieht, und wende ihn an. Führe anschließend terraform plan aus und stelle sicher, dass der Plan keine Änderungen mehr vorsieht.

Wenn du eine Ressource vom Typ openai_project_service_account löschst, löschst du damit auch das Dienstkonto bei OpenAI. Verlange für diese Änderung eine ausdrückliche Prüfung, insbesondere wenn der alte Schlüssel noch für laufende Anfragen verwendet wird.

Weitere Informationen dazu, wie Terraform Ressourcen in den State übernimmt und wie sich das Entfernen auswirkt, findest du im Leitfaden Import und Abgleich.

Vollständiges Beispiel ausführen

Die bisherigen Beispiele zeigen anhand konkreter Werte, wie du ein Dienstkonto erstellst, ihm eine Rolle zuweist und einen API-Schlüssel erstellst. Die vollständige Konfiguration verwendet Variablen für projektspezifische Werte und Berechtigungen. So kannst du sie in mehreren Umgebungen wiederverwenden.

Speichere die folgende Konfiguration als 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
}

Erstelle terraform.tfvars mit einer bestehenden Projekt-ID, einem eindeutigen Namen für das Dienstkonto und der kleinstmöglichen Auswahl genehmigter Projektberechtigungen:

project_id           = "proj_123"
service_account_name = "example-application-development-service-account"

project_role_permissions = [
  "api.responses.write",
]

Initialisiere Terraform, prüfe anschließend den gespeicherten Plan und wende ihn an:

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

Der erste Plan sollte das Hinzufügen von fünf Ressourcen vorsehen: das Dienstkonto, seine benutzerdefinierte Projektrolle, die Gruppe, die Gruppenmitgliedschaft und die Rollenzuweisung für die Gruppe. Führe terraform plan erneut aus und vergewissere dich, dass die Konfiguration keine weiteren Änderungen vorsieht.

Erstelle den API-Schlüssel für das Dienstkonto außerhalb von Terraform:

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

Übertrage den zurückgegebenen Schlüsselwert in deinen freigegebenen Secrets-Manager und lösche anschließend service-account-api-key.json. Speichere den Schlüssel weder in der Terraform-Konfiguration noch im State oder in Terraform-Ausgaben.