此頁面由機器翻譯。查看原文英文文章。

Management API 中的 EKM(外部金鑰)

了解如何使用管理 API 管理 EKM 的外部密鑰。

更新日期:3 days ago

摘要

存取

  • 你可以使用管理員 API 密鑰,透過管理 API 存取 EKM 端點。https://platform.openai.com/settings/organization/admin-keys(請勿使用一般 API 密鑰)。組織擁有者可使用管理員 API 密鑰。

  • 使用 api.external_keys.write 建立或刪除外部密鑰,使用 api.external_keys.read 列出、擷取或驗證外部密鑰。只有在同一密鑰需要執行讀取和寫入操作時,才需要同時具備這兩個權限範圍。

使用方式

限制

  • 你必須先透過管理 API,在新專案中測試 EKM。

  • 我們建議為 EKM 工作負載建立新專案。在現有正式環境專案中部署 EKM 前,請留意以下最佳實務。

    • 先在 EKM API 測試專案中,測試你在正式環境使用的所有 API 功能。

    • 採用逐步部署方式,不要一次過為所有正式環境 API 專案啟用 EKM。

組織層級 endpoints

在你的組織註冊外部金鑰

AWS

請求範例:

  • type:字串 — 一律為「aws」

  • name:字串 — 便於識別這項設定的名稱

  • role_arn:字串 — OpenAI 將在你的雲端環境中擔任的角色 ARN

  • kms_arn:字串 — 你所管理的主密鑰在密鑰管理系統中的 ARN

  • external_id:字串 — 你的組織 ID 或 API 項目 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>"
}'

回應範例:

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

請求範例:

  • type:字串 — 一律為「gcp」,

  • name:字串 — 便於識別這項設定的名稱

  • workload_identity_project_number:字串 — 你註冊 OpenAI 工作負載身分所在的 GCP 項目的數字編號

  • workload_identity_pool_id:字串 — 包含你為 OpenAI 註冊的工作負載身分供應商的集區

  • workload_identity_provider_id:字串 — 你為 OpenAI 註冊的工作負載身分供應商

  • audience:字串 — OpenAI 透過你的 GCP STS 擔任角色時,應在權杖中傳入的目標對象

  • kms_project_id:字串 — 你的 KMS 所在的 GCP 項目名稱

  • kms_key_ring_name:字串 — 密鑰管理系統中包含你所管理的主密鑰的密鑰環

  • kms_key_name:字串 — 密鑰管理系統中的主密鑰名稱

  • kms_key_location:字串 — 密鑰管理系統中的主密鑰所在的區域

如果你的 KMS 與你註冊 OpenAI 工作負載身分所在的 GCP 項目不同,請前往 https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview,確保包含 OpenAI 工作負載身分的項目至少已啟用 KMS。

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

回應範例:

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

請求範例:

  • type:字串 — 一律為「azure」,

  • name:字串 — 便於識別這項設定的名稱

  • tenant_id:字串 — 你的 Azure 租戶 UUID

  • vault_uri:字串 — 包含你所管理的主密鑰的 Azure 保存庫 URI

  • key_name:字串 — 你所管理的 Azure Key Vault 主密鑰的名稱。

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

回應範例:

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

設定並啟用 AES-256 密鑰,然後授予 OpenAI 存取權限。密鑰必須具有自由格式標籤 openai_organization_id,並將其值設為你的 OpenAI 組織 ID。設定步驟請參閱:設定 OCI Vault 以使用企業密鑰管理。

請求範例:

  • type:字串 — 固定為 "oci"

  • purpose:字串 — "ekm";省略時使用此預設值

  • name:字串 — 便於識別此設定的名稱

  • region:字串 — 存放保管庫和密鑰的 OCI 區域

  • vault_ocid:字串 — 保管庫的完整 OCID

  • key_ocid:字串 — AES-256 密鑰的完整 OCID

使用 EKM 時,請勿傳入 key_version_ocid。

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

回應範例:

{
"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 會傳回 HTTP 200。儲存傳回的 id,並在建立專案時將其用作 external_key_id。現有的列出、擷取、驗證和刪除操作亦適用於 OCI 註冊記錄。

如要使用 PSP 復原,請另外建立 RSA-3072 註冊記錄,指定 purpose: "psp_decryption" 及確切的 key_version_ocid。將 psp_decryption_key_id 設為該記錄的 OpenAI 註冊 ID。OpenAI 只需要讀取該 RSA 密鑰的中繼資料和公開密鑰的權限。完整設定方式請參閱:設定非對稱密鑰 — OCI Vault。

刪除在你的組織中註冊的外部密鑰

注意:只要仍有使用中的專案或工作區採用該註冊記錄,就無法將其刪除。對於 EKM,請先封存相關的 API 專案;與工作區關聯的 EKM 註冊記錄仍受保護,無法刪除。對於 PSP 復原,刪除註冊記錄前,請先在所有參照該記錄且仍在使用中的專案內,替換或清除 psp_decryption_key_id。刪除 OpenAI 註冊記錄不會刪除雲端密鑰。

請求範例

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

回應範例

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

取得在你的組織中註冊的外部密鑰

如未按用途篩選,清單會同時包含 EKM 和 PSP 復原的註冊記錄。使用 ?purpose=ekm 或 ?purpose=psp_decryption 按用途篩選。

請求範例

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

回應範例

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

驗證外部密鑰

使用驗證功能,檢查 OpenAI 是否仍可存取你的雲端密鑰。

  • 對於 EKM,OpenAI 會檢查能否使用該密鑰進行加密和解密。有關撤銷和快取的運作方式,請參閱:密鑰生命週期指引。

  • 對於 PSP 復原,OpenAI 會擷取已註冊版本的公開密鑰,並與已儲存的快照比較。驗證成功並不代表用於復原的身分具備解密能力。驗證失敗不會移除或取代已儲存的公開密鑰快照。

使用 GET 擷取註冊記錄時,只會傳回已儲存的設定,不會重新檢查是否可存取你的雲端密鑰。

請求範例

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

回應範例

{
"status": "success"
}

或者,由雲端供應商傳回錯誤。

專案層級 endpoints

使用外部密鑰 ID 建立新項目

這與現有的「建立項目」端點相同,只是在請求和回應中新增了 external_key_id 參數。

請求範例

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

回應範例

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

以外部密鑰 ID 更新現有專案

這與現有的「更新專案」端點相同,只是在請求和回應中新增了 external_key_id 參數。

我們建議為 EKM 工作負載建立新的 API 專案。在現有正式環境專案中部署 EKM 前,請留意以下最佳實務。

  • 先在 EKM API 測試專案中,測試你在正式環境使用的所有 API 功能。

  • 採用逐步部署方式,不要一次過為所有正式環境 API 專案啟用 EKM。

請求範例

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

列出組織中的所有項目

這與現有端點相同,只是在 API 回應中新增了 external_key_id。

請求範例

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

回應範例

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

這篇文章對你有幫助嗎?