OpenAI
Din il-paġna ġiet tradotta awtomatikament bl-IA. Ara l-artiklu oriġinali bl-Ingliż.

EKM (Ċwievet Esterni) fl-API tal-Ġestjoni

Tgħallem kif timmaniġġja ċwievet esterni għall-EKM bl-API tal-Ġestjoni.

Aġġornat: 5 hours ago

Sommarju

Aċċess

  • Il-punti ta' tmiem tal-EKM huma aċċessibbli fl-API tal-Ġestjoni permezz ta' Ċavetta tal-API tal-Amministratur. https://platform.openai.com/settings/organization/admin-keys (tużax ċavetta normali tal-API). Iċ-ċwievet tal-API tal-amministratur huma disponibbli għas-sidien tal-organizzazzjoni.

  • Uża api.external_keys.write biex toħloq jew tħassar ċwievet esterni, u api.external_keys.read biex telenka, tirkupra jew tivvalida ċwievet esterni. Ċavetta waħda teħtieġ iż-żewġ ambiti ta' permess biss jekk trid twettaq operazzjonijiet kemm ta' qari kif ukoll ta' kitba.

Użu

  • Il-konfigurazzjoni tal-EKM tiegħek tiġi rreġistrata fil-livell tal-organizzazzjoni permezz ta' punt ta' tmiem ġdid https://api.openai.com/v1/organization/external_keys.

  • Meta tirreġistra l-konfigurazzjoni tal-EKM tiegħek, tirċievi external_key_id fil-forma extkey_xxxx.

  • Il-konfigurazzjonijiet tal-EKM jiġu attivati fil-livell tal-proġett billi tinkludi external_key_id fil-korp tat-talba lill-punt ta' tmiem eżistenti għall-ħolqien ta' proġett https://api.openai.com/v1/organization/projects.

Restrizzjonijiet

  • L-ewwel trid tittestja l-EKM fuq proġett ġdid permezz tal-API tal-Ġestjoni.

  • Nirrakkomandaw li toħloq proġetti ġodda għall-kompiti tiegħek li jużaw l-EKM. Qis il-prattiki rakkomandati li ġejjin qabel ma ddaħħal l-EKM fil-proġetti eżistenti tiegħek fl-ambjent tal-produzzjoni.

    • L-ewwel ittestja l-funzjonijiet kollha tal-API li tuża fl-ambjent tal-produzzjoni fil-proġett tat-test tiegħek tal-API bl-EKM.

    • Daħħal l-EKM gradwalment minflok tapplikaha għall-proġetti kollha tal-API fl-ambjent tal-produzzjoni f'daqqa.

endpoints fil-livell tal-organizzazzjoni

Irreġistra ċavetta esterna fl-organizzazzjoni tiegħek

AWS

Eżempju ta' talba:

  • type: string - dejjem “aws”

  • name: string - Isem faċli biex tagħraf il-konfigurazzjoni tiegħek

  • role_arn: string - L-ARN tar-rwol li OpenAI se tassumi fil-cloud tiegħek

  • kms_arn: string - L-ARN tas-Sistema tal-Ġestjoni taċ-Ċwievet għaċ-ċavetta prinċipali li timmaniġġja

  • external_id: string - L-ID tal-Organizzazzjoni tiegħek jew l-ID tal-proġett tal-API tiegħek

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

Eżempju ta' rispons:

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

