Ta strona została przetłumaczona maszynowo. Wyświetl oryginalny artykuł w języku angielskim.

EKM (klucze zewnętrzne) w Management API

Dowiedz się, jak zarządzać kluczami zewnętrznymi EKM za pomocą API zarządzania.

Zaktualizowano: yesterday

Podsumowanie

Dostęp

  • Punkty końcowe EKM są dostępne w API zarządzania za pomocą klucza API administratora. https://platform.openai.com/settings/organization/admin-keys (nie używaj zwykłego klucza API). Klucze API administratora są dostępne dla właścicieli organizacji.

  • Użyj api.external_keys.write, aby tworzyć lub usuwać klucze zewnętrzne, oraz api.external_keys.read, aby wyświetlać ich listę, pobierać je lub weryfikować. Pojedynczy klucz potrzebuje obu zakresów uprawnień tylko wtedy, gdy musi wykonywać zarówno operacje odczytu, jak i zapisu.

Korzystanie

Ograniczenia

  • Najpierw musisz przetestować EKM w nowym projekcie za pomocą API zarządzania.

  • Zalecamy tworzenie nowych projektów na potrzeby zadań korzystających z EKM. Przed wdrożeniem EKM w istniejących projektach produkcyjnych zapoznaj się z poniższymi dobrymi praktykami.

    • Najpierw przetestuj wszystkie funkcje API używane w środowisku produkcyjnym w testowym projekcie API z EKM.

    • Wdrażaj EKM stopniowo, zamiast włączać je we wszystkich produkcyjnych projektach API naraz.

Endpoints na poziomie organizacji

Zarejestruj klucz zewnętrzny w organizacji

AWS

Przykładowe żądanie:

  • type: ciąg znaków – zawsze „aws”

  • name: ciąg znaków – czytelna nazwa konfiguracji

  • role_arn: ciąg znaków – ARN roli, którą OpenAI będzie przyjmować w Twojej chmurze

  • kms_arn: ciąg znaków – ARN zarządzanego przez Ciebie klucza głównego w systemie zarządzania kluczami

  • external_id: ciąg znaków – ID Twojej organizacji lub projektu API

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>"
}'

Przykładowa odpowiedź:

{
"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

Przykładowe żądanie:

  • type: ciąg znaków – zawsze „gcp”,

  • name: ciąg znaków – czytelna nazwa konfiguracji

  • workload_identity_project_number: ciąg znaków – numeryczny identyfikator projektu GCP, w którym zarejestrowano tożsamość obciążenia OpenAI

  • workload_identity_pool_id: ciąg znaków – pula zawierająca dostawcę Workload Identity zarejestrowanego dla OpenAI

  • workload_identity_provider_id: ciąg znaków – dostawca Workload Identity zarejestrowany dla OpenAI

  • audience: ciąg znaków – odbiorca, którego OpenAI ma wskazać w tokenie podczas przyjmowania roli za pośrednictwem Twojej usługi GCP STS

  • kms_project_id: ciąg znaków – nazwa projektu GCP, w którym znajduje się Twój KMS

  • kms_key_ring_name: ciąg znaków – pierścień kluczy w systemie zarządzania kluczami zawierający zarządzany przez Ciebie klucz główny

  • kms_key_name: ciąg znaków – nazwa klucza głównego w systemie zarządzania kluczami

  • kms_key_location: ciąg znaków – region, w którym znajduje się klucz główny Twojego systemu zarządzania kluczami

Jeśli Twój KMS znajduje się w innym projekcie GCP niż ten, w którym zarejestrowano Workload Identity OpenAI, upewnij się, że w projekcie z Workload Identity OpenAI jest przynajmniej włączony KMS. Możesz to sprawdzić pod adresem https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview.

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"
}'

Przykładowa odpowiedź:

{
"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

Przykładowe żądanie:

  • type: ciąg znaków – zawsze „azure”,

  • name: ciąg znaków – czytelna nazwa konfiguracji

  • tenant_id: ciąg znaków – UUID Twojej dzierżawy Azure

  • vault_uri: ciąg znaków – URI magazynu Azure zawierającego zarządzany przez Ciebie klucz główny

  • key_name: ciąg znaków – nazwa zarządzanego przez Ciebie klucza głównego w Azure Key Vault.

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"
}'

Przykładowa odpowiedź:

