OpenAI
Ez az oldal gépi fordítással készült. Tekintsd meg az eredeti angol nyelvű cikket.

EKM (External Keys) a Management API-ban

Ismerd meg, hogyan kezelheted az EKM külső kulcsait a felügyeleti API-val.

Frissítve: 49 minutes ago

Összefoglaló

Hozzáférés

  • Az EKM-végpontok a Management API-n keresztül, adminisztrátori API-kulccsal érhetők el. https://platform.openai.com/settings/organization/admin-keys (ne használj normál API-kulcsot). Az adminisztrátori API-kulcsok a szervezet tulajdonosai számára érhetők el.

  • Külső kulcsok létrehozásához vagy törléséhez használd az api.external_keys.write, listázásukhoz, lekérésükhöz vagy ellenőrzésükhöz pedig az api.external_keys.read jogosultsági hatókört. Egy kulcsnak csak akkor van szüksége mindkét hatókörre, ha olvasási és írási műveleteket is kell végeznie.

Használat

Korlátozások

  • Az EKM-et először egy új projektben kell tesztelned a Management API-n keresztül.

  • Javasoljuk, hogy az EKM-et igénylő feladatokhoz hozz létre új projekteket. Mielőtt bevezetnéd az EKM-et a meglévő éles projektjeidben, vedd figyelembe az alábbi bevált gyakorlatokat.

    • Először az EKM-tesztelésre szolgáló API-projektedben teszteld az éles környezetben használt összes API-funkciót.

    • Fokozatosan vezesd be az EKM-et, ne egyszerre állítsd be az összes éles API-projektben.

Szervezetszintű endpoints

Külső kulcs regisztrálása a szervezetében

AWS

Példakérés:

  • type: karakterlánc – mindig „aws”

  • name: karakterlánc – A konfiguráció könnyen felismerhető neve

  • role_arn: karakterlánc – Annak a szerepkörnek az ARN-je, amelyet az OpenAI a felhőkörnyezetedben felvesz

  • kms_arn: karakterlánc – Az általad kezelt főkulcs ARN-je a kulcskezelő rendszerben

  • external_id: karakterlánc – A szervezetazonosítód vagy az API-projekted azonosítója

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

Példaválasz:

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

Példakérés:

  • type: karakterlánc – mindig „gcp”,

  • name: karakterlánc – A konfiguráció könnyen felismerhető neve

  • workload_identity_project_number: karakterlánc – Annak a GCP-projektnek a numerikus projektszáma, amelyben regisztráltad az OpenAI munkaterhelés-identitását

  • workload_identity_pool_id: karakterlánc – Az OpenAI számára regisztrált Workload Identity-szolgáltatót tartalmazó készlet

  • workload_identity_provider_id: karakterlánc – Az OpenAI számára regisztrált Workload Identity-szolgáltató

  • audience: karakterlánc – Az a célközönség, amelyet az OpenAI-nak a tokenben kell megadnia, amikor a GCP STS-szolgáltatásodon keresztül veszünk fel egy szerepkört

  • kms_project_id: karakterlánc – Annak a GCP-projektnek a neve, amelyben a KMS-ed található

  • kms_key_ring_name: karakterlánc – A kulcskezelő rendszer azon kulcskarikája, amely az általad kezelt főkulcsot tartalmazza

  • kms_key_name: karakterlánc – A kulcskezelő rendszer főkulcsának neve

  • kms_key_location: karakterlánc – Az a régió, amelyben a kulcskezelő rendszer főkulcsa található

Ha a KMS-ed másik GCP-projektben található, mint amelyben az OpenAI Workload Identity-identitását regisztráltad, győződj meg róla, hogy az OpenAI Workload Identity-identitását tartalmazó projektben legalább a KMS engedélyezve van. Ezt itt ellenőrizheted: 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"
}'

Példaválasz:

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

Példakérés:

  • type: karakterlánc – mindig „azure”,

  • name: karakterlánc – A konfiguráció könnyen felismerhető neve

  • tenant_id: karakterlánc – Az Azure-bérlőd UUID-azonosítója

  • vault_uri: karakterlánc – Az általad kezelt főkulcsot tartalmazó Azure-kulcstartó URI-ja

  • key_name: karakterlánc – Az Azure Key Vaultban általad kezelt főkulcs neve.

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

Példaválasz:

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

Állíts be egy engedélyezett AES-256-kulcsot, és adj hozzáférést az OpenAI számára. A kulcshoz egy szabad formátumú openai_organization_id címkét kell rendelni, amelynek értéke az OpenAI-szervezetazonosítód. A beállítás lépéseit itt találod: Az OCI Vault konfigurálása vállalati kulcskezeléshez.

