将云服务商提供的 RSA-3072 非对称密钥对注册到 OpenAI。
您的私钥始终保存在 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
指定您自己的密钥管理员,完成密钥创建。保持密钥启用,并复制其完整 ARN。该 ARN 以 key/<CUSTOMER_KMS_KEY_ID> 结尾。请勿使用别名 ARN。
打开 IAM > 策略 > 创建策略 > JSON 。替换 <CUSTOMER_KMS_KEY_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。注册密钥时,将同一组织 ID 填入 external_id。
确认密钥策略已向该角色授权。如果密钥策略未将授权委托给 IAM,请添加以下语句。替换 <CUSTOMER_ROLE_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 基于角色的访问控制 。
您的管理员需要拥有允许创建密钥的角色,例如此保管库的密钥保管库加密主管 。请勿将该角色授予 OpenAI。
在保管库中,打开 对象 > 密钥 > 生成/导入 ,并使用以下设置:
名称: <OPENAI_ORG_ID>--asymmetric-key,其中的组织 ID 请填写您的 OpenAI 组织 ID
密钥类型: RSA
RSA 密钥大小: 3072
已启用: 是
如果设置了激活日期或到期日期,请确保密钥当前有效。在密钥允许的操作中勾选解密 。仅向 OpenAI 授予密钥读取权限。
也支持密钥保管库中的 RSA-HSM 密钥。不支持独立的托管 HSM 端点。
创建一个自定义角色,其 DataAction 允许读取密钥。将以下内容保存为 public-key-reader.json,并替换其中的订阅 ID 和资源组名称。
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 和安全令牌服务。如果这是两个不同的项目,请在两个项目中都启用 Cloud KMS。
记录用于身份联合的项目的 12 位项目编号。KMS 可以位于另一个项目中。
打开 安全 > 密钥管理 。创建密钥环,然后使用以下设置创建密钥:
保护级别: 软件
用途: 非对称解密
算法: 3072 位 RSA,使用 OAEP 填充和 SHA256 摘要
复制 KMS 项目 ID、位置、密钥环名称、密钥名称和已启用的版本号。请使用具体版本号,例如 "1",不要使用 "latest" 或 "0"。非对称密钥没有主要版本。
打开 IAM 和管理 > 工作负载身份联合 。创建一个全局池(例如 openai-keys)和一个 OIDC 提供方(例如 openai-google),并使用以下设置:
提供方设置
值
颁发者网址
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,请为 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
注册时,系统会先验证密钥,再保存注册信息。注册成功后,API 会返回 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 列出用于 PSP 解密的非对称密钥注册记录。省略此筛选条件会返回所有用途的注册记录。使用 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 "
删除成功后,API 会返回 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 密钥、已启用且属于指定保管库,并核实读取权限的授权范围是否限定为该保管库和该密钥。
404
检查注册 ID 和组织。已删除的注册记录和其他组织的注册记录均无法使用。
external_key_used_by_active_projects
在所有使用该密钥的活跃项目中清除密钥选择或选择其他密钥。
密钥不再匹配
注册新密钥或新版本,并选择其新的注册 ID。
联系支持团队时,请提供错误信息和 x-request-id。切勿分享凭据。