Eżempju ta' talba:

  • type: string - dejjem “gcp”,

  • name: string - Isem faċli biex tagħraf il-konfigurazzjoni tiegħek

  • workload_identity_project_number: string - In-numru tal-proġett tal-GCP fejn irreġistrajt l-identità tal-kompiti ta' OpenAI

  • workload_identity_pool_id: string - Il-grupp li fih il-fornitur ta' Workload Identity li rreġistrajt għal OpenAI

  • workload_identity_provider_id: string - Il-fornitur ta' Workload Identity li rreġistrajt għal OpenAI

  • audience: string - L-udjenza li OpenAI għandha tinkludi fit-token meta nassumu rwol permezz tal-GCP STS tiegħek

  • kms_project_id: string - L-isem tal-proġett tal-GCP li fih il-KMS tiegħek

  • kms_key_ring_name: string - Il-grupp ta' ċwievet tas-Sistema tal-Ġestjoni taċ-Ċwievet li fih iċ-ċavetta prinċipali li timmaniġġja

  • kms_key_name: string - L-isem taċ-ċavetta prinċipali tas-Sistema tal-Ġestjoni taċ-Ċwievet

  • kms_key_location: string - Ir-reġjun fejn tinsab iċ-ċavetta prinċipali tas-Sistema tal-Ġestjoni taċ-Ċwievet tiegħek

Jekk il-KMS tiegħek jinsab fi proġett tal-GCP differenti minn dak fejn irreġistrajt il-Workload Identity ta' OpenAI, kun żgur li l-proġett li fih il-Workload Identity ta' OpenAI għandu tal-inqas il-KMS attivat billi tmur fuq 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"
}'

Eżempju ta' rispons:

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

Eżempju ta' talba:

  • type: string - dejjem “azure”,

  • name: string - Isem faċli biex tagħraf il-konfigurazzjoni tiegħek

  • tenant_id: string - L-UUID tat-tenant tiegħek ta' Azure

  • vault_uri: string - L-URI tal-kaxxa-forti ta' Azure li fiha ċ-ċavetta prinċipali li timmaniġġja

  • key_name: string - L-isem taċ-ċavetta prinċipali ta' Azure Key Vault li timmaniġġja.

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

Eżempju ta' rispons:

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

Ikkonfigura ċavetta AES-256 attivata u agħti aċċess lil OpenAI. Iċ-ċavetta jrid ikollha tikketta b'forma libera openai_organization_id bil-valur tal-ID tal-Organizzazzjoni tiegħek ta' OpenAI. Għall-passi tal-konfigurazzjoni, ara: Kif tikkonfigura OCI Vault għall-Ġestjoni taċ-Ċwievet tal-Intrapriża.

Eżempju ta' talba:

  • type: string - dejjem "oci"

  • purpose: string - "ekm"; il-valur predefinit meta jitħalla barra

  • name: string - Isem faċli biex tagħraf il-konfigurazzjoni tiegħek

  • region: string - Ir-reġjun tal-OCI li fih il-vault u ċ-ċavetta tiegħek

  • vault_ocid: string - L-OCID sħiħ tal-vault tiegħek

  • key_ocid: string - L-OCID sħiħ taċ-ċavetta AES-256 tiegħek

Tgħaddix key_version_ocid għall-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>"
}'

Eżempju ta' rispons:

