EKM (Chiavi esterne) nell'API di gestione

Scopri come gestire le chiavi esterne per EKM utilizzando l'API di gestione.

Aggiornato: 3 days ago

Riepilogo

Accesso

  • Gli endpoint EKM sono accessibili nell'API di gestione tramite una chiave API di amministrazione. https://platform.openai.com/settings/organization/admin-keys (non utilizzare una normale chiave API). Le chiavi API di amministrazione sono disponibili per i proprietari dell'organizzazione.

  • Usa api.external_keys.write per creare o eliminare chiavi esterne e api.external_keys.read per elencare, recuperare o convalidare chiavi esterne. Una singola chiave richiede entrambi gli ambiti solo se deve eseguire operazioni sia di lettura sia di scrittura.

Utilizzo

Restrizioni

  • Devi prima testare EKM su un nuovo progetto tramite l'API di gestione.

  • Consigliamo di creare nuovi progetti per i carichi di lavoro EKM. Prima di implementare EKM nei tuoi progetti di produzione esistenti, tieni presenti le seguenti procedure consigliate.

    • Testa prima nel tuo progetto di prova dell'API EKM tutte le funzionalità dell'API che utilizzi in produzione.

    • Applica un'implementazione graduale, anziché inserire i dati EKM in tutti i progetti API di produzione contemporaneamente.

Endpoint a livello di organizzazione

Registra una chiave esterna per la tua organizzazione

AWS

Richiesta di esempio:

  • type: string - always “aws”

  • name: string - Un nome descrittivo per la tua configurazione

  • role_arn: string - L'ARN del ruolo che OpenAI assumerà nel tuo cloud

  • kms_arn: string - L'ARN del sistema di gestione delle chiavi per la chiave principale che gestisci

  • external_id: string - Il tuo ID organizzazione o ID progetto 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>"
}'

Risposta di esempio:

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

Richiesta di esempio:

  • type: string - always "gcp",

  • name: string - Un nome descrittivo per la tua configurazione

  • workload_identity_project_number: string - Il numero di progetto GCP in formato numerico in cui hai registrato l'identità del carico di lavoro di OpenAI

  • workload_identity_pool_id: string - Il pool contenente il provider di identità del carico di lavoro che hai registrato per OpenAI

  • workload_identity_provider_id: string - Il provider di identità del carico di lavoro che hai registrato per OpenAI

  • audience: string - Il pubblico che OpenAI deve includere nel token quando assumiamo un ruolo tramite il tuo GCP STS

  • kms_project_id: string - Il nome del progetto GCP in cui si trova il tuo KMS

  • kms_key_ring_name: string - Il keyring del sistema di gestione delle chiavi che contiene la chiave principale che gestisci

  • kms_key_name: string - Il nome della chiave principale del sistema di gestione delle chiavi

  • kms_key_location: string - L'area geografica in cui si trova la chiave principale del tuo sistema di gestione delle chiavi

Se il tuo KMS si trova in un progetto GCP diverso da quello in cui hai registrato l'identità del carico di lavoro di OpenAI, assicurati che il progetto contenente l'identità del carico di lavoro di OpenAI abbia almeno un KMS abilitato andando 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"
}'

Risposta di esempio:

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

Richiesta di esempio:

  • type: string - always "azure",

  • name: string - Un nome descrittivo per la tua configurazione

  • tenant_id: string - UUID del tenant di Azure

  • vault_uri: string - URI del vault di Azure contenente la chiave principale che gestisci

  • key_name: string - Il nome della chiave principale di Azure Key Vault che gestisci.

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

Risposta di esempio:

{
"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 chiave AES-256 abilitata e concedi a OpenAI l'accesso. La chiave deve avere un tag openai_organization_id in formato libero, il cui valore deve corrispondere all'ID della tua organizzazione OpenAI. Per i passaggi di configurazione, consulta: Configurazione di OCI Vault per la gestione delle chiavi aziendali.

Richiesta di esempio:

  • type: stringa - sempre "oci"

  • purpose: stringa - "ekm"; il valore predefinito se omesso

  • name: string - Un nome descrittivo per la tua configurazione

  • region: stringa - La regione OCI in cui si trovano il vault e la chiave

  • vault_ocid: stringa - L'OCID completo del tuo vault

  • key_ocid: stringa - L'OCID completo della tua chiave AES-256

Non specificare key_version_ocid per 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>"
}'

