Claude Platform Docs
管理加密金鑰

為 CMEK 設定 Google Cloud KMS

使用 Google Cloud KMS 為您的組織提供加密金鑰。

Configure with the /claude-api skill in Claude Code
claude "/claude-api help me configure a customer-managed encryption key with Google Cloud KMS"

本指南將逐步說明如何將 Google Cloud KMS 金鑰設定為您 Anthropic 組織的「customer-managed encryption key」（客戶管理的加密金鑰），即 CMEK。

先決條件

  • 已啟用計費的 Google Cloud 專案。
  • 已啟用 Cloud KMS API（cloudkms.googleapis.com）。
  • 具備建立 KMS 金鑰環與金鑰，以及在其上設定 IAM 政策的權限（roles/cloudkms.admin 或同等權限）。
  • 您組織的 Anthropic Admin API 金鑰。
  • 已安裝並完成驗證的 gcloud CLI。
  • 已為專案啟用 Cloud KMS 資料存取稽核日誌（Data Access audit logs）（IAM & Admin > Audit Logs > Cloud Key Management Service，並勾選 DATA_READ 與 DATA_WRITE）。這些日誌預設為關閉；若未啟用，Anthropic 的加密與解密作業將不會在 Cloud Logging 中產生任何項目。

Anthropic 服務帳戶電子郵件

若要讓 Anthropic 使用您的加密金鑰，您必須提供 Anthropic 的服務帳戶一把可用於加密資料的金鑰。Anthropic CMEK 的服務帳戶電子郵件為：

anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com

加密金鑰設定

  1. 建立或選擇金鑰環

    如果您已有可重複使用的金鑰環，請略過此步驟。金鑰環具有區域性。請選擇與您所設定的 Anthropic 地理區域相符的單一區域美國位置，例如 us-east5。不支援 us 與 global 等多區域位置。

    gcloud kms keyrings create <your-keyring-name> \
  --project=<your-project-id> \
  --location=<region>

  2. 建立加密金鑰

    建立一把用途為 ENCRYPT_DECRYPT 的對稱金鑰。Anthropic 強烈建議使用 HSM 保護：Cloud KMS HSM 金鑰已通過 FIPS 140-2 Level 3 驗證，且相較於軟體金鑰的成本差異很小。

    gcloud kms keys create <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --purpose=encryption \
  --protection-level=hsm

    若要改用軟體保護，請省略 --protection-level=hsm。本指南的其他內容皆不變。

    您也可以從 Google Cloud Console 建立金鑰。開啟金鑰環，點擊 Create key，選擇 Generated key，將用途與演算法設定為對稱加密與解密，並在保護層級下選擇 HSM。

    Google Cloud KMS 的 Create key 頁面，顯示 HSM 保護層級與 Symmetric encrypt/decrypt 用途。
    建立一把受 HSM 保護的對稱加密／解密（Symmetric encrypt/decrypt）金鑰。

  3. 授予 Anthropic 的服務帳戶存取金鑰的權限

    需要兩個金鑰層級的 IAM 繫結。兩者的範圍皆限定於單一加密金鑰，而非整個專案或整個金鑰環。

    加密與解密權限，Anthropic 用於加密與解密保護您工作區資料的資料金鑰（信封加密，envelope encryption）：

    gcloud kms keys add-iam-policy-binding <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \
  --role=roles/cloudkms.cryptoKeyEncrypterDecrypter

    檢視者（Viewer）權限，用於 Anthropic 在啟動時執行的中繼資料讀取（cryptoKeys.get），以驗證金鑰的用途與演算法：

    gcloud kms keys add-iam-policy-binding <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \
  --role=roles/cloudkms.viewer

    在 Console 中，選取該金鑰，開啟 Permissions 面板，點擊 Grant access，然後新增服務帳戶並同時授予 Cloud KMS CryptoKey Encrypter/Decrypter 與 Cloud KMS Viewer 角色。請確認您位於金鑰的權限頁面，而非金鑰環或專案的權限頁面，以確保授權範圍僅限於此金鑰。

    Grant access 對話方塊，其中 Anthropic 服務帳戶已被指派 Cloud KMS CryptoKey Encrypter/Decrypter 與 Viewer 角色。
    授予 Anthropic 服務帳戶兩個角色（Cloud KMS CryptoKey Encrypter/Decrypter 與 Viewer），範圍限定於該金鑰。

  4. 記下完整的金鑰資源名稱

    您在向 Anthropic 註冊金鑰時需要傳入此名稱。格式為：

    projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>

    使用以下指令取得：

    gcloud kms keys describe <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --format="value(name)"

    在 Console 中，開啟金鑰的詳細資料頁面並點擊 Copy resource name。

    Google Cloud 金鑰環詳細資料，金鑰動作選單中的 Copy resource name 動作已反白標示。
    從動作選單複製金鑰的完整資源名稱（Copy resource name）。

向 Anthropic 註冊金鑰

註冊金鑰的方式取決於您使用的產品。

  1. 向 Anthropic 註冊金鑰

    透過 Admin API 建立外部金鑰設定，使用「加密金鑰設定」下「記下完整的金鑰資源名稱」步驟中取得的資源名稱。

    client = anthropic.Anthropic()

external_key = client.beta.organization.external_keys.create(
    display_name="<friendly-name>",
    geo="us",
    provider_config={
        "type": "gcp",
        "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",
    },
)

print(f"id: {external_key.id}")
print(f"display_name: {external_key.display_name}")

    回應中包含外部金鑰 ID：

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

  2. 驗證金鑰

    對您的金鑰觸發一次加密與解密的往返測試。

    client = anthropic.Anthropic()

validation = client.beta.organization.external_keys.validate("ekey_<id>")

print(f"status: {validation.status}")
print(f"error: {validation.error}")

    成功的回應如下所示：

    { "type": "external_key_validation", "status": "success", "error": null }

    如果驗證失敗，常見原因包括：

    • VPC Service Controls： 如果您的專案中有服務範圍（service perimeter）保護 Cloud KMS，請將 Anthropic 加入該範圍的存取層級（或排除金鑰所在的專案），讓 Anthropic 能夠存取該金鑰。
    • 網域限制共用： constraints/iam.allowedPolicyMemberDomains 組織政策可能會移除 Anthropic 服務帳戶的繫結（請參閱前述說明）。請使用 gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name> 確認繫結是否存在。
    • 已停用或已銷毀的金鑰版本： 請確認金鑰的主要版本已啟用，且未被停用、排定銷毀或已銷毀。

  3. 將金鑰附加至工作區

    金鑰驗證完成後，請在向新工作區傳送任何請求之前，先將金鑰附加至該工作區。對於已在接收請求的工作區，金鑰可能需要最多一天才會生效。

    client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.update(
    "<workspace-id>", external_key_id="ekey_<id>"
)

print(f"id: {workspace.id}")
print(f"external_key_id: {workspace.external_key_id}")

Terraform

對於基礎架構即程式碼（infrastructure-as-code）的部署，相同的步驟可對應至 google provider 的 google_kms_key_ring、google_kms_crypto_key 與 google_kms_crypto_key_iam_member 資源。

Was this page helpful?