{
"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 tirritorna HTTP 200 meta t-talba tirnexxi. Issejvja l-id irritornat u użah bħala external_key_id meta toħloq proġett. L-operazzjonijiet eżistenti biex telenka, tirkupra, tivvalida u tħassar japplikaw ukoll għar-reġistrazzjonijiet tal-OCI.

Għall-irkupru tal-PSP, uża reġistrazzjoni separata RSA-3072 b'purpose: "psp_decryption" u key_version_ocid eżatt. Issettja psp_decryption_key_id għall-ID tar-reġistrazzjoni tagħha ma' OpenAI. OpenAI teħtieġ biss aċċess għall-qari tal-metadata u ċ-ċwievet pubbliċi ta' dik iċ-ċavetta RSA. Għall-konfigurazzjoni sħiħa, ara: Ikkonfigura ċwievet asimmetriċi — OCI Vault.

Ħassar ċavetta esterna rreġistrata mal-organizzazzjoni tiegħek

Nota: It-tħassir jiġi mblukkat waqt li proġett jew workspace attiv ikun qed juża r-reġistrazzjoni. Għall-EKM, l-ewwel arkivja l-proġetti tal-API assoċjati; reġistrazzjoni tal-EKM assoċjata ma' workspace tibqa' protetta. Għall-irkupru tal-PSP, ibdel jew neħħi l-valur ta' psp_decryption_key_id minn kull proġett attiv li jirreferi għar-reġistrazzjoni qabel ma tħassarha. It-tħassir ta' reġistrazzjoni ma' OpenAI ma jħassarx iċ-ċavetta fil-cloud.

Eżempju ta' talba

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

Eżempju ta' tweġiba

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

Ikseb iċ-ċwievet esterni rreġistrati mal-organizzazzjoni tiegħek

Mingħajr filtru skont l-iskop, il-lista tinkludi kemm reġistrazzjonijiet tal-EKM kif ukoll reġistrazzjonijiet għall-irkupru tal-PSP. Uża ?purpose=ekm jew ?purpose=psp_decryption biex tiffiltra skont l-iskop.

Eżempju ta' talba

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

Eżempju ta' tweġiba

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

Ivvalida ċavetta esterna

Uża l-validazzjoni biex tiċċekkja li OpenAI għad għandha aċċess għaċ-ċavetta tiegħek fil-cloud.

  • Għall-EKM, OpenAI tiċċekkja li tista' tikkripta u tiddeċifra biċ-ċavetta. Għal kif jaħdmu r-revoka u l-ħażna fil-cache, ara: gwida dwar iċ-ċiklu tal-ħajja taċ-ċwievet.

  • Għall-irkupru tal-PSP, OpenAI tirkupra ċ-ċavetta pubblika tal-verżjoni rreġistrata u tqabbilha mal-kopja maħżuna. Validazzjoni li tirnexxi ma tikkonfermax li l-identità tiegħek għall-irkupru tista' tiddeċifra. Validazzjoni li tfalli ma tneħħix u lanqas tissostitwixxi l-kopja maħżuna taċ-ċavetta pubblika.

Meta tirkupra reġistrazzjoni b'GET, tingħata l-konfigurazzjoni maħżuna mingħajr ma jerġa' jiġi ċċekkjat l-aċċess għaċ-ċavetta tiegħek fil-cloud.

Eżempju ta' talba

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

Eżempju ta' rispons

{
"status": "success"
}

Jew, żball muri mill-fornitur tal-cloud.

endpoints fil-livell tal-proġett

Oħloq proġett ġdid b'ID ta' ċavetta esterna

Dan huwa l-istess bħall-punt ta' tmiem eżistenti għall-ħolqien ta' proġett, biż-żieda tal-parametru external_key_id fit-talba u fit-tweġiba.

Eżempju ta' talba

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

Eżempju ta' tweġiba

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

Aġġorna proġett eżistenti b'ID ta' ċavetta esterna

Dan huwa l-istess bħall-punt ta' tmiem eżistenti Aġġorna Proġett, biż-żieda tal-parametru external_key_id fit-talba u fir-rispons.

Nirrakkomandaw li toħloq proġetti ġodda tal-API għall-kompiti tiegħek li jużaw l-EKM. Qis il-prattiki rakkomandati li ġejjin qabel ma ddaħħal l-EKM fil-proġetti eżistenti tiegħek fl-ambjent tal-produzzjoni.

  • L-ewwel ittestja l-funzjonijiet kollha tal-API li tuża fl-ambjent tal-produzzjoni fil-proġett tat-test tiegħek tal-API bl-EKM.

  • Daħħal l-EKM gradwalment minflok tapplikaha għall-proġetti kollha tal-API fl-ambjent tal-produzzjoni f'daqqa.

Eżempju ta' talba

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

Elenka l-proġetti kollha tal-organizzazzjoni tiegħek

Dan huwa l-istess bħall-punt ta' tmiem eżistenti, iżda biż-żieda ta' external_key_id fit-tweġiba tal-API.

Eżempju ta' talba

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

Eżempju ta' tweġiba

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

Dan l-artiklu kien ta’ għajnuna?