SPB Git

Repository Public

cmek-google-cloud-kms.md 23.1 KB 552 lines markdown

1---2title: Configure Google Cloud KMS for CMEK3url: https://platform.claude.com/docs/en/manage-claude/cmek-google-cloud-kms4description: Use Google Cloud KMS to provide an encryption key for your organization.5---67```bash Configure with the /claude-api skill in Claude Code8claude "/claude-api help me configure a customer-managed encryption key with Google Cloud KMS"9```1011This guide walks through configuring a Google Cloud KMS key as a [customer-managed encryption key (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek) for your Anthropic organization.1213<Warning>14  Enabling CMEK is permanent. If your KMS key is deleted or disabled, Anthropic cannot recover the data encrypted under it. Review the [warnings and limitations](https://platform.claude.com/docs/en/manage-claude/cmek) before you begin.15</Warning>1617## Prerequisites1819* A Google Cloud project with billing enabled.20* The Cloud KMS API enabled (`cloudkms.googleapis.com`).21* Permissions to create KMS key rings and keys, and to set IAM policy on them (`roles/cloudkms.admin` or equivalent).22* An Anthropic Admin API key for your organization.23* The [`gcloud` CLI](https://cloud.google.com/cli) installed and authenticated.24* Cloud KMS **Data Access audit logs** enabled for the project (IAM & Admin > Audit Logs > Cloud Key Management Service, with `DATA_READ` and `DATA_WRITE`). These are off by default; without them, Anthropic's encrypt and decrypt operations produce no entries in Cloud Logging.2526## Anthropic service account email2728To have Anthropic use your encryption key, you must give Anthropic's service account a key it can use for encrypting data. The service account email for Anthropic CMEK is:2930```text wrap31anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com32```3334<Warning>35  Use only this published service account email. Never trust an identifier provided over email, chat, or any onboarding channel.36</Warning>3738<Note>39  **Domain restricted sharing:** If your project is under a Google Cloud organization that enforces `constraints/iam.allowedPolicyMemberDomains`, the following IAM bindings are rejected because the Anthropic service account is outside your organization. You need either a project-level carve-out on that constraint, or to add Anthropic's Cloud Identity customer ID (format `C0xxxxxxxx`) to the allowed list. Contact Anthropic for the customer ID if needed.40</Note>4142## Encryption key setup4344<Steps>45  <Step title="Create or choose a key ring">46    Skip this step if you already have a key ring to reuse. Key rings are regional. Choose a single-region US location such as `us-east5` that matches the Anthropic geography you are configuring. Multi-region locations like `us` and `global` are not supported.4748    ```bash49    gcloud kms keyrings create <your-keyring-name> \50      --project=<your-project-id> \51      --location=<region>52    ```53  </Step>5455  <Step title="Create the crypto key">56    Create a symmetric key with the `ENCRYPT_DECRYPT` purpose. Anthropic strongly recommends HSM protection: Cloud KMS HSM keys are FIPS 140-2 Level 3 validated, and the cost delta over software keys is small.5758    ```bash59    gcloud kms keys create <your-key-name> \60      --project=<your-project-id> \61      --location=<region> \62      --keyring=<your-keyring-name> \63      --purpose=encryption \64      --protection-level=hsm65    ```6667    For software protection instead, omit `--protection-level=hsm`. Nothing else in this guide changes.6869    You can also create the key from the Google Cloud Console. Open the key ring, click **Create key**, select **Generated key**, set the purpose and algorithm to symmetric encrypt and decrypt, and choose **HSM** under protection level.7071    <Frame caption="Create an HSM-protected symmetric encrypt/decrypt key.">72      ![Google Cloud KMS Create key page with HSM protection level and a Symmetric encrypt/decrypt purpose.](https://platform.claude.com/docs/images/cmek/gcp-create-key.png)73    </Frame>74  </Step>7576  <Step title="Grant Anthropic's service account access to the key">77    Two key-level IAM bindings are required. Both are scoped to the single crypto key, not project-wide or keyring-wide.7879    Encrypt and decrypt, which Anthropic uses to encrypt and decrypt the data keys that protect your workspace data (envelope encryption):8081    ```bash82    gcloud kms keys add-iam-policy-binding <your-key-name> \83      --project=<your-project-id> \84      --location=<region> \85      --keyring=<your-keyring-name> \86      --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \87      --role=roles/cloudkms.cryptoKeyEncrypterDecrypter88    ```8990    Viewer, for the metadata read (`cryptoKeys.get`) Anthropic performs at startup to validate the key's purpose and algorithm:9192    ```bash93    gcloud kms keys add-iam-policy-binding <your-key-name> \94      --project=<your-project-id> \95      --location=<region> \96      --keyring=<your-keyring-name> \97      --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \98      --role=roles/cloudkms.viewer99    ```100101    From the Console, select the key, open the **Permissions** panel, click **Grant access**, and add the service account with both the Cloud KMS CryptoKey Encrypter/Decrypter and Cloud KMS Viewer roles. Make sure you are on the key's permissions page, not the key ring or project, so the grant is scoped to this key only.102103    <Frame caption="Grant the Anthropic service account both roles, scoped to the key.">104      ![Grant access dialog with the Anthropic service account assigned Cloud KMS CryptoKey Encrypter/Decrypter and Viewer roles.](https://platform.claude.com/docs/images/cmek/gcp-grant-access.png)105    </Frame>106  </Step>107108  <Step title="Note the full key resource name">109    You pass this to Anthropic when you register the key. The format is:110111    ```text wrap112    projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>113    ```114115    Retrieve it with:116117    ```bash118    gcloud kms keys describe <your-key-name> \119      --project=<your-project-id> \120      --location=<region> \121      --keyring=<your-keyring-name> \122      --format="value(name)"123    ```124125    From the Console, open the key's details page and click **Copy resource name**.126127    <Frame caption="Copy the key's full resource name from the actions menu.">128      ![Google Cloud key ring details with the Copy resource name action highlighted in the key's actions menu.](https://platform.claude.com/docs/images/cmek/gcp-copy-resource-name.png)129    </Frame>130  </Step>131</Steps>132133## Register the key with Anthropic134135How you register the key depends on which product you use.136137<Tabs>138  <Tab title="Claude Platform">139    You can set up the key in the Claude Console or through the Admin API, with the same result.140141    <Tabs>142      <Tab title="Claude Console">143        <Steps>144          <Step title="Register the key with Anthropic">145            In the Claude Console, open **Settings > Encryption keys** and click **Add key**. Enter a display name, choose **Google Cloud KMS**, and click **Continue**. Paste the full key resource name into **Key resource name**, and click **Add**.146          </Step>147148          <Step title="Validate the key">149            On the **Encryption keys** page, click **Verify** next to the key. **Connected** appears when the check passes. If it fails, a message gives the reason.150          </Step>151152          <Step title="Attach the key to a workspace">153            Open **Settings > Workspaces**, choose the workspace, and open its **Security** tab. Under **Encryption key**, select the key, click **Save**, and confirm. Attaching a key can't be undone. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).154          </Step>155        </Steps>156      </Tab>157158      <Tab title="API">159        <Steps>160          <Step title="Register the key with Anthropic">161            Create an external key configuration through the Admin API, using the resource name from the Note the full key resource name step under Encryption key setup.162163            <CodeGroup>164              ```bash cURL165              curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \166                -H "x-api-key: $ANTHROPIC_API_KEY" \167                -H "anthropic-version: 2023-06-01" \168                -H "content-type: application/json" \169                -d '{170                  "display_name": "<friendly-name>",171                  "geo": "us",172                  "provider_config": {173                    "type": "gcp",174                    "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"175                  }176                }'177              ```178179              ```bash CLI180              ant beta:organization:external-keys create <<'YAML'181              display_name: "<friendly-name>"182              geo: us183              provider_config:184                type: gcp185                key_name: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"186              YAML187              ```188189              ```python Python190              client = anthropic.Anthropic()191192              external_key = client.beta.organization.external_keys.create(193                  display_name="<friendly-name>",194                  geo="us",195                  provider_config={196                      "type": "gcp",197                      "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",198                  },199              )200201              print(f"id: {external_key.id}")202              print(f"display_name: {external_key.display_name}")203              ```204205              ```typescript TypeScript206              const client = new Anthropic();207208              const externalKey = await client.beta.organization.externalKeys.create({209                display_name: "<friendly-name>",210                geo: "us",211                provider_config: {212                  type: "gcp",213                  key_name:214                    "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"215                }216              });217218              console.log(`id: ${externalKey.id}`);219              console.log(`display_name: ${externalKey.display_name}`);220              ```221222              ```csharp C#223              using Anthropic.Models.Beta.Organization.ExternalKeys;224225              AnthropicClient client = new();226227              var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()228              {229                  DisplayName = "<friendly-name>",230                  Geo = Geo.Us,231                  ProviderConfig = new BetaGcpExternalKeyConfig232                  {233                      KeyName = "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"234                  }235              });236237              Console.WriteLine($"id: {externalKey.ID}");238              Console.WriteLine($"display_name: {externalKey.DisplayName}");239              ```240241              ```go Go242              client := anthropic.NewClient()243244              externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{245              	DisplayName: anthropic.String("<friendly-name>"),246              	Geo:         anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,247              	ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{248              		OfGCP: &anthropic.BetaGCPExternalKeyConfigParam{249              			KeyName: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",250              		},251              	},252              })253              if err != nil {254              	log.Fatal(err)255              }256257              fmt.Printf("id: %s\n", externalKey.ID)258              fmt.Printf("display_name: %s\n", externalKey.DisplayName)259              ```260261              ```java Java262              import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;263264              void main() {265                  AnthropicClient client = AnthropicOkHttpClient.fromEnv();266267                  var params = ExternalKeyCreateParams.builder()268                      .displayName("<friendly-name>")269                      .geo(ExternalKeyCreateParams.Geo.US)270                      .gcpProviderConfig("projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>")271                      .build();272                  var externalKey = client.beta().organization().externalKeys().create(params);273274                  IO.println("id: " + externalKey.id());275                  IO.println("display_name: " + externalKey.displayName().orElseThrow());276              }277              ```278279              ```php PHP280              use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;281              // ...282283              $client = new Client();284285              $externalKey = $client->beta->organization->externalKeys->create(286                  displayName: '<friendly-name>',287                  geo: Geo::US,288                  providerConfig: [289                      'type' => 'gcp',290                      'keyName' => 'projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>',291                  ],292              );293294              echo "id: {$externalKey->id}\n";295              echo "display_name: {$externalKey->displayName}\n";296              ```297298              ```ruby Ruby299              client = Anthropic::Client.new300301              external_key = client.beta.organization.external_keys.create(302                display_name: "<friendly-name>",303                geo: :us,304                provider_config: {305                  type: :gcp,306                  key_name: "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"307                }308              )309310              puts "id: #{external_key.id}"311              puts "display_name: #{external_key.display_name}"312              ```313            </CodeGroup>314315            The response contains the external key ID:316317            ```json318            {319              "type": "external_key",320              "id": "ekey_<id>",321              "display_name": "<friendly-name>"322            }323            ```324          </Step>325326          <Step title="Validate the key">327            Trigger an encrypt and decrypt round-trip against your key.328329            <CodeGroup>330              ```bash cURL331              curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \332                -H "x-api-key: $ANTHROPIC_API_KEY" \333                -H "anthropic-version: 2023-06-01"334              ```335336              ```bash CLI337              ant beta:organization:external-keys validate --external-key-id "ekey_<id>"338              ```339340              ```python Python341              client = anthropic.Anthropic()342343              validation = client.beta.organization.external_keys.validate("ekey_<id>")344345              print(f"status: {validation.status}")346              print(f"error: {validation.error}")347              ```348349              ```typescript TypeScript350              const client = new Anthropic();351352              const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");353354              console.log(`status: ${validation.status}`);355              console.log(`error: ${validation.error}`);356              ```357358              ```csharp C#359              AnthropicClient client = new();360361              var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");362363              Console.WriteLine($"status: {validation.Status.Raw()}");364              Console.WriteLine($"error: {validation.Error}");365              ```366367              ```go Go368              client := anthropic.NewClient()369370              validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")371              if err != nil {372              	log.Fatal(err)373              }374375              fmt.Printf("status: %s\n", validation.Status)376              fmt.Printf("error: %s\n", validation.Error)377              ```378379              ```java Java380              AnthropicClient client = AnthropicOkHttpClient.fromEnv();381382              var validation = client.beta().organization().externalKeys().validate("ekey_<id>");383384              IO.println("status: " + validation.status().asString());385              IO.println("error: " + validation.error().orElse(""));386              ```387388              ```php PHP389              $client = new Client();390391              $validation = $client->beta->organization->externalKeys->validate(392                  externalKeyID: 'ekey_<id>',393              );394395              echo "status: {$validation->status}\n";396              echo "error: {$validation->error}\n";397              ```398399              ```ruby Ruby400              client = Anthropic::Client.new401402              external_key_id = "ekey_<id>"403              validation = client.beta.organization.external_keys.validate(external_key_id)404405              puts "status: #{validation.status}"406              puts "error: #{validation.error}"407              ```408            </CodeGroup>409410            A successful response looks like this:411412            ```json413            { "type": "external_key_validation", "status": "success", "error": null }414            ```415416            If validation fails, common causes are:417418            * **VPC Service Controls:** if a service perimeter protects Cloud KMS in your project, add Anthropic to an access level on the perimeter (or exclude the key's project) so Anthropic can reach the key.419            * **Domain restricted sharing:** the `constraints/iam.allowedPolicyMemberDomains` org policy can strip the Anthropic service account binding (see the earlier note). Confirm the binding is present with `gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name>`.420            * **Disabled or destroyed key version:** confirm the key's primary version is enabled, and not disabled, scheduled for destruction, or destroyed.421          </Step>422423          <Step title="Attach the key to a workspace">424            Once the key is validated, attach it to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).425426            <CodeGroup>427              ```bash cURL428              curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \429                -H "x-api-key: $ANTHROPIC_API_KEY" \430                -H "anthropic-version: 2023-06-01" \431                -H "content-type: application/json" \432                -d '{433                  "external_key_id": "ekey_<id>"434                }'435              ```436437              ```bash CLI438              ant beta:organization:workspaces update \439                --workspace-id "<workspace-id>" \440                --external-key-id "ekey_<id>"441              ```442443              ```python Python444              client = anthropic.Anthropic()445446              workspace = client.beta.organization.workspaces.update(447                  "<workspace-id>", external_key_id="ekey_<id>"448              )449450              print(f"id: {workspace.id}")451              print(f"external_key_id: {workspace.external_key_id}")452              ```453454              ```typescript TypeScript455              const client = new Anthropic();456457              const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {458                external_key_id: "ekey_<id>"459              });460461              console.log(`id: ${workspace.id}`);462              console.log(`external_key_id: ${workspace.external_key_id}`);463              ```464465              ```csharp C#466              AnthropicClient client = new();467468              var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()469              {470                  ExternalKeyID = "ekey_<id>"471              });472473              Console.WriteLine($"id: {workspace.ID}");474              Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");475              ```476477              ```go Go478              client := anthropic.NewClient()479480              workspace, err := client.Beta.Organization.Workspaces.Update(481              	context.Background(),482              	"<workspace-id>",483              	anthropic.BetaOrganizationWorkspaceUpdateParams{484              		ExternalKeyID: anthropic.String("ekey_<id>"),485              	},486              )487              if err != nil {488              	log.Fatal(err)489              }490491              fmt.Printf("id: %s\n", workspace.ID)492              fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)493              ```494495              ```java Java496              import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;497498              void main() {499                  AnthropicClient client = AnthropicOkHttpClient.fromEnv();500501                  var params = WorkspaceUpdateParams.builder()502                      .externalKeyId("ekey_<id>")503                      .build();504                  var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);505506                  IO.println("id: " + workspace.id());507                  IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());508              }509              ```510511              ```php PHP512              $client = new Client();513514              $workspace = $client->beta->organization->workspaces->update(515                  workspaceID: '<workspace-id>',516                  externalKeyID: 'ekey_<id>',517              );518519              echo "id: {$workspace->id}\n";520              echo "external_key_id: {$workspace->externalKeyID}\n";521              ```522523              ```ruby Ruby524              client = Anthropic::Client.new525526              workspace_id = "<workspace-id>"527              workspace = client.beta.organization.workspaces.update(528                workspace_id,529                external_key_id: "ekey_<id>"530              )531532              puts "id: #{workspace.id}"533              puts "external_key_id: #{workspace.external_key_id}"534              ```535            </CodeGroup>536          </Step>537        </Steps>538      </Tab>539    </Tabs>540  </Tab>541542  <Tab title="Claude Enterprise">543    In [claude.ai > Organization settings > Data and privacy](https://claude.ai/admin-settings/data-privacy-controls), open **Encryption keys**, then click **Add key**. Choose **Google Cloud**, paste the full key resource name from the previous step, and click **Continue**. Anthropic validates the key with an encrypt and decrypt round-trip. Once it shows as verified, your organization is CMEK-protected from that point forward.544545    On Claude Enterprise, CMEK applies to the whole organization, so there is no separate workspace attach step, and an organization can have only one key.546  </Tab>547</Tabs>548549## Terraform550551For infrastructure-as-code deployments, the same steps map to the `google` provider with the `google_kms_key_ring`, `google_kms_crypto_key`, and `google_kms_crypto_key_iam_member` resources.552
Files main
Menu

Theme