EKM (Externe Schlüssel) in der Management-API

Hier erfährst du, wie du mit der Management-API externe Schlüssel für EKM verwaltest.

Aktualisiert: 15 hours ago

Zusammenfassung

Zugang

  • EKM-Endpunkte sind in der Management-API über einen Admin-API-Schlüssel zugänglich. https://platform.openai.com/settings/organization/admin-keys (Keinen normalen API-Schlüssel verwenden.) Admin-API-Schlüssel stehen Eigentümer:innen der Organisation zur Verfügung.

  • Verwende api.external_keys.write, um externe Schlüssel zu erstellen oder zu löschen, und api.external_keys.read, um externe Schlüssel aufzulisten, abzurufen oder zu validieren. Ein einzelner Schlüssel benötigt beide Berechtigungen nur dann, wenn er sowohl Lese- als auch Schreibvorgänge ausführen muss.

Nutzung

Beschränkungen

  • Du musst EKM zuerst in einem neuen Projekt über die Management-API testen.

  • Wir empfehlen, für deine EKM-Workloads neue Projekte anzulegen. Beachte die folgenden Empfehlungen, bevor du EKM in bestehenden Produktionsprojekten einführst.

    • Teste zunächst alle API-Funktionen, die du in der Produktionsumgebung nutzt, in deinem EKM-API-Testprojekt.

    • Führe EKM schrittweise ein, statt es gleichzeitig für alle produktiven API-Projekte zu konfigurieren.

Endpunkte auf Organisationsebene

Einen externen Schlüssel in deiner Organisation registrieren

AWS

Beispielanfrage:

  • type: string – immer "aws"

  • name: string – Ein benutzerfreundlicher Name für deine Konfiguration

  • role_arn: string – Die Rollen-ARN, die OpenAI in deiner Cloud übernehmen wird

  • kms_arn: string – Die ARN des Schlüsselverwaltungssystems für den von dir verwalteten Hauptschlüssel

  • external_id: string – Deine Organisations-ID oder API-Projekt-ID

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}'

Beispielantwort:

{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}

GCP

Beispielanfrage:

  • type: string – immer "gcp",

  • name: string – Ein benutzerfreundlicher Name für deine Konfiguration

  • workload_identity_project_number: string – Die numerische GCP-Projektnummer des Projekts, in dem du die Workload-Identität von OpenAI registriert hast

  • workload_identity_pool_id: string – Der Pool, der den Workload-Identitätsanbieter enthält, den du für OpenAI registriert hast

  • workload_identity_provider_id: string – Der Workload-Identitätsanbieter, den du für OpenAI registriert hast

  • audience: string – Die Zielgruppe, die OpenAI im Token übergeben soll, wenn wir über deinen GCP STS eine Rolle übernehmen

  • kms_project_id: string – Der Name des GCP-Projekts, in dem sich dein KMS befindet

  • kms_key_ring_name: string – Der Schlüsselbund des Schlüsselverwaltungssystems, der den von dir verwalteten Hauptschlüssel enthält

  • kms_key_name: string – Der Name des Hauptschlüssels des Schlüsselverwaltungssystems

  • kms_key_location: string – Die Region, in der sich dein Hauptschlüssel des Schlüsselverwaltungssystems befindet

Wenn sich dein KMS in einem anderen GCP-Projekt befindet als dem, in dem du die Workload-Identität von OpenAI registriert hast, stelle sicher, dass KMS zumindest auch im Projekt mit der Workload-Identität aktiviert ist. Rufe dazu https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview auf.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "gcp",
"name": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role",
"audience": "<your org id or project id>",
"kms_project_id": "adjective-noun-12345",
"kms_key_name": "openai-kms-key",
"kms_key_ring_name": "openai-kms-key-ring",
"kms_key_location": "us-east1"
}'

Beispielantwort:

{
"id": "extkey_xxxxxx",
"object": "organization.external_key",
"created_at": 1746174349,
"api_project_ids": [],
"type": "gcp",
"name": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"kms_key_ring_name": "openai-kms-key-ring",
"kms_key_name": "openai-kms-key",
"kms_key_location": "us-east1",
"audience": "<your org id or project id>",
"kms_project_id": "adjective-noun-12345",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role"
}

Azure

Beispielanfrage:

  • type: string – immer "azure",

  • name: string – Ein benutzerfreundlicher Name für deine Konfiguration

  • tenant_id: string – Deine Azure-Tenant-UUID

  • vault_uri: string – Die URI des Azure-Tresors, der den von dir verwalteten Hauptschlüssel enthält

  • key_name: string – Der Name des Azure Key Vault-Masterschlüssels, den du verwaltest.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "azure",
"name": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}'

Beispielantwort:

{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746174377,
"api_project_ids": [],
"type": "azure",
"name": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}

OCI

Richte einen aktivierten AES-256-Schlüssel ein und gewähre OpenAI Zugriff. Füge dem Schlüssel den Freiform-Tag openai_organization_id hinzu und gib deine OpenAI-Organisations-ID als Wert an. Die Anleitung findest du unter „OCI Vault für Enterprise Key Management konfigurieren“.

Beispielanfrage:

  • type: string – immer "oci"

  • purpose: string – ohne Angabe gilt der Standardwert "ekm"

  • name: string – Ein benutzerfreundlicher Name für deine Konfiguration

  • region: string – die OCI-Region, in der sich dein Vault und dein Schlüssel befinden

  • vault_ocid: string – die vollständige OCID deines Vaults

  • key_ocid: string – die vollständige OCID deines AES-256-Schlüssels

