Aquesta pàgina s'ha traduït automàticament. Mostra l'article original en anglès.

EKM (claus externes) a la Management API

Aprèn a gestionar les claus externes d'EKM amb l'API de gestió.

Actualització: 15 hours ago

Resum

Accés

  • Els punts finals d'EKM són accessibles a l'API de gestió mitjançant una clau d'API d'administració. https://platform.openai.com/settings/organization/admin-keys (no facis servir una clau d'API normal). Les claus d'API d'administració estan disponibles per als propietaris de l'organització.

  • Fes servir api.external_keys.write per crear o suprimir claus externes, i api.external_keys.read per llistar, obtenir o validar claus externes. Una mateixa clau només necessita tots dos àmbits de permisos si ha de fer operacions tant de lectura com d'escriptura.

Ús

Restriccions

  • Primer has de provar EKM en un projecte nou mitjançant l'API de gestió.

  • Recomanem crear projectes nous per a les càrregues de treball d'EKM. Tingues en compte les bones pràctiques següents abans d'implementar EKM als teus projectes de producció existents.

    • Prova primer totes les funcions de l'API que fas servir en producció al teu projecte d'API de prova amb EKM.

    • Implementa EKM gradualment en lloc d'activar-lo a tots els projectes d'API de producció alhora.

endpoints de nivell d’organització

Registrar una clau externa a la vostra organització

AWS

Exemple de sol·licitud:

  • type: cadena - sempre "aws"

  • name: cadena - Un nom descriptiu per a la teva configuració

  • role_arn: cadena - L'ARN del rol que OpenAI assumirà al teu núvol

  • kms_arn: cadena - L'ARN del sistema de gestió de claus corresponent a la clau mestra que gestiones

  • external_id: cadena - El teu ID d'organització o de projecte d'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>"
}'

Exemple de resposta:

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

Exemple de sol·licitud:

  • type: cadena - sempre "gcp",

  • name: cadena - Un nom descriptiu per a la teva configuració

  • workload_identity_project_number: cadena - El número del projecte de GCP on has registrat la identitat de càrrega de treball d'OpenAI

  • workload_identity_pool_id: cadena - El grup que conté el proveïdor de Workload Identity que has registrat per a OpenAI

  • workload_identity_provider_id: cadena - El proveïdor de Workload Identity que has registrat per a OpenAI

  • audience: cadena - L'audiència que OpenAI ha de passar al testimoni quan assumim un rol mitjançant el teu STS de GCP

  • kms_project_id: cadena - El nom del projecte de GCP on es troba el teu KMS

  • kms_key_ring_name: cadena - L'anell de claus del sistema de gestió de claus que conté la clau mestra que gestiones

  • kms_key_name: cadena - El nom de la clau mestra del sistema de gestió de claus

  • kms_key_location: cadena - La regió on es troba la clau mestra del teu sistema de gestió de claus

Si el teu KMS es troba en un projecte de GCP diferent d'aquell on has registrat la identitat de Workload Identity d'OpenAI, assegura't que el projecte que conté aquesta identitat tingui, com a mínim, KMS habilitat. Pots comprovar-ho a 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"
}'

Exemple de resposta:

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

Exemple de sol·licitud:

  • type: cadena - sempre "azure",

  • name: cadena - Un nom descriptiu per a la teva configuració

  • tenant_id: cadena - L'UUID del teu inquilí d'Azure

  • vault_uri: cadena - L'URI del magatzem d'Azure que conté la clau mestra que gestiones

  • key_name: cadena - El nom de la clau mestra d'Azure Key Vault que gestiones.

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

Exemple de resposta:

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

Configura una clau AES-256 habilitada i concedeix-hi accés a OpenAI. La clau ha de tenir una etiqueta de format lliure openai_organization_id amb el teu ID d'organització d'OpenAI com a valor. Per veure els passos de configuració, consulta: Configuració d'OCI Vault per a la gestió de claus empresarials.

