管理加密密钥

为 CMEK 配置 Azure Key Vault

使用 Azure Key Vault 为您的组织提供加密密钥。

Configure with the /claude-api skill in Claude Code

claude "/claude-api help me configure a customer-managed encryption key with Azure Key Vault"

本指南将引导您配置 Azure Key Vault 密钥，作为您的 Anthropic 组织的 customer-managed encryption key（客户管理的加密密钥，CMEK）。

启用 CMEK 是永久性操作。如果您的 Key Vault 密钥被删除或禁用，Anthropic 将无法恢复使用该密钥加密的数据。在开始之前，请查阅警告和限制。

前提条件

一个 Azure Key Vault，且已启用 RBAC 授权（enableRbacAuthorization: true）并允许公共网络访问。Anthropic 通过公共数据平面端点调用您的保管库；不支持私有端点。
保管库上已启用清除保护（enablePurgeProtection: true）。如果未启用，已删除的密钥可能在软删除保留期内被永久清除，导致受 CMEK 保护的数据不可逆转地丢失。清除保护一旦启用便无法禁用。
在保管库中创建密钥以及在其上分配 RBAC 角色的权限。
在您的 Entra 租户中创建服务主体的权限（Application Administrator、Cloud Application Administrator 或等效的自定义角色）。
您组织的 Anthropic Admin API 密钥。
已安装并完成身份验证的 az CLI。
已在保管库上配置诊断设置，将 AuditEvent 日志类别路由到 Log Analytics、存储帐户或事件中心。Azure Key Vault 默认不会发出数据平面审计日志（例如 KeyWrap、KeyUnwrap 和 KeyGet），因此如果没有此配置，您将无法获得 Anthropic 密钥操作的审计跟踪。

Anthropic 应用信息

为了让 Anthropic 使用您的加密密钥，您必须配置 Anthropic 多租户应用程序 ID 和显示名称。这些值如下：

字段	值
多租户应用客户端 ID（美国）	`8635ae1a-3e5d-44e8-a4ed-e0f614466f87`
应用显示名称	`anthropic-cmek-client-us`

请仅使用此处发布的客户端 ID 和显示名称。切勿信任通过电子邮件、聊天或任何入门引导渠道提供的标识符。

加密密钥设置

