OpenAI 配置非对称密钥

2026-11-20 11:20 更新

将云服务商托管的 RSA-3072 非对称密钥对注册到 OpenAI,可用于私有安全处理(PSP)记录的恢复。私钥留在 AWS KMS、Azure Key Vault、Google Cloud KMS 或 OCI Vault,OpenAI 注册时仅保存公钥副本。注册密钥本身不会启用 PSP,也不会配置存储。

开始前

  • 准备 OpenAI 组织 ID。云端信任、密钥注册和 API 访问须使用同一组织。
  • 创建具备外部密钥读写权限的组织管理员 API 密钥,将其安全载入 OPENAI_ADMIN_KEY。项目推理密钥不适用于这里的管理请求。
  • 确认你有权创建处于启用状态的 RSA-3072 密钥,并授予下文所需的限定范围公钥读取权限。
  • 私钥操作仅授予获授权的主体。旧记录仍依赖的密钥版本应继续保留。

配置云端密钥

按服务商完成下列配置,再注册密钥。四种方式都使用 RSA-3072。授予 OpenAI 的权限限于公钥和所需的元数据读取。

AWS KMS

1. 创建 RSA 密钥

在 KMS → Customer managed keys → Create key 中选择区域。将类型设为 Asymmetric,用途设为 Encrypt and decrypt,规格设为 RSA_3072。指定自己的密钥管理员,保持密钥启用。复制以 key/<CUSTOMER_KMS_KEY_ID> 结尾的完整密钥 ARN。

2. 创建公钥读取策略

在 IAM → Policies → Create policy → JSON 中,将 <CUSTOMER_KMS_KEY_ARN> 换成上一步的 ARN,并将策略保存为 OpenAI-PublicKeyRead。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["kms:DescribeKey", "kms:GetPublicKey"],
      "Resource": "<CUSTOMER_KMS_KEY_ARN>"
    }
  ]
}

OpenAI 只需要这两项读取权限。密钥用户和密钥管理员权限由你的组织另行管理。

3. 创建受信任的 IAM 角色

在 IAM → Roles → Create role → Custom trust policy 中,填写你的 OpenAI 组织 ID。示例中的 OpenAI 主体使用固定值。

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

4. 核对 KMS 密钥策略

确认密钥策略授权该角色。如果密钥策略没有将授权委托给 IAM,请加入下面的语句并保留现有管理员权限。在密钥策略里,"Resource": "*" 仅指附加此策略的这把密钥。前面的 IAM 策略仍使用实际密钥 ARN。

{
  "Sid": "AllowPublicKeyRead",
  "Effect": "Allow",
  "Principal": {
    "AWS": "<CUSTOMER_ROLE_ARN>"
  },
  "Action": ["kms:DescribeKey", "kms:GetPublicKey"],
  "Resource": "*"
}

保留角色 ARN 和密钥 ARN,供注册使用。

Azure Key Vault

1. 添加 OpenAI 企业应用

让租户管理员将 EKM - OpenAI Azure 加入租户。其应用 ID 为 20a14814-5ab7-4612-a671-1382b412bf93。安装 Azure CLI,登录并查询此应用。

## 登录 Azure,并按应用 ID 查询本租户内的服务主体。
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,供后续分配角色使用。

2. 创建密钥

在 Key vaults → Create 中选择订阅、资源组、名称和区域。在 Access configuration 中选择 Azure role-based access control。你方管理员需有权创建密钥,例如该保管库的 Key Vault Crypto Officer。OpenAI 只需后文的密钥读取权限。

在保管库的 Objects → Keys → Generate/Import 中创建密钥。命名为 <OPENAI_ORG_ID>--asymmetric-key,类型选 RSA,长度选 3072 位,状态选 Enabled。若设置起止日期,确认密钥当前有效。允许的操作需包含 Decrypt,实际解密权限由你管理。Key Vault 中的 RSA-HSM 密钥也可用。独立 Managed HSM 端点不在支持范围内。

3. 授予密钥读取权限

创建仅含读取密钥所需 DataAction 的自定义角色。替换订阅和资源组后,将以下内容保存为 public-key-reader.json。

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

从 Properties 取得保管库的 Azure 资源 ID,用于 VAULT_RESOURCE_ID。将企业应用在本租户内的对象 ID 用于 OPENAI_SP_ID。把角色分配限定在指定密钥。

## 创建自定义读取角色,将其分配范围限定在指定密钥。
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"

保管库采用旧版访问策略时,沿用其权限模型并授予密钥 Get。

4. 记录确切版本

保存租户 ID、保管库 URI 和密钥名称。从已启用版本的 Key Identifier 末尾复制 由 32 个十六进制字符组成的版本标识。

Google Cloud KMS

1. 准备项目和密钥

在密钥项目启用 Cloud KMS,在身份联合项目启用 IAM 和 Security Token Service。两者属于不同项目时,两边都要启用 Cloud KMS。保存身份联合项目的 12 位项目编号。

在 Security → Key Management 创建密钥环。创建软件保护级别、用途为 Asymmetric decrypt 的密钥,算法选择 3072 bit RSA - OAEP Padding - SHA256 Digest。保留 KMS 项目 ID、位置、密钥环、密钥名和启用的具体版本(例如 "1")。非对称密钥没有主版本,不能使用 "latest" 或 "0"。

2. 配置工作负载身份联合

在 IAM & Admin → Workload Identity Federation 创建全局池和 OIDC 提供方,例如 openai-keys 和 openai-google。

