OpenAI
Această pagină a fost tradusă automat. Vezi articolul original în limba engleză.

EKM (chei externe) în API-ul de management

Află cum să gestionezi cheile externe pentru EKM folosind API-ul de gestionare.

Actualizat: 5 hours ago

Rezumat

Acces

  • Punctele finale EKM sunt accesibile în API-ul de administrare printr-o cheie API de administrator. https://platform.openai.com/settings/organization/admin-keys (nu folosi o cheie API obișnuită). Cheile API de administrator sunt disponibile pentru proprietarii organizației.

  • Folosește api.external_keys.write pentru a crea sau a șterge chei externe și api.external_keys.read pentru a lista, a prelua sau a valida chei externe. O cheie are nevoie de ambele permisiuni doar dacă trebuie să efectueze atât operațiuni de citire, cât și de scriere.

Utilizare

Restricții

  • Trebuie să testezi mai întâi EKM într-un proiect nou, prin API-ul de administrare.

  • Recomandăm crearea unor proiecte noi pentru sarcinile tale de lucru EKM. Ține cont de următoarele bune practici înainte de a implementa EKM în proiectele tale existente din producție.

    • Testează mai întâi toate funcționalitățile API pe care le folosești în producție în proiectul tău API de testare cu EKM.

    • Implementează EKM treptat, în loc să îl activezi simultan în toate proiectele API din producție.

Endpointuri la nivel de organizație

Înregistrați o cheie externă în organizația dvs.

AWS

Exemplu de cerere:

  • type: șir de caractere - întotdeauna „aws”

  • name: șir de caractere - Un nume ușor de recunoscut pentru configurația ta

  • role_arn: șir de caractere - ARN-ul rolului pe care OpenAI îl va asuma în mediul tău cloud

  • kms_arn: șir de caractere - ARN-ul din sistemul de gestionare a cheilor pentru cheia principală pe care o gestionezi

  • external_id: șir de caractere - ID-ul de organizație sau ID-ul proiectului 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>"
}'

Exemplu de răspuns:

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

Exemplu de cerere:

  • type: șir de caractere - întotdeauna „gcp”,

  • name: șir de caractere - Un nume ușor de recunoscut pentru configurația ta

  • workload_identity_project_number: șir de caractere - Numărul proiectului GCP în care ai înregistrat identitatea sarcinii de lucru OpenAI

  • workload_identity_pool_id: șir de caractere - Grupul care conține furnizorul Workload Identity înregistrat pentru OpenAI

  • workload_identity_provider_id: șir de caractere - Furnizorul Workload Identity înregistrat pentru OpenAI

  • audience: șir de caractere - Destinatarul pe care OpenAI trebuie să îl includă în token atunci când ne asumăm un rol prin serviciul tău GCP STS

  • kms_project_id: șir de caractere - Numele proiectului GCP care găzduiește sistemul tău KMS

  • kms_key_ring_name: șir de caractere - Setul de chei din sistemul de gestionare a cheilor care conține cheia principală pe care o gestionezi

  • kms_key_name: șir de caractere - Numele cheii principale din sistemul de gestionare a cheilor

  • kms_key_location: șir de caractere - Regiunea în care se află cheia principală din sistemul de gestionare a cheilor

Dacă sistemul tău KMS este găzduit într-un alt proiect GCP decât cel în care ai înregistrat identitatea Workload Identity a OpenAI, asigură-te că proiectul care conține identitatea Workload Identity a OpenAI are cel puțin KMS activat, accesând 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"
}'

Exemplu de răspuns:

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

Exemplu de cerere:

  • type: șir de caractere - întotdeauna „azure”,

  • name: șir de caractere - Un nume ușor de recunoscut pentru configurația ta

  • tenant_id: șir de caractere - UUID-ul entității tale găzduite Azure

  • vault_uri: șir de caractere - URI-ul seifului Azure care conține cheia principală pe care o gestionezi

  • key_name: șir de caractere - Numele cheii principale din Azure Key Vault pe care o gestionezi.

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

Exemplu de răspuns:

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

Configurează o cheie AES-256 activată și acordă acces companiei OpenAI. Cheia trebuie să aibă o etichetă în format liber openai_organization_id, setată la ID-ul organizației tale OpenAI. Pentru pașii de configurare, consultă: Configurarea OCI Vault pentru gestionarea cheilor la nivel de întreprindere.

