---
title: 為 CMEK 設定 Google Cloud KMS
url: https://platform.claude.com/docs/zh-TW/manage-claude/cmek-google-cloud-kms
description: 使用 Google Cloud KMS 為您的組織提供加密金鑰。
---

讓 Claude Code 為您設定此功能

```text
/claude-api 協助我使用 Google Cloud KMS 設定客戶管理的加密金鑰
```

本指南將逐步說明如何將 Google Cloud KMS 金鑰設定為您 Anthropic 組織的[客戶管理加密金鑰（customer-managed encryption key，CMEK）](https://platform.claude.com/docs/zh-TW/manage-claude/cmek)。

<Warning>
  啟用 CMEK 是永久性的。如果您的 KMS 金鑰被刪除或停用，Anthropic 將無法復原使用該金鑰加密的資料。在開始之前，請先檢閱[警告與限制](https://platform.claude.com/docs/zh-TW/manage-claude/cmek)。
</Warning>

## 先決條件

* 已啟用計費的 Google Cloud 專案。
* 已啟用 Cloud KMS API（`cloudkms.googleapis.com`）。
* 建立 KMS 金鑰環和金鑰，以及在其上設定 IAM 政策的權限（`roles/cloudkms.admin` 或同等權限）。
* 您組織的 Anthropic Admin API 金鑰。
* 已安裝並通過驗證的 [`gcloud` CLI](https://cloud.google.com/cli)。
* 為專案啟用 Cloud KMS **資料存取稽核日誌**（IAM & Admin > Audit Logs > Cloud Key Management Service，並啟用 `DATA_READ` 和 `DATA_WRITE`）。這些預設為關閉；若未啟用，Anthropic 的加密和解密操作不會在 Cloud Logging 中產生任何記錄。

## Anthropic 服務帳戶電子郵件

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

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

<Warning>
  僅使用此已公布的服務帳戶電子郵件。切勿信任透過電子郵件、聊天或任何入門管道提供的識別碼。
</Warning>

<Note>
  **網域限制共用：** 如果您的專案位於強制執行 `constraints/iam.allowedPolicyMemberDomains` 的 Google Cloud 組織之下，以下 IAM 繫結將被拒絕，因為 Anthropic 服務帳戶位於您的組織之外。您需要在該限制上設定專案層級的例外，或將 Anthropic 的 Cloud Identity 客戶 ID（格式為 `C0xxxxxxxx`）加入允許清單。如有需要，請聯絡 Anthropic 取得客戶 ID。
</Note>

## 加密金鑰設定

<Steps>
  <Step title="建立或選擇金鑰環">
    如果您已有可重複使用的金鑰環，請跳過此步驟。金鑰環是區域性的。選擇一個與您正在設定的 Anthropic 地理位置相符的單一區域美國位置，例如 `us-east5`。不支援 `us` 和 `global` 等多區域位置。

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

  <Step title="建立加密金鑰">
    建立一個具有 `ENCRYPT_DECRYPT` 用途的對稱金鑰。Anthropic 強烈建議使用 HSM 保護：Cloud KMS HSM 金鑰通過 FIPS 140-2 Level 3 驗證，且相較於軟體金鑰的成本差異很小。

    `--labels` 選項會新增組織標籤 `anthropic-org-<ORGANIZATION_UUID>`，其值為 `true`，其中 `<ORGANIZATION_UUID>` 是您小寫的 Anthropic 組織 ID。此標籤是 Anthropic 驗證金鑰所必需的。

    <Note>
      **尋找您的組織 ID：** 在 Claude Console 的 [Organization](https://platform.claude.com/settings/organization) 頁面（`platform.claude.com/settings/organization`）複製 **Organization ID** 欄位，或在 claude.ai 的 **Organization settings > Organization** 下複製，或從 [Organization Info](https://platform.claude.com/docs/zh-TW/api/organization/retrieve) 端點讀取 `id` 欄位。請使用純 UUID，而非帶有 `org_` 前綴的 ID。
    </Note>

    ```bash
    gcloud kms keys create <KEY_NAME> \
      --project=<PROJECT_ID> \
      --location=<REGION> \
      --keyring=<KEYRING_NAME> \
      --purpose=encryption \
      --protection-level=hsm \
      --labels=anthropic-org-<ORGANIZATION_UUID>=true
    ```

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

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

    <Frame caption="建立一個帶有組織標籤、受 HSM 保護的對稱加密/解密金鑰。">
      ![Google Cloud KMS 的 Create key 頁面，已選擇 HSM 保護與對稱加密/解密，且 anthropic-org 標籤設為 true。](https://platform.claude.com/docs/images/cmek/gcp-create-key-label.png)
    </Frame>

    若要在多個 Anthropic 組織之間共用一個金鑰，請為每個組織新增一個這樣的標籤。一個金鑰最多可攜帶 64 個標籤，包括您自己的標籤。

    <Note>
      若要為尚未擁有此標籤的金鑰新增標籤，請執行 `gcloud kms keys update <KEY_NAME> --project=<PROJECT_ID> --location=<REGION> --keyring=<KEYRING_NAME> --update-labels=anthropic-org-<ORGANIZATION_UUID>=true`。它會將標籤與金鑰已有的任何標籤合併。
    </Note>
  </Step>

  <Step title="授予 Anthropic 服務帳戶存取金鑰的權限">
    需要兩個金鑰層級的 IAM 繫結。兩者都限定於單一加密金鑰，而非整個專案或整個金鑰環。

    加密和解密，Anthropic 用於加密和解密保護您工作區資料的資料金鑰（信封加密）：

    ```bash
    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
    ```

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

    ```bash
    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 兩個角色。請確保您位於金鑰的權限頁面，而非金鑰環或專案，以便授權僅限定於此金鑰。

    <Frame caption="為 Anthropic 服務帳戶授予兩個角色，限定於該金鑰。">
      ![Grant access 對話方塊，其中 Anthropic 服務帳戶已被指派 Cloud KMS CryptoKey Encrypter/Decrypter 和 Cloud KMS Viewer 角色。](https://platform.claude.com/docs/images/cmek/gcp-grant-access.png)
    </Frame>
  </Step>

  <Step title="記下完整的金鑰資源名稱">
    當您註冊金鑰時，需要將此名稱傳遞給 Anthropic。格式為：

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

    使用以下指令擷取：

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

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

    <Frame caption="從動作選單複製金鑰的完整資源名稱。">
      ![Google Cloud 金鑰環詳細資料，金鑰的動作選單中醒目標示了 Copy resource name 動作。](https://platform.claude.com/docs/images/cmek/gcp-copy-resource-name.png)
    </Frame>
  </Step>
</Steps>

## 向 Anthropic 註冊金鑰

您如何註冊金鑰取決於您使用的產品。

<Tabs>
  <Tab title="Claude Platform">
    您可以在 Claude Console 中或透過 Admin API 設定金鑰，結果相同。

    <Tabs>
      <Tab title="Claude Console">
        <Steps>
          <Step title="向 Anthropic 註冊金鑰">
            在 Claude Console 中，前往 [Data retention](https://platform.claude.com/settings/privacy#encryption-keys) 頁面（`platform.claude.com/settings/privacy`）。如果您沒有看到 **Encryption keys**，請從頁面頂端的下拉選單中選擇 **Organization**。在 **Encryption keys** 下，點擊 **Add key**。輸入顯示名稱，選擇 **Google Cloud KMS**，然後點擊 **Continue**。將完整的金鑰資源名稱貼到 **Key resource name** 中，然後點擊 **Add**。

            金鑰詳細資料步驟會顯示組織標籤。在點擊 **Add** 之前，請依照[建立步驟](https://platform.claude.com/docs/zh-TW/manage-claude/cmek-google-cloud-kms#organization-label)所述將其新增至金鑰。
          </Step>

          <Step title="驗證金鑰">
            在 **Encryption keys** 清單中，點擊金鑰旁的 **Verify**。檢查通過時會顯示 **Connected**。如果失敗，會有訊息說明原因。
          </Step>

          <Step title="將金鑰附加到工作區">
            在 Claude Console 中，前往 [Data retention](https://platform.claude.com/settings/privacy) 頁面（`platform.claude.com/settings/privacy`），並從頁面頂端的下拉選單中選擇工作區。在 **Encryption key** 下，選擇金鑰，點擊 **Save** 並確認。附加金鑰後無法復原。對於已在接收請求的工作區，金鑰可能需要[最多一天才會生效](https://platform.claude.com/docs/zh-TW/manage-claude/cmek#how-it-works)。
          </Step>
        </Steps>
      </Tab>

      <Tab title="API">
        <Steps>
          <Step title="向 Anthropic 註冊金鑰">
            透過 Admin API 建立外部金鑰設定，使用加密金鑰設定下「記下完整的金鑰資源名稱」步驟中的資源名稱。

            <CodeGroup>
              ```bash cURL
              curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \
                -H "x-api-key: $ANTHROPIC_API_KEY" \
                -H "anthropic-version: 2023-06-01" \
                -H "content-type: application/json" \
                -d '{
                  "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>"
                  }
                }'
              ```

              ```bash CLI
              ant organization:external-keys create <<'YAML'
              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>"
              YAML
              ```

              ```python Python
              client = anthropic.Anthropic()

              external_key = client.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}")
              ```

              ```typescript TypeScript
              const client = new Anthropic();

              const externalKey = await client.organization.externalKeys.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>"
                }
              });

              console.log(`id: ${externalKey.id}`);
              console.log(`display_name: ${externalKey.display_name}`);
              ```

              ```csharp C#
              using Anthropic.Models.Organization.ExternalKeys;

              AnthropicClient client = new();

              var externalKey = await client.Organization.ExternalKeys.Create(new()
              {
                  DisplayName = "<friendly-name>",
                  Geo = Geo.Us,
                  ProviderConfig = new GcpExternalKeyConfig
                  {
                      KeyName = "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
                  }
              });

              Console.WriteLine($"id: {externalKey.ID}");
              Console.WriteLine($"display_name: {externalKey.DisplayName}");
              ```

              ```go Go
              client := anthropic.NewClient()

              externalKey, err := client.Organization.ExternalKeys.New(context.Background(), anthropic.OrganizationExternalKeyNewParams{
              	DisplayName: anthropic.String("<friendly-name>"),
              	Geo:         anthropic.OrganizationExternalKeyNewParamsGeoUs,
              	ProviderConfig: anthropic.OrganizationExternalKeyNewParamsProviderConfigUnion{
              		OfGCP: &anthropic.GCPExternalKeyConfigParam{
              			KeyName: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",
              		},
              	},
              })
              if err != nil {
              	log.Fatal(err)
              }

              fmt.Printf("id: %s\n", externalKey.ID)
              fmt.Printf("display_name: %s\n", externalKey.DisplayName)
              ```

              ```java Java
              import com.anthropic.models.organization.externalkeys.ExternalKeyCreateParams;

              void main() {
                  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

                  var params = ExternalKeyCreateParams.builder()
                      .displayName("<friendly-name>")
                      .geo(ExternalKeyCreateParams.Geo.US)
                      .gcpProviderConfig("projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>")
                      .build();
                  var externalKey = client.organization().externalKeys().create(params);

                  IO.println("id: " + externalKey.id());
                  IO.println("display_name: " + externalKey.displayName().orElseThrow());
              }
              ```

              ```php PHP
              use Anthropic\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;
              // ...

              $client = new Client();

              $externalKey = $client->organization->externalKeys->create(
                  displayName: '<friendly-name>',
                  geo: Geo::US,
                  providerConfig: [
                      'type' => 'gcp',
                      'keyName' => 'projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>',
                  ],
              );

              echo "id: {$externalKey->id}\n";
              echo "display_name: {$externalKey->displayName}\n";
              ```

              ```ruby Ruby
              client = Anthropic::Client.new

              external_key = client.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>"
                }
              )

              puts "id: #{external_key.id}"
              puts "display_name: #{external_key.display_name}"
              ```
            </CodeGroup>

            回應包含外部金鑰 ID：

            ```json
            {
              "type": "external_key",
              "id": "ekey_<id>",
              "display_name": "<friendly-name>"
            }
            ```
          </Step>

          <Step title="驗證金鑰">
            針對您的金鑰觸發一次加密和解密的往返操作。

            <CodeGroup>
              ```bash cURL
              curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \
                -H "x-api-key: $ANTHROPIC_API_KEY" \
                -H "anthropic-version: 2023-06-01"
              ```

              ```bash CLI
              ant organization:external-keys validate --external-key-id "ekey_<id>"
              ```

              ```python Python
              client = anthropic.Anthropic()

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

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

              ```typescript TypeScript
              const client = new Anthropic();

              const validation = await client.organization.externalKeys.validate("ekey_<id>");

              console.log(`status: ${validation.status}`);
              console.log(`error: ${validation.error}`);
              ```

              ```csharp C#
              AnthropicClient client = new();

              var validation = await client.Organization.ExternalKeys.Validate("ekey_<id>");

              Console.WriteLine($"status: {validation.Status.Raw()}");
              Console.WriteLine($"error: {validation.Error}");
              ```

              ```go Go
              client := anthropic.NewClient()

              validation, err := client.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")
              if err != nil {
              	log.Fatal(err)
              }

              fmt.Printf("status: %s\n", validation.Status)
              fmt.Printf("error: %s\n", validation.Error)
              ```

              ```java Java
              AnthropicClient client = AnthropicOkHttpClient.fromEnv();

              var validation = client.organization().externalKeys().validate("ekey_<id>");

              IO.println("status: " + validation.status().asString());
              IO.println("error: " + validation.error().orElse(""));
              ```

              ```php PHP
              $client = new Client();

              $validation = $client->organization->externalKeys->validate(
                  externalKeyID: 'ekey_<id>',
              );

              echo "status: {$validation->status}\n";
              echo "error: {$validation->error}\n";
              ```

              ```ruby Ruby
              client = Anthropic::Client.new

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

              puts "status: #{validation.status}"
              puts "error: #{validation.error}"
              ```
            </CodeGroup>

            成功的回應如下所示：

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

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

            * **VPC Service Controls：** 如果服務範圍保護您專案中的 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>` 確認繫結存在。
            * **已停用或已銷毀的金鑰版本：** 確認金鑰的主要版本已啟用，且未被停用、排定銷毀或已銷毀。
          </Step>

          <Step title="將金鑰附加到工作區">
            金鑰驗證通過後，在您向該工作區傳送任何請求之前，將其附加到新工作區。對於已接收請求的工作區，金鑰可能需要[最多一天才能生效](https://platform.claude.com/docs/zh-TW/manage-claude/cmek#how-it-works)。

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

              ```bash CLI
              ant organization:workspaces update \
                --workspace-id "<workspace-id>" \
                --external-key-id "ekey_<id>"
              ```

              ```python Python
              client = anthropic.Anthropic()

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

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

              ```typescript TypeScript
              const client = new Anthropic();

              const workspace = await client.organization.workspaces.update("<workspace-id>", {
                external_key_id: "ekey_<id>"
              });

              console.log(`id: ${workspace.id}`);
              console.log(`external_key_id: ${workspace.external_key_id}`);
              ```

              ```csharp C#
              AnthropicClient client = new();

              var workspace = await client.Organization.Workspaces.Update("<workspace-id>", new()
              {
                  ExternalKeyID = "ekey_<id>"
              });

              Console.WriteLine($"id: {workspace.ID}");
              Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");
              ```

              ```go Go
              client := anthropic.NewClient()

              workspace, err := client.Organization.Workspaces.Update(
              	context.Background(),
              	"<workspace-id>",
              	anthropic.OrganizationWorkspaceUpdateParams{
              		ExternalKeyID: anthropic.String("ekey_<id>"),
              	},
              )
              if err != nil {
              	log.Fatal(err)
              }

              fmt.Printf("id: %s\n", workspace.ID)
              fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)
              ```

              ```java Java
              import com.anthropic.models.organization.workspaces.WorkspaceUpdateParams;

              void main() {
                  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

                  var params = WorkspaceUpdateParams.builder()
                      .externalKeyId("ekey_<id>")
                      .build();
                  var workspace = client.organization().workspaces().update("<workspace-id>", params);

                  IO.println("id: " + workspace.id());
                  IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());
              }
              ```

              ```php PHP
              $client = new Client();

              $workspace = $client->organization->workspaces->update(
                  workspaceID: '<workspace-id>',
                  externalKeyID: 'ekey_<id>',
              );

              echo "id: {$workspace->id}\n";
              echo "external_key_id: {$workspace->externalKeyID}\n";
              ```

              ```ruby Ruby
              client = Anthropic::Client.new

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

              puts "id: #{workspace.id}"
              puts "external_key_id: #{workspace.external_key_id}"
              ```
            </CodeGroup>
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Claude Enterprise">
    在 [claude.ai > Organization settings > Data and privacy](https://claude.ai/admin-settings/data-privacy-controls) 中，開啟 **Encryption keys**，然後點擊 **Add key**。選擇 **Google Cloud**，貼上上一步驟中的完整金鑰資源名稱，然後點擊 **Continue**。Anthropic 會透過加密和解密的往返操作驗證金鑰。一旦顯示為已驗證，您的組織從該時間點起即受 CMEK 保護。

    在 Claude Enterprise 上，CMEK 適用於整個組織，因此沒有單獨的工作區附加步驟，且一個組織只能有一個金鑰。
  </Tab>
</Tabs>

## Terraform

對於基礎設施即程式碼（infrastructure-as-code）部署，相同的步驟對應到 `google` 提供者的 `google_kms_key_ring`、`google_kms_crypto_key` 和 `google_kms_crypto_key_iam_member` 資源。