同意 Anthropic 多租户应用程序
此操作会在您的 Entra 租户中为 Anthropic 的 CMEK 客户端应用程序创建一个服务主体。该应用程序不请求任何 Microsoft Graph 权限；它仅作为 Key Vault 数据平面访问的联合身份验证目标而存在。
az ad sp create --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87
从输出中获取 id 字段。这是该服务主体在您租户中的对象 ID，您将在分配 RBAC 角色时使用它。
{ "appId": "8635ae1a-3e5d-44e8-a4ed-e0f614466f87", "displayName": "anthropic-cmek-client-us", "id": "<sp-object-id>" }
如果该服务主体已存在于您的租户中（来自之前的尝试或其他集成），az ad sp create 会退出并显示"already exists"（已存在）错误。此时请改为获取其对象 ID：
az ad sp show --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87 --query id -o tsv
此步骤没有对应的门户操作。如果您本地未安装 Azure CLI，请从门户顶部导航栏打开 Cloud Shell。命令成功执行后，您可以在 Microsoft Entra ID > 企业应用程序 中清除默认的应用程序类型筛选器并搜索 anthropic-cmek-client-us，以找到该服务主体的对象 ID。
在服务主体的 Entra 企业应用程序概述页面上找到其 Object ID（对象 ID）。
在您的保管库中创建 RSA 密钥
Azure Key Vault 不支持对称密钥包装，因此该密钥必须是 RSA（3072 位或更大），且其允许的操作中包含 wrapKey 和 unwrapKey。
az keyvault key create \ --vault-name <your-vault-name> \ --name <your-key-name> \ --kty RSA --size 3072 \ --ops wrapKey unwrapKey
对于 HSM 支持的密钥，请使用 --kty RSA-HSM（需要高级 SKU 保管库）。软件保护的 RSA 密钥也可用于此集成。
在门户中，打开您的 Key Vault，选择密钥，然后选择生成/导入。将密钥类型设置为 RSA，大小设置为 3072 或更大。要将密钥限制为仅包装和解包，请打开密钥版本，滚动到允许的操作，取消选中除 Wrap Key（包装密钥）和 Unwrap Key（解包密钥）之外的所有选项。
创建大小为 3072 或更大的 RSA 密钥。
将允许的操作限制为 Wrap Key（包装密钥）和 Unwrap Key（解包密钥）。
授予 Anthropic 服务主体访问您密钥的权限
将 Key Vault Crypto User 角色分配给第一步中创建的服务主体，作用域限定为单个密钥而非整个保管库。
VAULT_ID=$(az keyvault show --name <your-vault-name> --query id -o tsv) az role assignment create \ --role "Key Vault Crypto User" \ --assignee-object-id <sp-object-id> \ --assignee-principal-type ServicePrincipal \ --scope "${VAULT_ID}/keys/<your-key-name>"
内置的 Key Vault Crypto User 角色在其分配的作用域上授予密钥加密操作（加密、解密、包装、解包、签名、验证）以及密钥读取权限。您在上一步中对密钥设置的 --ops wrapKey unwrapKey 限制进一步缩小了可对此密钥成功执行的操作范围，因此实际上 Anthropic 只能执行包装和解包操作。
在门户中，打开该密钥（而非保管库），选择其访问控制 (IAM) 选项卡，单击添加 > 添加角色分配，选择 Key Vault Crypto User，并将其分配给 anthropic-cmek-client-us 服务主体。
专用保管库替代方案： Microsoft 建议为每个应用程序使用专用保管库，并在保管库作用域分配角色。如果您预配的保管库仅包含此 Anthropic CMEK 密钥，则可以改为在保管库作用域分配角色，效果完全相同。当密钥位于共享保管库中时，请将作用域限定为单个密钥。
将 Key Vault Crypto User 分配给 Anthropic 服务主体，作用域限定为该密钥。
验证您的保管库配置
az keyvault show --name <your-vault-name> \ --query "{rbac:properties.enableRbacAuthorization, purge:properties.enablePurgeProtection, pub:properties.publicNetworkAccess, net:properties.networkAcls.defaultAction, ipRules:properties.networkAcls.ipRules, uri:properties.vaultUri, tenantId:properties.tenantId}"
确认以下内容：
- rbac 为 true。
- purge 为 true。如果为 false 或 null，请在继续之前在保管库上启用清除保护。如果未启用，软删除的密钥可能在保留期内被永久清除，导致受 CMEK 保护的数据无法恢复。
- pub 为 "Enabled"。如果为 "Disabled"，Anthropic 将无法通过其公共数据平面端点访问该保管库，验证将失败。
- net 为 "Allow"；或者，如果为 "Deny"，则 ipRules 中包含 Anthropic 的出口 IP 范围（请联系 Anthropic 获取当前列表）。
- uri 是您在注册密钥时使用的保管库 URI。
- tenantId 是管理该保管库的租户。在注册密钥时，请将此值用作 tenant_id，而不是您当前活动订阅的租户（在跨租户设置中，两者可能不同）。

向 Anthropic 注册密钥

通过 Admin API 创建外部密钥配置。

curl -sS https://api.anthropic.com/v1/organizations/external_keys \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "display_name": "<friendly-name>",
    "geo": "us",
    "provider_config": {
      "type": "azure",
      "vault_uri": "https://<your-vault-name>.vault.azure.net/",
      "key_name": "<your-key-name>",
      "tenant_id": "<your-tenant-id>"
    }
  }'

响应中包含外部密钥 ID：

{
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

验证密钥
针对您的密钥触发一次加密和解密往返操作。这可确认 Anthropic 能够对您的租户进行身份验证并执行包装和解包操作。
curl -sS -X POST https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate \ -H "x-api-key: <anthropic-admin-api-key>" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" -d '{}'
成功的响应如下所示：
{ "type": "external_key_validation", "status": "success", "error": null }
如果验证失败，error 字段会描述问题所在。常见原因包括：
- RBAC 传播延迟： 角色分配可能需要几分钟才能生效。请等待后重试。
- 网络 ACL 阻止了 Anthropic： 按照验证步骤中的说明确认公共网络访问和 ipRules。
- 针对工作负载标识的条件访问策略： 如果您的租户有针对服务主体的条件访问策略，请排除 Anthropic 服务主体，或将 Anthropic 的出口 IP 范围添加到该策略的命名位置中。

将密钥附加到工作区

密钥验证通过后，将其附加到工作区，以便为该工作区的数据启用 CMEK。

curl -sS -X POST https://api.anthropic.com/v1/organizations/workspaces/<workspace-id> \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "external_key_id": "ekey_<id>"
  }'