提供方设置 值
签发方 URL https://accounts.google.com
允许的受众 你的 OpenAI 组织 ID,须完全一致
属性映射 google.subject = assertion.sub
属性条件 assertion.sub == '105900137572174660365'

签发方和 OpenAI 主体使用表中固定值。

3. 创建并分配密钥读取角色

在 KMS 项目的 IAM & Admin → Roles 中创建自定义角色,包含以下两项权限。

cloudkms.cryptoKeyVersions.get
cloudkms.cryptoKeyVersions.viewPublicKey

仅授予公钥查看权限不足。这里无需解密、签名或模拟服务账户权限。进入密钥的 Permissions → Grant access,对以下主体授予角色,并替换其中的项目编号和池 ID。

principal://iam.googleapis.com/projects/<CUSTOMER_GCP_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<CUSTOMER_GCP_POOL_ID>/subject/105900137572174660365

使用池所在项目的编号,把权限限定在这把密钥。密钥级 IAM 覆盖其版本。保留池 ID、提供方 ID、组织受众和 KMS 标识。

OCI Vault

1. 创建保管库和 RSA 密钥

向 OpenAI 联系人确认 OCI 密钥注册及区域可用性。你的租户和 OpenAI 租户都要订阅目标区域。在 OCI 控制台的 Vault 选用一个商业区域内的保管库,例如 us-ashburn-1,等待状态变为 Active。在 Master encryption keys → Create key 创建软件保护的 RSA-3072 密钥并保持启用。若同时使用 EKM,请为 EKM 配置另一把 AES-256 密钥。

OCI 中配置软件保护的 RSA-3072 密钥

2. 为密钥添加组织标签

在密钥本身添加无命名空间的自由格式标签 openai_organization_id,值为含 org- 前缀的 OpenAI 组织 ID。即使保管库或区间已有标签,这一步仍需在密钥上完成。

OCI 密钥的组织 ID 标签配置

3. 授予公钥读取权限

在 Identity & Security → Policies 选择租户根区间。启用 Show manual editor,填写你方保管库和密钥的 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 用于查找保管库端点。KEY_READ 用于读取指定版本的元数据和公钥。这些授权不包含解密、导出或管理密钥。即使已为 PSP 单独配置 OCI Object Storage 策略,也要使用这里的密钥管理身份。

4. 记录确切版本

记录区域标识、保管库 OCID、密钥 OCID,以及要注册的版本 OCID。版本 OCID 以 ocid1.keyversion. 开头。使用完整版本 OCID,避免使用 latest 或版本序号。保管库、密钥和版本须位于同一商业区域,密钥也须属于注册时填写的保管库。

注册密钥

以下示例使用 curl 和 Bash 兼容 Shell。安全载入 OPENAI_ADMIN_KEY 后设置组织 ID。

## 填写组织 ID。管理员密钥由安全的环境配置提供。
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 中的变量名不会自动展开。

AWS KMS 请求体

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

Azure Key Vault 请求体

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

Google Cloud KMS 请求体

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

OCI Vault 请求体

{
  "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. 注册和验证密钥

## 用 registration.json 注册恢复密钥并验证公钥读取权限。
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 及服务商配置。部分响应字段如下。

{
  "id": "extkey_11111111111111111111111111111111",
  "object": "organization.external_key",
  "name": "asymmetric-key-gcp",
  "type": "gcp",
  "purpose": "psp_decryption",
  "api_project_ids": []
}

保存返回的注册 ID。

## 把占位值换成注册响应返回的 extkey ID。
KEY_ID="<EXTERNAL_KEY_ID>"

2. 重新验证密钥(可选)

GET 返回已保存的信息。POST /validate 按保存的公钥重新核对访问权限及密钥有效性。它不解密记录,也不会更新公钥快照。

## 按注册 ID 读取已保存的配置。
curl --fail-with-body -sS "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

## 重新验证当前访问权限和公钥状态。
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 配置生效后再重试。注册完成后仍需在私有安全处理指南所述的项目设置中选择恢复密钥。

列出密钥

传入 purpose=psp_decryption 仅列出恢复密钥。省略筛选时返回所有用途,purpose=ekm 只返回 EKM 注册。

## 按用途列出 PSP 恢复密钥,使用游标继续翻页。
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 时,将 last_id 作为下一页的 after,并保持 purpose、order 和 limit 一致。

更换密钥

  1. 创建替代 AWS 密钥,或创建 Azure、Google Cloud、OCI 的新密钥版本,并配置所需的读取权限。
  2. 注册新密钥,保存新的 extkey ID。
  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"。此操作只删除 OpenAI 的注册,云端密钥继续保留。

排查问题

结果 核对内容
401 或 403 确认使用组织管理员 API 密钥,且有外部密钥注册权限。
400 external_key_provider_error 检查云端信任、读取权限、网络、密钥启用状态和算法。
400 请求字段校验失败 检查用途、AWS 密钥 ARN 及 Azure、Google Cloud、OCI 的确切版本。
OCI 密钥验证失败 检查组织标签、RSA-3072 规格、启用状态、保管库归属及限定范围的保管库和密钥读取授权。
404 检查注册 ID 和组织。找不到已删除或属于其他组织的注册。
external_key_used_by_active_projects 清除或替换各活动项目中的选择。
密钥与快照不匹配 重新注册替代密钥并选择它的新 ID。

联系支持时,提供错误信息和 x-request-id。请勿提供凭据。

相关指南

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号