OpenAI
Denne side er maskinoversat. Se den originale engelske artikel.

EKM (eksterne nøgler) i Management API

Se, hvordan du administrerer eksterne nøgler til EKM med Management API.

Opdateret: 40 minutes ago

Oversigt

Adgang

  • EKM-endepunkter er tilgængelige i administrations-API'et via en administrator-API-nøgle. https://platform.openai.com/settings/organization/admin-keys (brug ikke en almindelig API-nøgle). Administrator-API-nøgler er tilgængelige for organisationsejere.

  • Brug api.external_keys.write til at oprette eller slette eksterne nøgler og api.external_keys.read til at vise en liste over, hente eller validere eksterne nøgler. En nøgle behøver kun begge rettighedsområder, hvis den skal udføre både læse- og skriveoperationer.

Brug

Begrænsninger

  • Du skal først teste EKM på et nyt projekt via administrations-API'et.

  • Vi anbefaler at oprette nye projekter til dine EKM-arbejdsbelastninger. Følg disse anbefalinger, før du udruller EKM til dine eksisterende produktionsprojekter.

    • Test først alle API-funktioner, som du bruger i produktion, i dit API-testprojekt med EKM.

    • Udrul EKM gradvist i stedet for at aktivere det på alle API-projekter i produktion på én gang.

End points på organisationsniveau

Registrer en ekstern nøgle i din organisation

AWS

Eksempel på anmodning:

  • type: streng – altid »aws«

  • name: streng – Et letgenkendeligt navn til din konfiguration

  • role_arn: streng – ARN for den rolle, som OpenAI påtager sig i dit cloudmiljø

  • kms_arn: streng – ARN i nøgleadministrationssystemet for den hovednøgle, du administrerer

  • external_id: streng – Dit organisations-id eller API-projekt-id

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

Eksempel på svar:

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

Eksempel på anmodning:

  • type: streng – altid »gcp«,

  • name: streng – Et letgenkendeligt navn til din konfiguration

  • workload_identity_project_number: streng – Det numeriske projektnummer for det GCP-projekt, hvor du registrerede OpenAI's workloadidentitet

  • workload_identity_pool_id: streng – Den pulje, der indeholder den Workload Identity-udbyder, du registrerede for OpenAI

  • workload_identity_provider_id: streng – Den Workload Identity-udbyder, du registrerede for OpenAI

  • audience: streng – Den målgruppe, OpenAI skal angive i tokenet, når vi påtager os en rolle via din GCP STS

  • kms_project_id: streng – Navnet på det GCP-projekt, hvor dit KMS er placeret

  • kms_key_ring_name: streng – Den nøglering i nøgleadministrationssystemet, der indeholder den hovednøgle, du administrerer

  • kms_key_name: streng – Navnet på hovednøglen i nøgleadministrationssystemet

  • kms_key_location: streng – Den region, hvor hovednøglen i dit nøgleadministrationssystem er placeret

Hvis dit KMS er placeret i et andet GCP-projekt end det, hvor du registrerede OpenAI's Workload Identity, skal du sikre dig, at KMS som minimum er aktiveret i projektet med OpenAI's Workload Identity. Det gør du ved at gå til 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"
}'

Eksempel på svar:

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

Eksempel på anmodning:

  • type: streng – altid »azure«,

  • name: streng – Et letgenkendeligt navn til din konfiguration

  • tenant_id: streng – UUID'et for din Azure-lejer

  • vault_uri: streng – URI'en for den Azure-nøgleboks, der indeholder den hovednøgle, du administrerer

  • key_name: streng – Navnet på den hovednøgle i Azure Key Vault, du administrerer.

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

Eksempel på svar:

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

Konfigurer en aktiveret AES-256-nøgle, og giv OpenAI adgang. Nøglen skal have et frit defineret openai_organization_id-tag, der er indstillet til dit OpenAI-organisations-id. Se opsætningsvejledningen her: Konfiguration af OCI Vault til Enterprise Key Management.