Terraform

对于基础设施即代码部署，相同的步骤可映射到 azurerm 和 azuread 提供程序。

Was this page helpful?

前提条件

一个 Azure Key Vault，且已启用 RBAC 授权（enableRbacAuthorization: true）并允许公共网络访问。Anthropic 通过公共数据平面端点调用您的保管库；不支持私有端点。

保管库上已启用清除保护（enablePurgeProtection: true）。如果未启用，已删除的密钥可能在软删除保留期内被永久清除，导致受 CMEK 保护的数据不可逆转地丢失。清除保护一旦启用便无法禁用。

在保管库中创建密钥以及在其上分配 RBAC 角色的权限。

在您的 Entra 租户中创建服务主体的权限（Application Administrator、Cloud Application Administrator 或等效的自定义角色）。

您组织的 Anthropic Admin API 密钥。

已安装并完成身份验证的 az CLI。

已在保管库上配置诊断设置，将 AuditEvent 日志类别路由到 Log Analytics、存储帐户或事件中心。Azure Key Vault 默认不会发出数据平面审计日志（例如 KeyWrap、KeyUnwrap 和 KeyGet），因此如果没有此配置，您将无法获得 Anthropic 密钥操作的审计跟踪。

Anthropic 应用信息

为了让 Anthropic 使用您的加密密钥，您必须配置 Anthropic 多租户应用程序 ID 和显示名称。这些值如下：

字段	值
多租户应用客户端 ID（美国）	`8635ae1a-3e5d-44e8-a4ed-e0f614466f87`
应用显示名称	`anthropic-cmek-client-us`

请仅使用此处发布的客户端 ID 和显示名称。切勿信任通过电子邮件、聊天或任何入门引导渠道提供的标识符。

加密密钥设置

