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.
Einen in der Cloud verwalteten öffentlichen Schlüssel bei OpenAI registrieren
Registriere ein asymmetrisches RSA-3072-Schlüsselpaar deines Cloud-Anbieters für die Verwendung mit OpenAI.
Dein privater Schlüssel bleibt in AWS KMS, Azure Key Vault, Google Cloud KMS oder Oracle Cloud Infrastructure (OCI) Vault. Bei der Registrierung speichert OpenAI eine Kopie des zugehörigen öffentlichen Schlüssels.
Mit der Registrierung eines Schlüssels konfigurierst du weder Produktfunktionen noch Speicher. In dieser Anleitung geht es um Schlüssel für die PSP-Entschlüsselung.
Voraussetzungen
Halte deine Organisations-ID bereit. Verwende dieselbe Organisation für die Vertrauensbeziehung mit deinem Cloud-Anbieter, die Registrierung und den API-Zugriff.
Erstelle einen Admin-API-Schlüssel für deine Organisation mit Lese- und Schreibzugriff auf externe Schlüssel. Lade ihn sicher in die Umgebungsvariable OPENAI_ADMIN_KEY. Projektschlüssel für die Inferenz funktionieren hierfür nicht.
Du brauchst die Berechtigung, einen aktivierten RSA-3072-Schlüssel zu erstellen und OpenAI den in dieser Anleitung beschriebenen Lesezugriff auf den öffentlichen Schlüssel zu gewähren.
Beschränke die Nutzung privater Schlüssel auf autorisierte Personen. Bewahre alte Schlüsselversionen auf, solange Datensätze von ihnen abhängen.
Cloud-Schlüssel einrichten
Führe vor der Registrierung die Schritte für deinen Cloud-Anbieter aus. Bei allen Anbietern verwendest du RSA-3072 und gewährst OpenAI ausschließlich Lesezugriff auf den öffentlichen Schlüssel und seine Metadaten.
1. RSA-Schlüssel erstellen
Öffne KMS > Kundenverwaltete Schlüssel > Schlüssel erstellen und wähle deine Region aus. Verwende folgende Einstellungen:
Schlüsseltyp: Asymmetrisch
Schlüsselverwendung: Verschlüsseln und entschlüsseln
Schlüsselspezifikation:RSA_3072
Lege fest, wer den Schlüssel bei dir verwaltet, und schließe die Erstellung ab. Lass den Schlüssel aktiviert und kopiere seinen vollständigen ARN. Er endet auf key/<CUSTOMER_KMS_KEY_ID>. Verwende keinen Alias-ARN.
2. Richtlinie für den Lesezugriff auf den öffentlichen Schlüssel erstellen
Öffne IAM > Richtlinien > Richtlinie erstellen > JSON. Ersetze <CUSTOMER_KMS_KEY_ARN> und speichere die Richtlinie als OpenAI-PublicKeyRead.
Der Schlüssel unterstützt die Entschlüsselung, aber OpenAI benötigt nur diese Leseberechtigungen. Erteile OpenAI keine Berechtigungen zur Nutzung oder Verwaltung des Schlüssels.
3. IAM-Rolle mit Vertrauensrichtlinie erstellen
Öffne IAM > Rollen > Rolle erstellen > Benutzerdefinierte Vertrauensrichtlinie. Ersetze <OPENAI_ORG_ID> durch deine OpenAI-Organisations-ID. Lass den OpenAI-Prinzipal unverändert.
Füge die Richtlinie OpenAI-PublicKeyRead hinzu und erstelle die Rolle. Kopiere den ARN der Rolle. Gib bei der Registrierung des Schlüssels dieselbe Organisations-ID als external_id an.
4. KMS-Schlüsselrichtlinie prüfen
Prüfe, ob die Schlüsselrichtlinie der Rolle den Zugriff erlaubt. Falls die Richtlinie die Autorisierung nicht an IAM delegiert, füge die folgende Anweisung hinzu. Ersetze <CUSTOMER_ROLE_ARN> und behalte die bestehenden Verwaltungsberechtigungen bei.
In dieser KMS-Schlüsselrichtlinie gilt "Resource": "*" nur für den Schlüssel, dem die Richtlinie zugeordnet ist. Die IAM-Richtlinie verwendet den genauen ARN des Schlüssels.
Halte den Rollen-ARN und den Schlüssel-ARN für die Registrierung bereit.
1. OpenAI-Unternehmensanwendung hinzufügen
Bitte eine Person mit Verwaltungsrechten für deinen Mandanten, die Anwendung EKM - OpenAI Azure zu deinem Mandanten hinzuzufügen. Ihre Anwendungs-ID lautet 20a14814-5ab7-4612-a671-1382b412bf93.
Installiere die Azure CLI, melde dich an und prüfe, ob die Anwendung vorhanden ist:
123az login --tenant '<CUSTOMER_TENANT_ID>'az ad sp show --id '20a14814-5ab7-4612-a671-1382b412bf93' \ --query '{name:displayName,objectId:id}' -o table
Falls die Anwendung fehlt, füge sie hinzu:
az ad sp create --id '20a14814-5ab7-4612-a671-1382b412bf93' \ --query '{name:displayName,objectId:id}' -o table
Speichere die Objekt-ID der Anwendung in deinem Mandanten für die Rollenzuweisung.
2. Schlüssel erstellen
Öffne Schlüsseltresore > Erstellen. Wähle dein Abonnement, deine Ressourcengruppe, den Namen des Tresors und die Region aus. Wähle unter Zugriffskonfiguration die Option Rollenbasierte Zugriffssteuerung in Azure.
Wer den Tresor verwaltet, benötigt für diesen Tresor eine Rolle, die das Erstellen von Schlüsseln erlaubt, etwa Key Vault Crypto Officer. Weise OpenAI diese Rolle nicht zu.
Öffne im Tresor Objekte > Schlüssel > Generieren/Importieren und verwende folgende Einstellungen:
Name:<OPENAI_ORG_ID>--asymmetric-key mit deiner OpenAI-Organisations-ID
Schlüsseltyp: RSA
RSA-Schlüsselgröße: 3072
Aktiviert: Ja
Wenn du ein Aktivierungs- oder Ablaufdatum festlegst, stelle sicher, dass der Schlüssel aktuell gültig ist. Nimm Entschlüsseln in die Liste der zulässigen Schlüsseloperationen auf. OpenAI erhält ausschließlich Lesezugriff auf den Schlüssel.
RSA-HSM-Schlüssel in einem Schlüsseltresor werden ebenfalls unterstützt. Eigenständige Managed HSM-Endpunkte werden nicht unterstützt.
3. Lesezugriff auf den Schlüssel gewähren
Erstelle eine benutzerdefinierte Rolle mit der DataAction zum Lesen von Schlüsseln. Speichere die folgende Rollendefinition als public-key-reader.json und ersetze die Werte für das Abonnement und die Ressourcengruppe.
123456789101112{ "Name": "OpenAI Public Key Reader", "IsCustom": true, "Description": "Read key metadata and public keys.", "Actions": [], "NotActions": [], "DataActions": ["Microsoft.KeyVault/vaults/keys/read"], "NotDataActions": [], "AssignableScopes": [ "/subscriptions/<CUSTOMER_SUBSCRIPTION_ID>/resourceGroups/<CUSTOMER_RESOURCE_GROUP>" ]}
Setze VAULT_RESOURCE_ID auf die Azure-Ressourcen-ID des Tresors. Du findest sie unter Eigenschaften. Verwende hierfür nicht den HTTPS-URI des Tresors. Setze OPENAI_SP_ID auf die Objekt-ID der Anwendung in deinem Mandanten und weise die Rolle für diesen Schlüssel zu:
123456789101112az role definition create --role-definition @public-key-reader.jsonOPENAI_SP_ID='<CUSTOMER_OPENAI_SP_OBJECT_ID>'VAULT_RESOURCE_ID='<CUSTOMER_VAULT_RESOURCE_ID>'KEY_NAME='<OPENAI_ORG_ID>--asymmetric-key'KEY_SCOPE="$VAULT_RESOURCE_ID/keys/$KEY_NAME"az role assignment create \ --assignee-object-id "$OPENAI_SP_ID" \ --assignee-principal-type ServicePrincipal \ --role 'OpenAI Public Key Reader' \ --scope "$KEY_SCOPE"
Verwendet der Tresor ältere Zugriffsrichtlinien, erteile stattdessen die Schlüsselberechtigung Get. Behalte das bestehende Berechtigungsmodell des Tresors bei.
4. Genaue Schlüsselversion notieren
Notiere die Mandanten-ID, den Tresor-URI und den Schlüsselnamen. Öffne die aktivierte Schlüsselversion und kopiere die 32-stellige hexadezimale Versionskennung am Ende des Felds Schlüsselbezeichner.
1. Projekt und Schlüssel vorbereiten
Aktiviere Cloud KMS im Projekt des Schlüssels. Aktiviere IAM und den Security Token Service im Projekt für die Föderation. Falls es sich um zwei verschiedene Projekte handelt, aktiviere Cloud KMS in beiden.
Notiere die zwölfstellige Projektnummer des Föderationsprojekts. Das KMS-Projekt kann ein anderes sein.
Öffne Sicherheit > Schlüsselverwaltung. Erstelle einen Schlüsselbund und darin einen Schlüssel mit folgenden Einstellungen:
Schutzstufe: Software
Zweck: Asymmetrische Entschlüsselung
Algorithmus: RSA mit 3072 Bit, OAEP-Padding und SHA-256-Digest
Kopiere die KMS-Projekt-ID, den Standort, den Namen des Schlüsselbunds, den Schlüsselnamen und die aktivierte Version. Gib eine konkrete Version wie "1" an. Verwende weder "latest" noch "0". Asymmetrische Schlüssel haben keine primäre Version.
2. Workload Identity Federation konfigurieren
Öffne IAM und Verwaltung > Workload Identity Federation. Erstelle einen globalen Pool, zum Beispiel openai-keys, und einen OIDC-Anbieter, zum Beispiel openai-google, mit folgenden Einstellungen:
Anbietereinstellung
Wert
Aussteller-URL
https://accounts.google.com
Zulässige Zielgruppe
Deine exakte OpenAI-Organisations-ID
Attributzuordnung
google.subject = assertion.sub
Attributbedingung
assertion.sub == '105900137572174660365'
Verwende deine OpenAI-Organisations-ID als Zielgruppe. Lass den Aussteller und den Subject-Wert für OpenAI unverändert.
3. Rolle für den Lesezugriff erstellen und zuweisen
Erstelle im KMS-Projekt unter IAM und Verwaltung > Rollen eine benutzerdefinierte Rolle mit folgenden Berechtigungen:
Beide Berechtigungen sind erforderlich. Die Rolle public-key-viewer allein reicht nicht aus. Berechtigungen zum Entschlüsseln, zum Signieren oder zum Annehmen der Identität eines Dienstkontos sind nicht erforderlich.
Öffne beim Schlüssel den Tab Berechtigungen und wähle Zugriff gewähren. Weise die Rolle dem folgenden Prinzipal zu und ersetze dabei <CUSTOMER_GCP_PROJECT_NUMBER> und <CUSTOMER_GCP_POOL_ID>:
Verwende die Projektnummer des Pools und beschränke die Rollenzuweisung auf diesen Schlüssel. IAM-Berechtigungen auf Schlüsselebene gelten auch für die Versionen des Schlüssels. Halte die IDs von Pool und Anbieter, die Organisations-ID für die Zielgruppe und die KMS-Kennungen für die Registrierung bereit.
1. Vault und RSA-Schlüssel erstellen
Kläre mit deiner Ansprechperson bei OpenAI, ob du OCI-Schlüssel registrieren kannst und ob die gewünschte Region verfügbar ist. Sowohl dein Mandant als auch der Mandant von OpenAI müssen die Region abonniert haben.
Öffne in der OCI-Konsole Vault. Erstelle einen Vault in einer kommerziellen OCI-Region wie us-ashburn-1 oder wähle dort einen vorhandenen Vault aus. Warte, bis der Vault den Status Aktiv hat.
Öffne Masterverschlüsselungsschlüssel und wähle Schlüssel erstellen. Verwende RSA mit einer Schlüssellänge von 3072 Bit und softwarebasiertem Schutz. Lass den Schlüssel aktiviert. Wenn du auch EKM konfigurierst, verwende dafür einen separaten AES-256-Schlüssel.
2. Schlüssel mit der Organisations-ID kennzeichnen
Füge dem Schlüssel das folgende Freiform-Tag hinzu:
Tag-Feld
Wert
Tag-Namespace
Keiner (Freiform-Tag)
Tag-Schlüssel
openai_organization_id
Tag-Wert
Deine OpenAI-Organisations-ID einschließlich des Präfixes org-
Das Tag muss am Schlüssel selbst gesetzt sein, auch wenn du den Vault oder das Compartment ebenfalls mit einem Tag versiehst.
3. Lesezugriff auf den öffentlichen Schlüssel gewähren
Wähle unter Identität und Sicherheit > Richtlinien das Root-Compartment deines Mandanten aus und erstelle eine Richtlinie. Aktiviere Manuellen Editor anzeigen und gib die folgenden Anweisungen mit deiner Vault-OCID und deiner Schlüssel-OCID ein. Lass die Mandanten- und Gruppenkennungen von OpenAI unverändert.
Define tenancy OpenAIEKM as ocid1.tenancy.oc1..aaaaaaaa4kzwe5jdr4gsxft7dfnwbnp3aozhxeskabsqo7czdkbp6fkh3uhaDefine group OpenAIEKMProduction as ocid1.group.oc1..aaaaaaaaerxukyeaxwqtbsxasnp54mem3sfgyokzdk7s27o7yvepluynxi5qAdmit group OpenAIEKMProduction of tenancy OpenAIEKM to {VAULT_READ} in tenancy where target.vault.id = '<CUSTOMER_VAULT_OCID>'Admit group OpenAIEKMProduction of tenancy OpenAIEKM to {KEY_READ} in tenancy where target.key.id = '<CUSTOMER_KEY_OCID>'
Mit VAULT_READ kann OpenAI die Endpunkte des Vaults ermitteln. Mit KEY_READ kann OpenAI die Schlüsselmetadaten und den öffentlichen Schlüssel der ausgewählten Version lesen. Diese Berechtigungen erlauben weder das Entschlüsseln noch den Export oder die Verwaltung von Schlüsseln. Verwende diese Identität für die Schlüsselverwaltung auch dann, wenn du für PSP bereits eine separate Richtlinie für OCI Object Storage eingerichtet hast.
4. Genaue Schlüsselversion notieren
Notiere die Regionskennung, die Vault-OCID und die Schlüssel-OCID. Kopiere aus der Versionsliste des Schlüssels die vollständige OCID der Version, die du registrieren möchtest. Die Versions-OCID beginnt mit ocid1.keyversion.. Das Präfix ocid1.key. kennzeichnet den Schlüssel selbst.
Gib die genaue Versions-OCID an. Verwende weder latest noch eine Versionsnummer. Vault, Schlüssel und Version müssen zur selben kommerziellen Region gehören. Der Schlüssel muss zum registrierten Vault gehören.
Schlüssel registrieren
Die Beispiele verwenden curl und eine Bash-kompatible Shell. Lade OPENAI_ADMIN_KEY sicher und lege dann deine Organisations-ID fest:
123456API_BASE="https://api.openai.com/v1"ORG_ID="<OPENAI_ORG_ID>": "${OPENAI_ADMIN_KEY:?Load your organization admin key securely}"KEYS_URL="$API_BASE/organization/external_keys"
Registrierungsanfrage vorbereiten
Für purpose sind die Werte ekm (Standard) und psp_decryption zulässig. Verwende psp_decryption für die asymmetrischen Schlüssel in dieser Anleitung. Der Wert ekm ist für Enterprise Key Management (EKM) vorgesehen.
Speichere die Anfrage für deinen Anbieter als registration.json. Ersetze die Beispielwerte, da JSON keine Shellvariablen auflöst.
Bei der Registrierung prüft die API den Schlüssel, bevor sie ihn speichert. Bei Erfolg erhältst du HTTP 200 mit einer extkey-ID und deiner Anbieterkonfiguration. Die Antwort enthält beispielsweise folgende Felder:
GET gibt die gespeicherten Angaben zurück. POST /validate prüft erneut, ob der Zugriff weiterhin möglich ist und ob der aktuelle Schlüssel gültig ist und mit dem gespeicherten öffentlichen Schlüssel übereinstimmt. Dabei entschlüsselt die API keine Datensätze und aktualisiert auch nicht die gespeicherte Momentaufnahme.
Validiere den Schlüssel nach Änderungen am Schlüssel, an den Berechtigungen oder am Netzwerk erneut. Warte nach IAM-Änderungen, bis sie wirksam sind, bevor du es erneut versuchst.
Verwende purpose=psp_decryption, um die Registrierungen dieser asymmetrischen Schlüssel aufzulisten. Ohne Filter erhältst du Registrierungen für alle Verwendungszwecke. Mit purpose=ekm erhältst du nur EKM-Registrierungen.
Solange has_more den Wert true hat, ruf die nächste Seite ab, indem du after auf den Wert von last_id setzt. Lass purpose, order und limit unverändert.
Schlüssel ersetzen
Erstelle in AWS einen Ersatzschlüssel oder in Azure, Google Cloud oder OCI eine neue Schlüsselversion und gewähre Lesezugriff darauf.
Registriere den Ersatzschlüssel bzw. die neue Version.
Jede Registrierung hält den Stand zum Zeitpunkt der Registrierung fest. Eine Schlüsselrotation in der Cloud aktualisiert die Registrierung nicht. Bewahre alte private Schlüssel auf, solange Datensätze von ihnen abhängen. Wenn du die Schlüsselauswahl änderst, werden bestehende Datensätze nicht migriert.
Nach dem Löschen der Registrierung erhältst du HTTP 200 mit object: "organization.external_key.deleted". Dein Schlüssel in der Cloud bleibt erhalten.
Fehlerbehebung
Fehler
Was du prüfen solltest
401 oder 403
Verwende einen Admin-API-Schlüssel deiner Organisation und prüfe, ob er zur Registrierung externer Schlüssel berechtigt.
400 external_key_provider_error
Prüfe die Vertrauensbeziehung mit deinem Cloud-Anbieter, die Leseberechtigungen und den Netzwerkzugriff. Prüfe außerdem, ob der Schlüssel aktiviert ist und den richtigen Algorithmus verwendet.
400 bei der Validierung der Anfrage
Prüfe den Verwendungszweck und je nach Anbieter den ARN des konkreten AWS-Schlüssels oder die genaue Schlüsselversion in Azure, Google Cloud oder OCI.
Validierung des OCI-Schlüssels schlägt fehl
Prüfe das Tag openai_organization_id am Schlüssel. Stelle sicher, dass der RSA-Schlüssel 3072 Bit lang und aktiviert ist, zum registrierten Vault gehört und OpenAI die auf diesen Vault und diesen Schlüssel beschränkten Leseberechtigungen hat.
404
Prüfe die Registrierungs-ID und die Organisation. Gelöschte Registrierungen und Registrierungen einer anderen Organisation kannst du nicht verwenden.
external_key_used_by_active_projects
Hebe die Schlüsselauswahl in allen aktiven Projekten auf oder wähle dort einen anderen Schlüssel aus.
Schlüssel stimmt nicht mehr überein
Registriere den Ersatzschlüssel und wähle seine neue ID aus.
Wenn du dich an den Support wendest, gib die Fehlermeldung und die x-request-id an. Gib niemals Zugangsdaten weiter.