Risposta di esempio:

{
"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 restituisce HTTP 200 in caso di successo. Salva l'id restituito e usalo come external_key_id quando crei un progetto. Le operazioni esistenti di elenco, recupero, convalida ed eliminazione si applicano anche alle registrazioni OCI.

Per il recupero tramite PSP, usa una registrazione RSA-3072 separata con purpose: "psp_decryption" e un valore key_version_ocid esatto. Imposta psp_decryption_key_id sull’ID di registrazione OpenAI corrispondente. Per questa chiave RSA, OpenAI necessita soltanto dell'accesso in lettura ai metadati e alle chiavi pubbliche. Per la configurazione completa, consulta: Configura le chiavi asimmetriche: OCI Vault.

Elimina una chiave esterna registrata nella tua organizzazione

Nota: l'eliminazione è bloccata finché un progetto o un'area di lavoro attiva utilizza la registrazione. Per EKM, archivia prima i progetti API associati; una registrazione EKM associata a un'area di lavoro rimane protetta. Per il ripristino PSP, sostituisci o rimuovi il valore di `psp_decryption_key_id` in ogni progetto attivo che fa riferimento alla registrazione prima di eliminarla. L'eliminazione di una registrazione OpenAI non comporta l'eliminazione della chiave nel cloud.

Richiesta di esempio

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

Risposta di esempio

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

Visualizza le chiavi esterne registrate per la tua organizzazione

Senza un filtro per finalità, l'elenco include sia le registrazioni EKM sia quelle per il ripristino PSP. Usa ?purpose=ekm o ?purpose=psp_decryption per filtrare in base alla finalità.

Richiesta di esempio

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

Risposta di esempio

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

Convalida una chiave esterna

Utilizza la convalida per verificare che OpenAI possa ancora accedere alla tua chiave nel cloud.

  • Per EKM, OpenAI verifica di poter eseguire operazioni di crittografia e decrittografia con la chiave. Per informazioni sul comportamento relativo alla revoca e alla memorizzazione nella cache, consulta:guida completa al ciclo di vita delle chiavi.

  • Per il ripristino PSP, OpenAI recupera la chiave pubblica della versione registrata e la confronta con la copia memorizzata. Una convalida riuscita non conferma che la tua identità di ripristino sia autorizzata a eseguire operazioni di decrittografia. Una convalida non riuscita non elimina né sostituisce la copia della chiave pubblica memorizzata.

Il recupero di una registrazione tramite una richiesta GET restituisce la configurazione memorizzata e non verifica nuovamente l'accesso alla tua chiave nel cloud.

Richiesta di esempio

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

Risposta di esempio

{
"status": "success"
}

Oppure, si è verificato un errore dal provider cloud.

Endpoint a livello di progetto

Crea un nuovo progetto con una chiave esterna ID

Questo è uguale all'endpoint Create Project esistente, con l'aggiunta del parametro external_key_id nella richiesta e nella risposta.

Richiesta di esempio

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

Risposta di esempio

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

Aggiorna un progetto esistente con un ID di chiave esterna

Questo è uguale all'endpoint Update Project esistente con l'aggiunta del parametro external_key_id nella richiesta e nella risposta.

Consigliamo di creare nuovi progetti API per i carichi di lavoro EKM. Prima di implementare EKM nei tuoi progetti di produzione esistenti, tieni presenti le seguenti procedure consigliate.

  • Testa prima nel tuo progetto di prova dell'API EKM tutte le funzionalità dell'API che utilizzi in produzione.

  • Applica un'implementazione graduale, anziché inserire i dati EKM in tutti i progetti API di produzione contemporaneamente.

Richiesta di esempio

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

Elenca tutti i progetti della tua organizzazione

Questo è lo stesso endpoint esistente ma con l'aggiunta di external_key_id nella risposta dell'API.

Richiesta di esempio

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

Risposta di esempio

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

Questo articolo è stato utile?