Exemplu de cerere:

  • type: string – întotdeauna "oci"

  • purpose: string – "ekm"; valoarea implicită dacă parametrul este omis

  • name: string – Un nume ușor de recunoscut pentru configurația ta

  • region: string – Regiunea OCI în care se află seiful și cheia

  • vault_ocid: string – OCID-ul complet al seifului

  • key_ocid: string – OCID-ul complet al cheii AES-256

Nu transmite key_version_ocid pentru 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>"
}'

Exemplu de răspuns:

{
"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-ul returnează HTTP 200 dacă operațiunea reușește. Salvează valoarea id returnată și folosește-o ca external_key_id când creezi un proiect. Operațiunile existente de listare, preluare, validare și ștergere se aplică și înregistrărilor OCI.

Pentru recuperarea PSP, folosește o înregistrare RSA-3072 separată, cu purpose: "psp_decryption" și o valoare exactă pentru key_version_ocid. Setează psp_decryption_key_id la ID-ul înregistrării sale în OpenAI. OpenAI are nevoie doar de acces de citire la metadatele și cheile publice ale acelei chei RSA. Pentru configurarea completă, consultă: Configurarea cheilor asimetrice — OCI Vault.

Șterge o cheie externă înregistrată în organizația ta

Notă: Ștergerea este blocată cât timp un proiect sau un spațiu de lucru activ folosește înregistrarea. Pentru EKM, arhivează mai întâi proiectele API asociate; o înregistrare EKM asociată unui spațiu de lucru rămâne protejată. Pentru recuperarea PSP, înlocuiește sau golește valoarea psp_decryption_key_id în fiecare proiect activ care face referire la înregistrare, înainte de a o șterge. Ștergerea unei înregistrări OpenAI nu șterge cheia din cloud.

Exemplu de cerere

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

Exemplu de răspuns

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

Obține cheile externe înregistrate în organizația ta

Fără un filtru după scop, lista include atât înregistrările EKM, cât și pe cele pentru recuperare PSP. Folosește ?purpose=ekm sau ?purpose=psp_decryption pentru a filtra după scop.

Exemplu de cerere

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

Exemplu de răspuns

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

Validează o cheie externă

Folosește validarea pentru a verifica dacă OpenAI îți poate accesa în continuare cheia din cloud.

  • Pentru EKM, OpenAI verifică dacă poate cripta și decripta cu ajutorul cheii. Pentru detalii despre revocare și stocarea în cache, consultă: îndrumările privind ciclul de viață al cheilor.

  • Pentru recuperarea PSP, OpenAI preia cheia publică a versiunii înregistrate și o compară cu copia stocată. Validarea reușită nu confirmă că identitatea ta de recuperare poate efectua decriptarea. Validarea eșuată nu elimină și nu înlocuiește copia stocată a cheii publice.

Preluarea unei înregistrări prin GET returnează configurația stocată și nu verifică din nou accesul la cheia ta din cloud.

Exemplu de cerere

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

Exemplu de răspuns

{
"status": "success"
}

Sau o eroare transmisă de furnizorul de cloud.

Endpointuri la nivel de proiect

Creează un proiect nou cu un ID de cheie externă

Acest punct final este identic cu cel existent pentru crearea unui proiect, dar include și parametrul external_key_id în cerere și în răspuns.

Exemplu de cerere

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

Exemplu de răspuns

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

Actualizează un proiect existent cu ID-ul unei chei externe

Acesta este identic cu punctul final existent pentru actualizarea proiectelor, cu adăugarea parametrului external_key_id în cerere și în răspuns.

Recomandăm crearea unor proiecte API noi pentru sarcinile tale de lucru EKM. Ține cont de următoarele bune practici înainte de a implementa EKM în proiectele tale existente din producție.

  • Testează mai întâi toate funcționalitățile API pe care le folosești în producție în proiectul tău API de testare cu EKM.

  • Implementează EKM treptat, în loc să îl activezi simultan în toate proiectele API din producție.

Exemplu de cerere

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

Listează toate proiectele din organizația ta

Acest punct final este identic cu cel existent, dar include și external_key_id în răspunsul API.

Exemplu de cerere

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

Exemplu de răspuns

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

A fost util acest articol?