Példakérés:

  • type: karakterlánc – mindig "oci"

  • purpose: karakterlánc – "ekm"; ha nincs megadva, ez az alapértelmezett érték

  • name: karakterlánc – A konfiguráció könnyen azonosítható neve

  • region: karakterlánc – A tárolót és a kulcsot tartalmazó OCI-régió

  • vault_ocid: karakterlánc – A tároló teljes OCID-je

  • key_ocid: karakterlánc – Az AES-256-kulcs teljes OCID-je

EKM esetén ne add meg a key_version_ocid paramétert.

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

Példaválasz:

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

Siker esetén az API HTTP 200-as állapotkódot ad vissza. Mentsd el a visszakapott id értéket, és projekt létrehozásakor ezt add meg az external_key_id értékeként. A meglévő listázási, lekérési, ellenőrzési és törlési műveletek az OCI-regisztrációkra is alkalmazhatók.

PSP-helyreállításhoz használj külön RSA-3072-regisztrációt purpose: "psp_decryption" beállítással és egy pontos key_version_ocid értékkel. A psp_decryption_key_id értékét állítsd ennek OpenAI-regisztrációs azonosítójára. Az OpenAI számára elegendő olvasási hozzáférést biztosítani az adott RSA-kulcs metaadataihoz és nyilvános kulcsaihoz. A teljes beállítási útmutatót itt találod: Aszimmetrikus kulcsok beállítása – OCI Vault.

A szervezetednél regisztrált külső kulcs törlése

Megjegyzés: A törlés nem engedélyezett, amíg egy aktív projekt vagy munkaterület használja a regisztrációt. EKM esetén először archiváld a kapcsolódó API-projekteket; a munkaterülethez kapcsolódó EKM-regisztráció továbbra is védett marad. PSP-helyreállítás esetén a regisztráció törlése előtt módosítsd vagy töröld a psp_decryption_key_id értékét minden olyan aktív projektben, amely a regisztrációra hivatkozik. Az OpenAI-regisztráció törlése nem törli a felhőben tárolt kulcsot.

Példakérés

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

Példaválasz

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

A szervezetednél regisztrált külső kulcsok lekérése

Felhasználási cél szerinti szűrés nélkül a lista az EKM- és a PSP-helyreállítási regisztrációkat is tartalmazza. Használd a ?purpose=ekm vagy a ?purpose=psp_decryption paramétert a felhasználási cél szerinti szűréshez.

Példakérés

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

Példaválasz

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

Külső kulcs ellenőrzése

Az ellenőrzéssel meggyőződhetsz arról, hogy az OpenAI továbbra is hozzáfér-e a felhőben tárolt kulcsodhoz.

  • EKM esetén az OpenAI ellenőrzi, hogy képes-e titkosítani és visszafejteni a kulccsal. A visszavonás és a gyorsítótárazás működését a kulcsok életciklusáról szóló útmutató ismerteti.

  • PSP-helyreállítás esetén az OpenAI lekéri a regisztrált verzió nyilvános kulcsát, és összehasonlítja a tárolt pillanatképpel. A sikeres ellenőrzés nem igazolja, hogy a helyreállításhoz használt identitásod képes a visszafejtésre. A sikertelen ellenőrzés nem távolítja el és nem cseréli le a nyilvános kulcs tárolt pillanatképét.

A regisztráció GET-tel történő lekérése a tárolt konfigurációt adja vissza, és nem ellenőrzi újra a felhőben tárolt kulcsodhoz való hozzáférést.

Példakérés

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

Példaválasz

{
"status": "success"
}

Vagy a felhőszolgáltató által jelzett hiba.

Projektszintű endpoints

Új projekt létrehozása külső kulcsazonosítóval

Ez megegyezik a meglévő projektlétrehozási végponttal, de a kérés és a válasz kiegészül az external_key_id paraméterrel.

Példakérés

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

Példaválasz

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

Meglévő projekt frissítése külső kulcsazonosítóval

Ez megegyezik a meglévő projektfrissítési végponttal, de a kérés és a válasz kiegészül az external_key_id paraméterrel.

Javasoljuk, hogy az EKM-et igénylő feladatokhoz hozz létre új API-projekteket. Mielőtt bevezetnéd az EKM-et a meglévő éles projektjeidben, vedd figyelembe az alábbi bevált gyakorlatokat.

  • Először az EKM-tesztelésre szolgáló API-projektedben teszteld az éles környezetben használt összes API-funkciót.

  • Fokozatosan vezesd be az EKM-et, ne egyszerre állítsd be az összes éles API-projektben.

Példakérés

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

A szervezet összes projektjének listázása

Ez megegyezik a meglévő végponttal, de az API-válasz kiegészül az external_key_id mezővel.

Példakérés

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

Példaválasz

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

Hasznos volt ez a cikk?