同意 Anthropic 多租户应用程序
此操作会在您的 Entra 租户中为 Anthropic 的 CMEK 客户端应用程序创建一个服务主体。该应用程序不请求任何 Microsoft Graph 权限；它仅作为 Key Vault 数据平面访问的联合身份验证目标而存在。
az ad sp create --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87
从输出中获取 id 字段。这是该服务主体在您租户中的对象 ID，您将在分配 RBAC 角色时使用它。
{ "appId": "8635ae1a-3e5d-44e8-a4ed-e0f614466f87", "displayName": "anthropic-cmek-client-us", "id": "<sp-object-id>" }
如果该服务主体已存在于您的租户中（来自之前的尝试或其他集成），az ad sp create 会退出并显示"already exists"（已存在）错误。此时请改为获取其对象 ID：
az ad sp show --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87 --query id -o tsv
此步骤没有对应的门户操作。如果您本地未安装 Azure CLI，请从门户顶部导航栏打开 Cloud Shell。命令成功执行后，您可以在 Microsoft Entra ID > 企业应用程序 中清除默认的应用程序类型筛选器并搜索 anthropic-cmek-client-us，以找到该服务主体的对象 ID。
在服务主体的 Entra 企业应用程序概述页面上找到其 Object ID（对象 ID）。
在您的保管库中创建 RSA 密钥
Azure Key Vault 不支持对称密钥包装，因此该密钥必须是 RSA（3072 位或更大），且其允许的操作中包含 wrapKey 和 unwrapKey。
az keyvault key create \ --vault-name <your-vault-name> \ --name <your-key-name> \ --kty RSA --size 3072 \ --ops wrapKey unwrapKey
对于 HSM 支持的密钥，请使用 --kty RSA-HSM（需要高级 SKU 保管库）。软件保护的 RSA 密钥也可用于此集成。
在门户中，打开您的 Key Vault，选择密钥，然后选择生成/导入。将密钥类型设置为 RSA，大小设置为 3072 或更大。要将密钥限制为仅包装和解包，请打开密钥版本，滚动到允许的操作，取消选中除 Wrap Key（包装密钥）和 Unwrap Key（解包密钥）之外的所有选项。
创建大小为 3072 或更大的 RSA 密钥。
将允许的操作限制为 Wrap Key（包装密钥）和 Unwrap Key（解包密钥）。
授予 Anthropic 服务主体访问您密钥的权限
将 Key Vault Crypto User 角色分配给第一步中创建的服务主体，作用域限定为单个密钥而非整个保管库。
VAULT_ID=$(az keyvault show --name <your-vault-name> --query id -o tsv) az role assignment create \ --role "Key Vault Crypto User" \ --assignee-object-id <sp-object-id> \ --assignee-principal-type ServicePrincipal \ --scope "${VAULT_ID}/keys/<your-key-name>"
内置的 Key Vault Crypto User 角色在其分配的作用域上授予密钥加密操作（加密、解密、包装、解包、签名、验证）以及密钥读取权限。您在上一步中对密钥设置的 --ops wrapKey unwrapKey 限制进一步缩小了可对此密钥成功执行的操作范围，因此实际上 Anthropic 只能执行包装和解包操作。
在门户中，打开该密钥（而非保管库），选择其访问控制 (IAM) 选项卡，单击添加 > 添加角色分配，选择 Key Vault Crypto User，并将其分配给 anthropic-cmek-client-us 服务主体。
专用保管库替代方案： Microsoft 建议为每个应用程序使用专用保管库，并在保管库作用域分配角色。如果您预配的保管库仅包含此 Anthropic CMEK 密钥，则可以改为在保管库作用域分配角色，效果完全相同。当密钥位于共享保管库中时，请将作用域限定为单个密钥。
将 Key Vault Crypto User 分配给 Anthropic 服务主体，作用域限定为该密钥。
验证您的保管库配置
az keyvault show --name <your-vault-name> \ --query "{rbac:properties.enableRbacAuthorization, purge:properties.enablePurgeProtection, pub:properties.publicNetworkAccess, net:properties.networkAcls.defaultAction, ipRules:properties.networkAcls.ipRules, uri:properties.vaultUri, tenantId:properties.tenantId}"
确认以下内容：
- rbac 为 true。
- purge 为 true。如果为 false 或 null，请在继续之前在保管库上启用清除保护。如果未启用，软删除的密钥可能在保留期内被永久清除，导致受 CMEK 保护的数据无法恢复。
- pub 为 "Enabled"。如果为 "Disabled"，Anthropic 将无法通过其公共数据平面端点访问该保管库，验证将失败。
- net 为 "Allow"；或者，如果为 "Deny"，则 ipRules 中包含 Anthropic 的出口 IP 范围（请联系 Anthropic 获取当前列表）。
- uri 是您在注册密钥时使用的保管库 URI。
- tenantId 是管理该保管库的租户。在注册密钥时，请将此值用作 tenant_id，而不是您当前活动订阅的租户（在跨租户设置中，两者可能不同）。

向 Anthropic 注册密钥

通过 Admin API 创建外部密钥配置。

curl -sS https://api.anthropic.com/v1/organizations/external_keys \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "display_name": "<friendly-name>",
    "geo": "us",
    "provider_config": {
      "type": "azure",
      "vault_uri": "https://<your-vault-name>.vault.azure.net/",
      "key_name": "<your-key-name>",
      "tenant_id": "<your-tenant-id>"
    }
  }'

响应中包含外部密钥 ID：

{
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

验证密钥
针对您的密钥触发一次加密和解密往返操作。这可确认 Anthropic 能够对您的租户进行身份验证并执行包装和解包操作。
curl -sS -X POST https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate \ -H "x-api-key: <anthropic-admin-api-key>" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" -d '{}'
成功的响应如下所示：
{ "type": "external_key_validation", "status": "success", "error": null }
如果验证失败，error 字段会描述问题所在。常见原因包括：
- RBAC 传播延迟： 角色分配可能需要几分钟才能生效。请等待后重试。
- 网络 ACL 阻止了 Anthropic： 按照验证步骤中的说明确认公共网络访问和 ipRules。
- 针对工作负载标识的条件访问策略： 如果您的租户有针对服务主体的条件访问策略，请排除 Anthropic 服务主体，或将 Anthropic 的出口 IP 范围添加到该策略的命名位置中。

将密钥附加到工作区

密钥验证通过后，将其附加到工作区，以便为该工作区的数据启用 CMEK。

curl -sS -X POST https://api.anthropic.com/v1/organizations/workspaces/<workspace-id> \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "external_key_id": "ekey_<id>"
  }'