向 OpenAI 註冊由雲端供應商管理的 RSA-3072 非對稱金鑰組。
私密金鑰會留在 AWS KMS、Azure Key Vault、Google Cloud KMS 或 Oracle Cloud Infrastructure (OCI) Vault 中。註冊時,OpenAI 會儲存對應公開金鑰的副本。
註冊金鑰不會設定產品功能或儲存空間。本指南說明如何設定用於 PSP 解密 的金鑰。
備妥組織 ID。設定雲端信任關係、註冊金鑰及存取 API 時,請使用同一個組織。
建立具備外部金鑰讀寫權限的組織管理員 API 金鑰 ,並以安全的方式將其載入 OPENAI_ADMIN_KEY 環境變數。專案推論金鑰無法用於此操作。
確認你有權建立並啟用 RSA-3072 金鑰,也有權依本指南指定的範圍,授予 OpenAI 讀取公開金鑰的權限。
僅允許獲授權的使用者使用私密金鑰。只要仍有紀錄依賴舊版金鑰,就必須保留該版本。
註冊金鑰前,請依照雲端供應商對應的步驟完成設定。各供應商的設定均使用 RSA-3072,且僅授予 OpenAI 讀取公開金鑰與中繼資料的權限。
AWS KMS 依序開啟 KMS > 客戶管理的金鑰 > 建立金鑰 ,選擇你的區域,然後使用下列設定:
金鑰類型: 非對稱
金鑰用途: 加密與解密
金鑰規格: RSA_3072
指定你自己的金鑰管理員,然後完成金鑰建立程序。讓金鑰維持啟用狀態,並複製以 key/<CUSTOMER_KMS_KEY_ID> 結尾的完整 ARN。請勿使用別名 ARN。
依序開啟 IAM > 政策 > 建立政策 > JSON 。將 <CUSTOMER_KMS_KEY_ARN> 替換為你的金鑰 ARN,並將這份政策儲存為 OpenAI-PublicKeyRead。
1 2 3 4 5 6 7 8 9 10 {
"Version" : "2012-10-17" ,
"Statement" : [
{
"Effect" : "Allow" ,
"Action" : [ "kms:DescribeKey" , "kms:GetPublicKey" ],
"Resource" : "<CUSTOMER_KMS_KEY_ARN>"
}
]
} 金鑰支援解密,但 OpenAI 只需要上述讀取權限。請勿授予 OpenAI 金鑰使用者或金鑰管理員權限。
依序開啟 IAM > 角色 > 建立角色 > 自訂信任政策 。將 <OPENAI_ORG_ID> 替換為你的 OpenAI 組織 ID。請保留原有的 OpenAI 主體。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 {
"Version" : "2012-10-17" ,
"Statement" : [
{
"Effect" : "Allow" ,
"Principal" : {
"AWS" : "arn:aws:iam::790389265272:role/EnterpriseKeyManagement"
},
"Action" : "sts:AssumeRole" ,
"Condition" : {
"StringEquals" : {
"sts:ExternalId" : "<OPENAI_ORG_ID>"
}
}
}
]
} 附加 OpenAI-PublicKeyRead 政策,建立角色並複製角色 ARN。註冊金鑰時,請將 external_id 設為同一個組織 ID。
確認金鑰政策已授權該角色。如果政策未將授權委派給 IAM,請新增下列陳述式。將 <CUSTOMER_ROLE_ARN> 替換為你的角色 ARN,並保留現有的管理員權限。
在這份 KMS 金鑰政策中,"Resource": "*" 僅適用於附加了這份政策的金鑰。IAM 政策則使用該金鑰的完整 ARN。
1 2 3 4 5 6 7 8 9 {
"Sid" : "AllowPublicKeyRead" ,
"Effect" : "Allow" ,
"Principal" : {
"AWS" : "<CUSTOMER_ROLE_ARN>"
},
"Action" : [ "kms:DescribeKey" , "kms:GetPublicKey" ],
"Resource" : "*"
} 請記下角色 ARN 和金鑰 ARN,以供註冊時使用。
Azure Key Vault 請租用戶管理員將 EKM - OpenAI Azure 新增至你的租用戶。此應用程式的 ID 為 20a14814-5ab7-4612-a671-1382b412bf93。
安裝 Azure CLI,然後登入並檢查租用戶中是否已有此應用程式:
1 2 3 az login --tenant '<CUSTOMER_TENANT_ID>'
az ad sp show --id '20a14814-5ab7-4612-a671-1382b412bf93' \
--query '{name:displayName,objectId:id}' -o table 如果找不到此應用程式,請執行下列指令新增:
az ad sp create --id '20a14814-5ab7-4612-a671-1382b412bf93' \
--query '{name:displayName,objectId:id}' -o table 記下此應用程式在租用戶中的物件 ID,以供指派角色時使用。
依序開啟 金鑰保存庫 > 建立 。選取你的訂用帳戶、資源群組、保存庫名稱與區域。在 存取設定 下選擇 Azure 角色型存取控制 。
管理員必須具備可建立金鑰的角色,例如此保存庫的 Key Vault Crypto Officer 。請勿將該角色授予 OpenAI。
在保存庫中依序開啟 物件 > 金鑰 > 產生/匯入 ,並使用下列設定:
名稱: <OPENAI_ORG_ID>--asymmetric-key,請填入你的 OpenAI 組織 ID
金鑰類型: RSA
RSA 金鑰大小: 3072
已啟用: 是
如果設定了啟用日期或到期日期,請確認金鑰目前有效。金鑰允許的作業必須包含 解密 。OpenAI 僅取得金鑰的讀取權限。
也支援金鑰保存庫中的 RSA-HSM 金鑰。不支援獨立的受控 HSM 端點。
建立自訂角色,並加入用於讀取金鑰的 DataAction。將下列內容儲存為 public-key-reader.json,並填入你的訂用帳戶和資源群組資訊。
1 2 3 4 5 6 7 8 9 10 11 12 {
"Name" : "OpenAI Public Key Reader" ,
"IsCustom" : true ,
"Description" : "Read key metadata and public keys." ,
"Actions" : [],
"NotActions" : [],
"DataActions" : [ "Microsoft.KeyVault/vaults/keys/read" ],
"NotDataActions" : [],
"AssignableScopes" : [
"/subscriptions/<CUSTOMER_SUBSCRIPTION_ID>/resourceGroups/<CUSTOMER_RESOURCE_GROUP>"
]
} 將 VAULT_RESOURCE_ID 設為保存庫 屬性 中的 Azure 資源 ID,請勿使用保存庫的 HTTPS URI。將 OPENAI_SP_ID 設為應用程式在租用戶中的物件 ID,然後在金鑰範圍內指派角色:
1 2 3 4 5 6 7 8 9 10 11 12 az role definition create --role-definition @public-key-reader.json
OPENAI_SP_ID = '<CUSTOMER_OPENAI_SP_OBJECT_ID>'
VAULT_RESOURCE_ID = '<CUSTOMER_VAULT_RESOURCE_ID>'
KEY_NAME = '<OPENAI_ORG_ID>--asymmetric-key'
KEY_SCOPE = " $VAULT_RESOURCE_ID /keys/ $KEY_NAME "
az role assignment create \
--assignee-object-id " $OPENAI_SP_ID " \
--assignee-principal-type ServicePrincipal \
--role 'OpenAI Public Key Reader' \
--scope " $KEY_SCOPE " 如果保存庫使用舊版存取原則,請改為授予金鑰的 取得 權限,並保留現有的權限模型。
記下租用戶 ID、保存庫 URI 和金鑰名稱。開啟已啟用的金鑰版本,從 金鑰識別碼 的末尾複製由 32 個十六進位字元組成的版本識別碼。
Google Cloud KMS 在金鑰所屬專案中啟用 Cloud KMS,並在身分聯盟所屬專案中啟用 IAM 和 Security Token Service。如果是兩個不同的專案,請在兩者中都啟用 Cloud KMS。
記下身分聯盟所屬專案的 12 位數專案編號。KMS 可能位於另一個專案。
依序開啟 安全性 > 金鑰管理 。先建立金鑰環,再使用下列設定建立金鑰:
保護層級: 軟體
用途: 非對稱解密
演算法: 3072 位元 RSA、OAEP 填補、SHA256 摘要
複製 KMS 專案 ID、位置、金鑰環、金鑰名稱及已啟用的版本。請指定確切的版本,例如 "1",不要使用 "latest" 或 "0"。非對稱金鑰沒有主要版本。
依序開啟 IAM 與管理 > 工作負載身分聯盟 。建立全域集區(例如 openai-keys)及 OIDC 供應商(例如 openai-google),並使用下列設定:
供應商設定
值
核發者 URL
https://accounts.google.com
允許的目標對象
你的完整 OpenAI 組織 ID
屬性對應
google.subject = assertion.sub
屬性條件
assertion.sub == '105900137572174660365'
請將目標對象設為你的 OpenAI 組織 ID。保留原有的核發者與 OpenAI 主體識別值。
在 IAM 與管理 > 角色 中,為 KMS 專案建立具備下列權限的自訂角色:
cloudkms.cryptoKeyVersions.get
cloudkms.cryptoKeyVersions.viewPublicKey 這兩項權限缺一不可,只授予公開金鑰檢視者角色並不足夠。無須授予解密、簽署或模擬服務帳戶的權限。
在金鑰的 權限 分頁上選擇 授予存取權 。將下列主體中的 <CUSTOMER_GCP_PROJECT_NUMBER> 和 <CUSTOMER_GCP_POOL_ID> 替換為實際值,再將角色指派給該主體:
principal://iam.googleapis.com/projects/<CUSTOMER_GCP_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<CUSTOMER_GCP_POOL_ID>/subject/105900137572174660365 使用集區所屬專案的編號,並將授權範圍限於這把金鑰。金鑰層級的 IAM 權限涵蓋其所有版本。記下集區 ID、供應商 ID、用作目標對象的組織 ID,以及 KMS 識別資訊,以供註冊時使用。
OCI Vault 請向你的 OpenAI 聯絡人確認是否可註冊 OCI 金鑰,以及哪些區域可供使用。你的租用戶和 OpenAI 的租用戶都必須訂閱所選區域。
在 OCI 主控台中開啟 保存庫 。在 OCI 商業區域(例如 us-ashburn-1)中建立或選取保存庫,然後等候保存庫狀態變為 作用中 。
開啟 主要加密金鑰 ,然後選擇 建立金鑰 。選用 RSA,將金鑰長度設為 3072 位元,並選擇軟體保護。讓金鑰維持啟用狀態。如果也要設定 EKM,請另外使用一把 AES-256 金鑰。
在金鑰上新增下列自由格式標記:
標記欄位
值
標記命名空間
無(自由格式標記)
標記索引鍵
openai_organization_id
標記值
你的 OpenAI 組織 ID,包含 org- 前置詞
即使已為保存庫或區間加上標記,也必須在金鑰本身加上這個標記。
在 身分識別與安全性 > 政策 中,選取租用戶的根區間並建立政策。開啟 顯示手動編輯器 ,輸入下列陳述式,並填入你的保存庫 OCID 和金鑰 OCID。請保留原有的 OpenAI 租用戶和群組識別碼。
Define tenancy OpenAIEKM as ocid1.tenancy.oc1..aaaaaaaa4kzwe5jdr4gsxft7dfnwbnp3aozhxeskabsqo7czdkbp6fkh3uha
Define group OpenAIEKMProduction as ocid1.group.oc1..aaaaaaaaerxukyeaxwqtbsxasnp54mem3sfgyokzdk7s27o7yvepluynxi5q
Admit group OpenAIEKMProduction of tenancy OpenAIEKM to {VAULT_READ} in tenancy where target.vault.id = '<CUSTOMER_VAULT_OCID>'
Admit group OpenAIEKMProduction of tenancy OpenAIEKM to {KEY_READ} in tenancy where target.key.id = '<CUSTOMER_KEY_OCID>' VAULT_READ 可讓 OpenAI 查詢保存庫端點。KEY_READ 可讓 OpenAI 讀取金鑰的中繼資料及所選版本的公開金鑰。這些權限不包含解密、匯出金鑰或管理金鑰。即使已另外為 PSP 設定 OCI Object Storage 政策,仍須使用這個金鑰管理身分。
記下區域識別碼、保存庫 OCID 和金鑰 OCID。在金鑰的版本清單中,複製要註冊的版本所對應的完整 OCID。版本 OCID 以 ocid1.keyversion. 開頭,金鑰 OCID 則以 ocid1.key. 開頭。
請使用該版本的確切 OCID,請勿使用 latest 或版本號碼。保存庫、金鑰和版本必須位於同一個商業區域,且金鑰必須屬於註冊時指定的保存庫。
下列範例使用 curl 和相容於 Bash 的 shell。以安全的方式載入 OPENAI_ADMIN_KEY,然後設定組織 ID:
1 2 3 4 5 6 API_BASE = "https://api.openai.com/v1"
ORG_ID = "<OPENAI_ORG_ID>"
: "${ OPENAI_ADMIN_KEY :? Load your organization admin key securely }"
KEYS_URL = " $API_BASE /organization/external_keys"
purpose 列舉欄位接受 ekm(預設值)或 psp_decryption。本指南中的非對稱金鑰請使用 psp_decryption。ekm 用於企業金鑰管理(EKM)。
將供應商對應的請求內容儲存為 registration.json。請將範例值替換為實際值,JSON 不會展開 shell 變數。
1 2 3 4 5 6 7 8 {
"type" : "aws" ,
"purpose" : "psp_decryption" ,
"name" : "asymmetric-key-aws" ,
"role_arn" : "<CUSTOMER_ROLE_ARN>" ,
"external_id" : "<OPENAI_ORG_ID>" ,
"kms_arn" : "<CUSTOMER_KMS_KEY_ARN>"
}
1 2 3 4 5 6 7 8 9 {
"type" : "azure" ,
"purpose" : "psp_decryption" ,
"name" : "asymmetric-key-azure" ,
"tenant_id" : "<CUSTOMER_TENANT_ID>" ,
"vault_uri" : "https://<CUSTOMER_VAULT_NAME>.vault.azure.net" ,
"key_name" : "<OPENAI_ORG_ID>--asymmetric-key" ,
"key_version" : "<CUSTOMER_KEY_VERSION>"
}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 {
"type" : "gcp" ,
"purpose" : "psp_decryption" ,
"name" : "asymmetric-key-gcp" ,
"workload_identity_project_number" : "<CUSTOMER_GCP_PROJECT_NUMBER>" ,
"workload_identity_pool_id" : "openai-keys" ,
"workload_identity_provider_id" : "openai-google" ,
"audience" : "<OPENAI_ORG_ID>" ,
"kms_project_id" : "<CUSTOMER_KMS_PROJECT_ID>" ,
"kms_key_ring_name" : "asymmetric-keys" ,
"kms_key_name" : "asymmetric-key" ,
"kms_key_location" : "us-central1" ,
"kms_key_version" : "1"
}
1 2 3 4 5 6 7 8 9 {
"type" : "oci" ,
"purpose" : "psp_decryption" ,
"name" : "asymmetric-key-oci" ,
"region" : "us-ashburn-1" ,
"vault_ocid" : "<CUSTOMER_VAULT_OCID>" ,
"key_ocid" : "<CUSTOMER_KEY_OCID>" ,
"key_version_ocid" : "<CUSTOMER_KEY_VERSION_OCID>"
}
1 2 3 4 5 curl --fail-with-body -sS " $KEYS_URL " \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY " \
-H "OpenAI-Organization: $ORG_ID " \
-H "Content-Type: application/json" \
--data @registration.json
註冊時,系統會先驗證金鑰,再儲存註冊資料。成功時會傳回 HTTP 200,回應中包含 extkey ID 和供應商設定。以下是回應欄位的範例:
1 2 3 4 5 6 7 8 {
"id" : "extkey_11111111111111111111111111111111" ,
"object" : "organization.external_key" ,
"name" : "asymmetric-key-gcp" ,
"type" : "gcp" ,
"purpose" : "psp_decryption" ,
"api_project_ids" : []
}
儲存回應中的註冊 ID:
KEY_ID = "<EXTERNAL_KEY_ID>"
GET 會傳回已儲存的詳細資料。POST /validate 會重新檢查目前的存取權限,並比對已儲存的公開金鑰,以確認金鑰仍然有效。此操作不會解密紀錄,也不會更新快照。
1 2 3 curl --fail-with-body -sS " $KEYS_URL / $KEY_ID " \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY " \
-H "OpenAI-Organization: $ORG_ID "
1 2 3 curl --fail-with-body -sS -X POST " $KEYS_URL / $KEY_ID /validate" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY " \
-H "OpenAI-Organization: $ORG_ID "
預期回應(HTTP 200):
{ "status" : "success" }
變更金鑰、權限或網路設定後,請再次驗證。如果變更了 IAM 設定,請等候變更生效後再重試。
若要使用已註冊的金鑰進行 PSP 解密,請為專案選取這把金鑰 。
使用 purpose=psp_decryption 列出這些非對稱金鑰的註冊資料。省略篩選條件會傳回所有用途的註冊資料,purpose=ekm 則只會傳回 EKM 的註冊資料。
1 2 3 4 5 6 curl --fail-with-body -sS --get " $KEYS_URL " \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY " \
-H "OpenAI-Organization: $ORG_ID " \
--data-urlencode "purpose=psp_decryption" \
--data-urlencode "order=asc" \
--data-urlencode "limit=20"
只要 has_more 為 true,就將 after 設為 last_id 的值以取得下一頁。請保留 purpose、order 和 limit 的原值。
在 AWS 建立替代金鑰,或在 Azure、GCP 或 OCI 建立新的金鑰版本,並授予 OpenAI 讀取權限。
註冊替代金鑰或新版本。
在專案中選取新的 extkey ID ,並確認選取結果。
註冊資料是固定的快照,不會隨雲端金鑰輪替而更新。只要仍有紀錄依賴舊的私密金鑰,就必須保留該金鑰。變更所選金鑰不會遷移既有紀錄。
刪除註冊資料前,請在每個使用中的專案內清除金鑰選擇 或改選其他金鑰 :
1 2 3 curl --fail-with-body -sS -X DELETE " $KEYS_URL / $KEY_ID " \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY " \
-H "OpenAI-Organization: $ORG_ID "
刪除成功時會傳回 HTTP 200,回應中包含 object: "organization.external_key.deleted"。此操作不會刪除你的雲端金鑰。
錯誤
檢查項目
401 或 403
使用組織管理員 API 金鑰,並確認具備存取外部金鑰註冊資料的權限。
400 external_key_provider_error
檢查雲端信任關係、讀取權限、網路存取設定,以及金鑰的啟用狀態與演算法。
400 請求驗證錯誤
檢查用途、指向特定 AWS 金鑰的 ARN,以及 Azure、GCP 或 OCI 的確切金鑰版本。
OCI 金鑰驗證失敗
檢查金鑰上的 openai_organization_id 標記。確認金鑰為 3072 位元的 RSA 金鑰、已啟用且屬於指定的保存庫,並確認已授予 OpenAI 讀取該保存庫和金鑰的權限。
404
檢查註冊 ID 和組織。無法使用已刪除或屬於其他組織的註冊資料。
external_key_used_by_active_projects
在所有使用中的專案內清除金鑰選擇或改選其他金鑰。
金鑰不再相符
註冊替代金鑰,並選取其新的註冊 ID。
聯絡支援團隊時,請提供錯誤訊息和 x-request-id。切勿提供驗證憑證。