Exemple de sol·licitud:

  • type: cadena - sempre "oci"

  • purpose: cadena - "ekm"; el valor predeterminat si s'omet

  • name: cadena - Un nom descriptiu per a la configuració

  • region: cadena - La regió d'OCI que conté el magatzem de claus i la clau

  • vault_ocid: cadena - L'OCID complet del magatzem de claus

  • key_ocid: cadena - L'OCID complet de la clau AES-256

No passis key_version_ocid per a 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>"
}'

Exemple de resposta:

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

L'API retorna HTTP 200 si l'operació es completa correctament. Desa el valor id retornat i fes-lo servir com a external_key_id en crear un projecte. Les operacions existents per llistar, obtenir, validar i suprimir també s'apliquen als registres d'OCI.

Per a la recuperació de PSP, fes servir un registre RSA-3072 independent amb purpose: "psp_decryption" i un valor exacte de key_version_ocid. Estableix psp_decryption_key_id amb el seu ID de registre d'OpenAI. OpenAI només necessita accés de lectura a les metadades i a les claus públiques d'aquesta clau RSA. Per veure la configuració completa, consulta: Configuració de claus asimètriques — OCI Vault.

Suprimeix una clau externa registrada a la teva organització

Nota: La supressió es bloqueja mentre un projecte o espai de treball actiu utilitzi el registre. Per a EKM, arxiva primer els projectes d'API associats; un registre d'EKM associat a un espai de treball continua protegit. Per a la recuperació de PSP, substitueix o esborra el valor de psp_decryption_key_id a tots els projectes actius que facin referència al registre abans de suprimir-lo. Suprimir un registre d'OpenAI no suprimeix la clau al núvol.

Exemple de sol·licitud

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

Exemple de resposta

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

Obtén les claus externes registrades a la teva organització

Sense un filtre de finalitat, la llista inclou tant els registres d'EKM com els de recuperació de PSP. Fes servir ?purpose=ekm o ?purpose=psp_decryption per filtrar per finalitat.

Exemple de sol·licitud

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

Exemple de resposta

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

Valida una clau externa

Fes servir la validació per comprovar que OpenAI encara pot accedir a la teva clau al núvol.

  • Per a EKM, OpenAI comprova que pot xifrar i desxifrar amb la clau. Per saber com funcionen la revocació i la memòria cau, consulta: guia del cicle de vida de les claus.

  • Per a la recuperació de PSP, OpenAI obté la clau pública de la versió registrada i la compara amb la instantània emmagatzemada. Una validació correcta no confirma que la teva identitat de recuperació pugui desxifrar. Una validació fallida no suprimeix ni substitueix la instantània emmagatzemada de la clau pública.

Obtenir un registre amb GET retorna la configuració emmagatzemada i no torna a comprovar l'accés a la teva clau al núvol.

Exemple de sol·licitud

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

Exemple de resposta

{
"status": "success"
}

O bé un error retornat pel proveïdor de núvol.

endpoints de nivell de projecte

Crea un projecte nou amb un ID de clau externa

És el mateix punt final que ja existeix per crear projectes, però amb el paràmetre external_key_id afegit a la sol·licitud i a la resposta.

Exemple de sol·licitud

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

Exemple de resposta

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

Actualitza un projecte existent amb un ID de clau externa

És el mateix punt final d'actualització de projectes existent, amb el paràmetre external_key_id afegit a la sol·licitud i a la resposta.

Recomanem crear projectes d'API nous per a les càrregues de treball d'EKM. Tingues en compte les bones pràctiques següents abans d'implementar EKM als teus projectes de producció existents.

  • Prova primer totes les funcions de l'API que fas servir en producció al teu projecte d'API de prova amb EKM.

  • Implementa EKM gradualment en lloc d'activar-lo a tots els projectes d'API de producció alhora.

Exemple de sol·licitud

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

Llista tots els projectes de la teva organització

És el mateix punt final que ja existeix, però amb external_key_id afegit a la resposta de l'API.

Exemple de sol·licitud

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

Exemple de resposta

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

T'ha estat útil aquest article?