Eksempel på anmodning:

  • type: streng – altid "oci"

  • purpose: streng – "ekm"; standardværdien, hvis feltet udelades

  • name: streng – Et beskrivende navn til din konfiguration

  • region: streng – Den OCI-region, hvor din vault og nøgle er placeret

  • vault_ocid: streng – Det fulde OCID for din vault

  • key_ocid: streng – Det fulde OCID for din AES-256-nøgle

Angiv ikke key_version_ocid for 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>"
}'

Eksempel på svar:

{
"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'et returnerer HTTP 200, når anmodningen lykkes. Gem det returnerede id, og brug det som external_key_id, når du opretter et projekt. De eksisterende operationer til at vise lister, hente, validere og slette gælder også for OCI-registreringer.

Til PSP-gendannelse skal du bruge en separat RSA-3072-registrering med purpose: "psp_decryption" og et præcist key_version_ocid. Indstil psp_decryption_key_id til registreringens id hos OpenAI. OpenAI behøver kun læseadgang til metadata og offentlige nøgler for den pågældende RSA-nøgle. Se den komplette opsætningsvejledning her: Opsæt asymmetriske nøgler – OCI Vault.

Slet en ekstern nøgle, der er registreret i din organisation

Bemærk: Sletning er blokeret, så længe et aktivt projekt eller arbejdsområde bruger registreringen. For EKM skal du først arkivere de tilknyttede API-projekter. En EKM-registrering, der er knyttet til et arbejdsområde, er fortsat beskyttet. For PSP-gendannelse skal du erstatte eller rydde psp_decryption_key_id på alle aktive projekter, der henviser til registreringen, før du sletter den. Når du sletter en OpenAI-registrering, slettes nøglen i skyen ikke.

Eksempel på anmodning

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

Eksempel på svar

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

Hent de eksterne nøgler, der er registreret i din organisation

Uden et filter for formål indeholder listen både EKM-registreringer og registreringer til PSP-gendannelse. Brug ?purpose=ekm eller ?purpose=psp_decryption til at filtrere efter formål.

Eksempel på anmodning

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

Eksempel på svar

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

Valider en ekstern nøgle

Brug validering til at kontrollere, at OpenAI stadig har adgang til din nøgle i skyen.

  • For EKM kontrollerer OpenAI, at nøglen kan bruges til kryptering og dekryptering. Læs om tilbagekaldelse og caching i vejledningen om nøglers livscyklus.

  • For PSP-gendannelse henter OpenAI den registrerede versions offentlige nøgle og sammenligner den med det gemte øjebliksbillede. En vellykket validering bekræfter ikke, at din gendannelsesidentitet kan dekryptere. En mislykket validering fjerner eller erstatter ikke det gemte øjebliksbillede af den offentlige nøgle.

Når du henter en registrering med GET, returneres den gemte konfiguration, uden at adgangen til din nøgle i skyen kontrolleres igen.

Eksempel på anmodning

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

Eksempel på svar

{
"status": "success"
}

Eller en fejl, der blev returneret fra cloududbyderen.

End points på projektniveau

Opret et nyt projekt med et eksternt nøgle-id

Dette er det samme som det eksisterende endepunkt til at oprette projekter, men med parameteren external_key_id tilføjet i anmodningen og svaret.

Eksempel på anmodning

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

Eksempel på svar

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

Opdater et eksisterende projekt med et eksternt nøgle-id

Dette svarer til det eksisterende endepunkt til projektopdatering, men med parameteren external_key_id tilføjet i anmodningen og svaret.

Vi anbefaler at oprette nye API-projekter til dine EKM-arbejdsbelastninger. Følg disse anbefalinger, før du udruller EKM til dine eksisterende produktionsprojekter.

  • Test først alle API-funktioner, som du bruger i produktion, i dit API-testprojekt med EKM.

  • Udrul EKM gradvist i stedet for at aktivere det på alle API-projekter i produktion på én gang.

Eksempel på anmodning

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

Vis alle projekter i din organisation

Dette er det samme som det eksisterende endepunkt, men med external_key_id tilføjet i API-svaret.

Eksempel på anmodning

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

Eksempel på svar

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

Var denne artikel nyttig?