In dieser Anleitung erstellst du ein OpenAI-Projekt und richtest wiederverwendbare Zugriffsregeln ein. Mit einer Projektrolle legst du fest, welche Aktionen Identitäten ausführen dürfen. Du fasst die Identitäten in einer Organisationsgruppe zusammen und weist der Gruppe die Rolle im Projekt zu.
Am Ende hast du eine wiederverwendbare Konfiguration, die folgende Aufgaben übernimmt:
- Sie erstellt ein OpenAI-Projekt für eine Anwendung.
- Sie definiert eine Projektrolle, die nur die erforderlichen Berechtigungen gewährt.
- Sie erstellt eine Organisationsgruppe für Identitäten, die Zugriff benötigen.
- Sie gewährt der Gruppe über die Rolle Zugriff auf das Projekt.
- Sie fügt der Gruppe ein bestehendes Benutzerkonto der Organisation hinzu.
Bevor du beginnst
Schließe das Setup des Terraform-Providers ab und exportiere einen Admin-API-Schlüssel als OPENAI_ADMIN_KEY. Du benötigst außerdem die ID eines bestehenden Benutzerkontos der Organisation und die Kennungen der für die Anwendung genehmigten Berechtigungen. Verwende eine Testorganisation, um den Ablauf zu erproben.
Wenn du eine Ressource vom Typ openai_project mit Terraform entfernst, wird das Projekt archiviert, statt dauerhaft gelöscht zu werden. Ein archiviertes Projekt kannst du nicht wiederherstellen.
Ein eigenes Projekt für die Anwendung erstellen
Erstelle ein Projekt für die Anwendung:
resource "openai_project" "application" {
name = "example-application-development"
}
Das Projekt legt fest, auf welcher Ebene du die API-Nutzung, Dienstkonten, Ratenlimits, Kostenwarnungen und Projekteinstellungen der Anwendung verwaltest. Terraform stellt die generierte ID als openai_project.application.project_id bereit. Ressourcen auf Projektebene können auf diesen Wert verweisen. Terraform erstellt das Projekt deshalb vor den Ressourcen, die darauf verweisen.
Dieses Beispiel verwendet einen festen Projektnamen. Im vollständigen Beispiel weiter unten ersetzt du ihn durch eine Variable, damit du die Konfiguration in mehreren Umgebungen verwenden kannst.
Projektberechtigungen definieren
Erstelle eine Projektrolle mit den für die Anwendung genehmigten Berechtigungen:
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"]
}
Die Ressource openai_project_role legt fest, welche Aktionen eine Identität im Projekt ausführen darf. In diesem Beispiel gewährt die Rolle Lesezugriff auf die Webhook-Konfiguration. Ersetze api.webhooks.read durch die Kennungen der für deine Anwendung genehmigten Berechtigungen. Vergib zunächst nur die Berechtigungen, die deine Anwendung benötigt.
Wenn du permissions änderst, wird die Rolle aktualisiert. Führe terraform plan aus und prüfe jede Berechtigung, die hinzukommt oder entfällt, bevor du die Änderung anwendest.
Eine Gruppe erstellen oder eine bestehende Gruppe verwenden
Erstelle eine Organisationsgruppe, wenn Terraform ihren Lebenszyklus verwalten soll:
resource "openai_group" "application_access" {
name = "example-application-development-access"
}
Gruppen gehören zur Organisation. Du kannst dieselbe Gruppe in mehreren Projekten verwenden. Die Endung -access im Gruppennamen macht deutlich, dass die Mitgliedschaft Zugriff gewährt und der Name mehr als nur eine Teamzugehörigkeit ausdrückt.
Wenn ein anderes System eine bestehende Gruppe verwaltet, lies sie über eine Datenquelle ein:
data "openai_group" "application_access" {
group_id = "group_123"
}
Die Datenquelle liest die Gruppe ein, ohne dass diese Konfiguration ihren Lebenszyklus verwaltet. Auch über SCIM verwaltete Gruppen kannst du einlesen. Ändere ihre Mitgliedschaften weiterhin im zuständigen Identitätsverwaltungssystem.
Der Gruppe Zugriff auf das Projekt gewähren
Weise der Gruppe die benutzerdefinierte Rolle im Projekt zu:
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
}
Dieses Beispiel verwendet die von Terraform verwaltete Gruppe. Wenn du eine bestehende Gruppe über die Datenquelle eingelesen hast, ersetze den Ausdruck für group_id durch data.openai_group.application_access.group_id.
Die Zuweisung verknüpft drei Objekte:
project_idgibt an, auf welches Projekt die Gruppe Zugriff erhält.group_idgibt an, welche Gruppe von Identitäten Zugriff erhält.role_idgibt an, welche Berechtigungen die Gruppe erhält.
Die Gruppenmitglieder erben die benutzerdefinierte Rolle in diesem Projekt. Eine Rolle oder Gruppe allein gewährt noch keinen Zugriff. Dazu musst du der Gruppe die Rolle zuweisen.
Benutzerkonten und andere Identitäten hinzufügen
Füge einer von Terraform verwalteten Organisationsgruppe mit openai_group_user eine Identität hinzu:
resource "openai_group_user" "application_developer" {
group_id = openai_group.application_access.group_id
user_id = "user_123"
}
Die user_id kann ein bestehendes Benutzerkonto der Organisation oder ein Dienstkonto bezeichnen. Um ein Dienstkonto hinzuzufügen, verwende openai_project_service_account.application.id als user_id. Die Anleitung zu Dienstkonten beschreibt den gruppenbasierten Zugriff für Dienstkonten, die Authentifizierung und die Anforderungen an die Verwaltung von Zugangsdaten während ihres gesamten Lebenszyklus.
Wenn sich gruppenbasierter Zugriff für deinen Anwendungsfall nicht eignet, weise die Rolle direkt zu:
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
}
Für organisationsweite Berechtigungen erstellst du eine Organisationsrolle und weist sie direkt oder über eine Gruppe zu:
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
}
Gib in organization_role_permissions die Kennungen der genehmigten Berechtigungen auf Organisationsebene an. Trenne Organisationsberechtigungen von Projektberechtigungen, damit jede Zuweisung nur so weit reicht wie erforderlich.
Aktuelle Rollenzuweisungen prüfen
Lies die Organisations- und Projektrollen aus, die einer Identität zugewiesen sind, bevor du deren Zugriffsrechte änderst:
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
}
Datenquellen zeigen die aktuellen Zuweisungen an, ohne dass Terraform deren Verwaltung übernimmt.
Zuweisungen entfernen
Wenn Terraform eine Zuweisung bereits verwaltet und du ihren Ressourcenblock entfernst, schlägt Terraform im nächsten Plan vor, die Zuweisung im Zielsystem zu löschen. Prüfe den Plan und vergewissere dich, dass alle weiterhin erforderlichen Zugriffsrechte über andere Zuweisungen erhalten bleiben.
Bei einer bereits vorhandenen Zuweisung deklarierst du zuerst die passende Ressource und importierst die Zuweisung mit der dokumentierten zusammengesetzten ID. Vergewissere dich, dass der erste Plan keine Änderungen vorsieht. Erst dann entfernst du die Ressource aus der Konfiguration und führst die Löschung aus.
Terraform kann nur Zuweisungen entfernen, die im Terraform-State erfasst sind. Um eine bestehende Standardzuweisung zu entfernen, importiere sie zuerst in die entsprechende Terraform-Ressource. Entferne anschließend die Ressource aus deiner Konfiguration und wende den daraus resultierenden Löschplan an. Wenn deine Organisation dieses Vorgehen nicht erlaubt, entferne die Zuweisung über ein dafür zugelassenes Dashboard oder mithilfe eines genehmigten Verfahrens über die Administration API.
Die Anleitung Import und Abgleich beschreibt die Importformate und zeigt, in welcher Reihenfolge du bestehende Ressourcen sicher in die Verwaltung durch Terraform übernimmst.
Das vollständige Beispiel ausführen
Die einzelnen Beispiele verwenden konkrete Werte, um die Beziehungen zwischen den Ressourcen zu verdeutlichen. Die vollständige Konfiguration ersetzt wiederkehrende, umgebungsspezifische Werte durch Variablen. So kannst du sie wiederverwenden, ohne die Ressourcendefinitionen zu ändern.
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_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
}
Erstelle die Datei terraform.tfvars und gib darin einen eindeutigen Projektnamen, die ID eines bestehenden Benutzerkontos der Organisation und die genehmigten Berechtigungen an:
project_name = "example-application-development"
user_id = "user_123"
project_role_permissions = [
"api.webhooks.read",
]
Initialisiere Terraform, speichere den Plan, prüfe ihn und wende ihn an:
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan
Der erste Plan sollte fünf neue Ressourcen vorsehen. Nachdem du den Plan angewendet hast, erbt das Benutzerkonto die benutzerdefinierte Projektrolle über die Gruppe. Mit terraform output gibst du die IDs des Projekts, der Gruppe und der Projektrolle aus. Führe terraform plan erneut aus und prüfe, ob die Konfiguration keine weiteren Änderungen vorsieht.
Um weitere Personen hinzuzufügen, lege für jedes Benutzerkonto wie im Beispiel eine Gruppenmitgliedschaft mit einem eindeutigen Terraform-Ressourcennamen an. Wie du eine nichtmenschliche Identität konfigurierst, erfährst du in der Anleitung zu Dienstkonten. Weitere Schutzmaßnahmen für dein Projekt findest du in den Anleitungen Zugriff auf Modelle, Tools und Daten steuern und Ratenlimits und Ausgaben.