Gib für EKM keine key_version_ocid an.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'

Beispielantwort:

{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}

Bei Erfolg gibt die API HTTP 200 zurück. Speichere den zurückgegebenen id-Wert und verwende ihn als external_key_id, wenn du ein Projekt erstellst. Auch OCI-Registrierungen kannst du mit den bestehenden Operationen auflisten, abrufen, validieren und löschen.

Verwende für die PSP-Wiederherstellung eine separate RSA-3072-Registrierung mit purpose: "psp_decryption" und dem exakten Wert für key_version_ocid. Setze psp_decryption_key_id auf die Registrierungs-ID bei OpenAI. Für diesen RSA-Schlüssel braucht OpenAI nur Lesezugriff auf Metadaten und öffentliche Schlüssel. Die vollständige Anleitung findest du unter Asymmetrische Schlüssel einrichten – OCI Vault.

Einen externen Schlüssel löschen, der in deiner Organisation registriert ist

Hinweis: Du kannst eine Registrierung erst löschen, wenn sie von keinem aktiven Projekt und keinem Workspace mehr verwendet wird. Archiviere bei EKM zuerst die zugehörigen API-Projekte. Eine EKM-Registrierung, die mit einem Workspace verknüpft ist, bleibt vor dem Löschen geschützt. Ersetze oder entferne für die PSP-Wiederherstellung den Wert von psp_decryption_key_id in jedem aktiven Projekt, das auf die Registrierung verweist. Danach kannst du die Registrierung löschen. Wenn du eine OpenAI-Registrierung löschst, bleibt der Cloud-Schlüssel erhalten.

Beispielanfrage

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Beispielantwort

{
"id": "extkey_xxxxx",
"object": "organization.external_key.deleted",
"created_at": 1746127808,
"api_project_ids": [],
"type": "aws",
"account_number": "123456789012",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}

Rufe die externen Schlüssel ab, die für deine Organisation registriert sind.

Ohne „purpose“-Filter enthält die Liste sowohl Registrierungen für EKM als auch Registrierungen für die PSP-Wiederherstellung. Verwende ?purpose=ekm oder ?purpose=psp_decryption, um nach Zweck zu filtern.

Beispielanfrage

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Beispielantwort

{
"object": "list",
"data": [
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746127808,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"account_number": "123456789012",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}
],
"first_id": "extkey_xxxx",
"has_more": false,
"last_id": "extkey_xxxx"
}

Einen externen Schlüssel validieren

Prüfe mit der Validierung, ob OpenAI weiterhin auf deinen Cloud-Schlüssel zugreifen kann.

  • Bei EKM prüft OpenAI, ob sich mit dem Schlüssel Daten ver- und entschlüsseln lassen. Informationen zum Widerruf und zur Zwischenspeicherung findest du im Leitfaden zum Lebenszyklus von Schlüsseln.

  • Für die PSP-Wiederherstellung ruft OpenAI den öffentlichen Schlüssel der registrierten Version ab und vergleicht ihn mit der gespeicherten Kopie. Eine erfolgreiche Validierung bestätigt nicht, dass deine Wiederherstellungsidentität Daten entschlüsseln kann. Wenn die Validierung fehlschlägt, bleibt die gespeicherte Kopie des öffentlichen Schlüssels erhalten.

Wenn du eine Registrierung mit GET abrufst, erhältst du die gespeicherte Konfiguration. Die API prüft dabei den Zugriff auf deinen Cloud-Schlüssel nicht erneut.

Beispielanfrage

curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Beispielantwort

{
"status": "success"
}

Oder es ist ein Fehler seitens deines Cloud-Anbieters aufgetreten.

Endpunkte auf Projektebene

Ein neues Projekt mit einer externen Schlüssel-ID erstellen

Dies funktioniert wie der bestehende Endpunkt zum Erstellen von Projekten, jedoch mit dem zusätzlichen Parameter external_key_id in der Anfrage und der Antwort.

Beispielanfrage

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
"name": "Some Project",
"external_key_id": "extkey_xxxx"
}'

Beispielantwort

{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}

Eine externe Schlüssel-ID in einem bestehenden Projekt aktualisieren

Dies funktioniert wie der bestehende Endpunkt zum Aktualisieren von Projekten, jedoch mit dem zusätzlichen Parameter external_key_id in der Anfrage und Antwort.

Wir empfehlen, für deine EKM-Workloads neue API-Projekte anzulegen. Beachte die folgenden Empfehlungen, bevor du EKM in bestehenden Produktionsprojekten einführst.

  • Teste zunächst alle API-Funktionen, die du in der Produktionsumgebung nutzt, in deinem EKM-API-Testprojekt.

  • Führe EKM schrittweise ein, statt es gleichzeitig für alle produktiven API-Projekte zu konfigurieren.

Beispielanfrage

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects/proj_xxx" \
-d '{
"external_key_id": "extkey_xxxx"
}'

Alle Projekte in deiner Organisation auflisten

Dies ist derselbe Endpunkt wie bisher, allerdings enthält die API-Antwort zusätzlich external_key_id.

Beispielanfrage

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Beispielantwort

{
"object": "list",
"data": [
{
"object": "organization.project",
"id": "proj_xxxx",
"name": "Project Name",
"external_key_id": "extkey_xxxx",
"created_at": 1717798982,
"archived_at": null,
"status": "active"
}
],
"first_id": "proj_xxxx",
"last_id": "proj_xxxx",
"has_more": true
}

War dieser Artikel hilfreich?