{
"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

Skonfiguruj aktywny klucz AES-256 i przyznaj OpenAI dostęp do niego. Klucz musi mieć tag swobodny openai_organization_id o wartości odpowiadającej ID organizacji w OpenAI. Instrukcje konfiguracji znajdziesz w artykule: Konfigurowanie OCI Vault na potrzeby zarządzania kluczami przedsiębiorstwa.

Przykładowe żądanie:

  • type: ciąg znaków — zawsze "oci"

  • purpose: ciąg znaków — "ekm"; wartość domyślna, gdy parametr zostanie pominięty

  • name: ciąg znaków — czytelna nazwa konfiguracji

  • region: ciąg znaków — region OCI, w którym znajdują się Twój magazyn kluczy i klucz

  • vault_ocid: ciąg znaków — pełny identyfikator OCID Twojego magazynu kluczy

  • key_ocid: ciąg znaków — pełny identyfikator OCID Twojego klucza AES-256

Nie przekazuj key_version_ocid w przypadku EKM.

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>"
}'

Przykładowa odpowiedź:

{
"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>"
}

API zwraca kod HTTP 200, gdy operacja się powiedzie. Zapisz zwróconą wartość id i użyj jej jako external_key_id podczas tworzenia projektu. Istniejące operacje wyświetlania listy, pobierania, weryfikacji i usuwania mają zastosowanie również do rejestracji OCI.

Na potrzeby odzyskiwania PSP użyj osobnej rejestracji RSA-3072 z purpose: "psp_decryption" i dokładną wartością key_version_ocid. Ustaw psp_decryption_key_id na identyfikator tej rejestracji w OpenAI. OpenAI potrzebuje jedynie dostępu do odczytu metadanych i kluczy publicznych tego klucza RSA. Pełne instrukcje konfiguracji znajdziesz w artykule: Konfigurowanie kluczy asymetrycznych — OCI Vault.

Usuń klucz zewnętrzny zarejestrowany w Twojej organizacji

Uwaga: Usuwanie jest zablokowane, dopóki z rejestracji korzysta aktywny projekt lub przestrzeń robocza. W przypadku EKM najpierw zarchiwizuj powiązane projekty API; rejestracja EKM powiązana z przestrzenią roboczą pozostaje chroniona przed usunięciem. W przypadku odzyskiwania PSP przed usunięciem rejestracji zastąp lub wyczyść psp_decryption_key_id w każdym aktywnym projekcie, który się do niej odwołuje. Usunięcie rejestracji w OpenAI nie usuwa klucza w chmurze.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
"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>"
}

Pobierz klucze zewnętrzne zarejestrowane w Twojej organizacji

Bez filtra przeznaczenia lista obejmuje zarówno rejestracje EKM, jak i rejestracje na potrzeby odzyskiwania PSP. Użyj ?purpose=ekm lub ?purpose=psp_decryption, aby filtrować według przeznaczenia.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
"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"
}

Zweryfikuj klucz zewnętrzny

Użyj weryfikacji, aby sprawdzić, czy OpenAI nadal ma dostęp do Twojego klucza w chmurze.

  • W przypadku EKM OpenAI sprawdza, czy może szyfrować i odszyfrowywać dane za pomocą klucza. Informacje o unieważnianiu kluczy i działaniu pamięci podręcznej znajdziesz we wskazówkach dotyczących cyklu życia klucza.

  • W przypadku odzyskiwania PSP OpenAI pobiera klucz publiczny zarejestrowanej wersji i porównuje go z zapisaną kopią. Pomyślna weryfikacja nie potwierdza, że tożsamość używana do odzyskiwania może odszyfrowywać dane. Nieudana weryfikacja nie usuwa ani nie zastępuje zapisanej kopii klucza publicznego.

Pobranie rejestracji metodą GET zwraca zapisaną konfigurację i nie sprawdza ponownie dostępu do Twojego klucza w chmurze.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
"status": "success"
}

Albo błąd zgłoszony przez dostawcę chmury.

Endpoints na poziomie projektu

Utwórz nowy projekt z ID klucza zewnętrznego

Działa tak samo jak istniejący punkt końcowy tworzenia projektu, ale żądanie i odpowiedź zawierają dodatkowo parametr external_key_id.

Przykładowe żądanie

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"
}'

Przykładowa odpowiedź

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

Zaktualizuj istniejący projekt, podając identyfikator klucza zewnętrznego

To ten sam punkt końcowy co istniejący punkt końcowy aktualizacji projektu, ale z dodatkowym parametrem external_key_id w żądaniu i odpowiedzi.

Zalecamy tworzenie nowych projektów API na potrzeby zadań korzystających z EKM. Przed wdrożeniem EKM w istniejących projektach produkcyjnych zapoznaj się z poniższymi dobrymi praktykami.

  • Najpierw przetestuj wszystkie funkcje API używane w środowisku produkcyjnym w testowym projekcie API z EKM.

  • Wdrażaj EKM stopniowo, zamiast włączać je we wszystkich produkcyjnych projektach API naraz.

Przykładowe żądanie

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"
}'

Wyświetl listę wszystkich projektów w Twojej organizacji

Działa tak samo jak istniejący punkt końcowy, ale odpowiedź API zawiera dodatkowo pole external_key_id.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
"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
}

Czy ten artykuł był pomocny?