--- title: CMEK를 위한 Google Cloud KMS 구성 url: https://platform.claude.com/docs/ko/manage-claude/cmek-google-cloud-kms description: Google Cloud KMS를 사용하여 조직에 암호화 키를 제공하세요. --- Claude Code가 이 기능을 설정하도록 하세요 ```text /claude-api Google Cloud KMS로 고객 관리형 암호화 키를 구성하도록 도와줘 ``` 이 가이드는 Anthropic 조직을 위한 [고객 관리 암호화 키(customer-managed encryption key, CMEK)](https://platform.claude.com/docs/ko/manage-claude/cmek)로 Google Cloud KMS 키를 구성하는 과정을 안내합니다. CMEK 활성화는 영구적입니다. KMS 키가 삭제되거나 비활성화되면 Anthropic은 해당 키로 암호화된 데이터를 복구할 수 없습니다. 시작하기 전에 [경고 및 제한 사항](https://platform.claude.com/docs/ko/manage-claude/cmek)을 검토하세요. ## 사전 요구 사항 * 결제가 활성화된 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 ``` 이 게시된 서비스 계정 이메일만 사용하세요. 이메일, 채팅 또는 온보딩 채널을 통해 제공된 식별자를 절대 신뢰하지 마세요. **도메인 제한 공유:** 프로젝트가 `constraints/iam.allowedPolicyMemberDomains`를 적용하는 Google Cloud 조직에 속해 있는 경우, Anthropic 서비스 계정이 조직 외부에 있기 때문에 다음 IAM 바인딩이 거부됩니다. 해당 제약 조건에 대한 프로젝트 수준의 예외를 설정하거나, Anthropic의 Cloud Identity 고객 ID(형식 `C0xxxxxxxx`)를 허용 목록에 추가해야 합니다. 필요한 경우 고객 ID에 대해 Anthropic에 문의하세요. ## 암호화 키 설정 재사용할 키 링이 이미 있는 경우 이 단계를 건너뛰세요. 키 링은 리전별로 구성됩니다. 구성 중인 Anthropic 지역과 일치하는 `us-east5`와 같은 단일 리전 US 위치를 선택하세요. `us` 및 `global`과 같은 멀티 리전 위치는 지원되지 않습니다. ```bash gcloud kms keyrings create \ --project= \ --location= ``` `ENCRYPT_DECRYPT` 용도로 대칭 키를 생성하세요. Anthropic은 HSM 보호를 강력히 권장합니다: Cloud KMS HSM 키는 FIPS 140-2 Level 3 검증을 받았으며, 소프트웨어 키 대비 비용 차이가 작습니다. `--labels` 옵션은 조직 레이블 `anthropic-org-`를 값 `true`와 함께 추가하며, 여기서 ``는 소문자로 된 Anthropic 조직 ID입니다. 이 레이블은 Anthropic이 키를 검증하는 데 필요합니다. **조직 ID 찾기:** Claude Console의 [Organization](https://platform.claude.com/settings/organization) 페이지(`platform.claude.com/settings/organization`) 또는 claude.ai의 **Organization settings > Organization**에서 **Organization ID** 필드를 복사하거나, [Organization Info](https://platform.claude.com/docs/ko/api/organization/retrieve) 엔드포인트에서 `id` 필드를 읽으세요. `org_` 접두사가 붙은 ID가 아닌 순수 UUID를 사용하세요. ```bash gcloud kms keys create \ --project= \ --location= \ --keyring= \ --purpose=encryption \ --protection-level=hsm \ --labels=anthropic-org-=true ``` 대신 소프트웨어 보호를 사용하려면 `--protection-level=hsm`을 생략하세요. 이 가이드의 다른 내용은 변경되지 않습니다. Google Cloud Console에서도 키를 생성할 수 있습니다. 키 링을 열고 **Create key**를 클릭한 다음, **Generated key**를 선택하고, 용도와 알고리즘을 대칭 암호화 및 복호화로 설정하고, 보호 수준에서 **HSM**을 선택하세요. ![HSM 보호, 대칭 암호화/복호화, 값이 true인 anthropic-org 레이블이 지정된 Google Cloud KMS의 Create key 페이지.](https://platform.claude.com/docs/images/cmek/gcp-create-key-label.png) 여러 Anthropic 조직 간에 하나의 키를 공유하려면, 각 조직에 대해 이러한 레이블을 하나씩 추가하세요. 키는 자신의 레이블을 포함하여 최대 64개의 레이블을 가질 수 있습니다. 레이블이 없는 키에 레이블을 추가하려면 `gcloud kms keys update --project= --location= --keyring= --update-labels=anthropic-org-=true`를 실행하세요. 이는 키에 이미 있는 레이블과 병합됩니다. 두 개의 키 수준 IAM 바인딩이 필요합니다. 둘 다 프로젝트 전체나 키 링 전체가 아닌 단일 암호화 키로 범위가 지정됩니다. 암호화 및 복호화, Anthropic이 워크스페이스 데이터를 보호하는 데이터 키를 암호화하고 복호화하는 데 사용합니다(봉투 암호화): ```bash gcloud kms keys add-iam-policy-binding \ --project= \ --location= \ --keyring= \ --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 \ --project= \ --location= \ --keyring= \ --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 역할을 모두 가진 서비스 계정을 추가하세요. 권한 부여가 이 키로만 범위가 지정되도록 키 링이나 프로젝트가 아닌 키의 권한 페이지에 있는지 확인하세요. ![Anthropic 서비스 계정에 Cloud KMS CryptoKey Encrypter/Decrypter 및 Cloud KMS Viewer 역할이 할당된 Grant access 대화 상자.](https://platform.claude.com/docs/images/cmek/gcp-grant-access.png) 키를 등록할 때 이를 Anthropic에 전달합니다. 형식은 다음과 같습니다: ```text wrap projects//locations//keyRings//cryptoKeys/ ``` 다음으로 검색하세요: ```bash gcloud kms keys describe \ --project= \ --location= \ --keyring= \ --format="value(name)" ``` Console에서 키의 세부 정보 페이지를 열고 **Copy resource name**을 클릭하세요. ![키의 작업 메뉴에서 Copy resource name 작업이 강조 표시된 Google Cloud 키 링 세부 정보 페이지.](https://platform.claude.com/docs/images/cmek/gcp-copy-resource-name.png) ## Anthropic에 키 등록 키를 등록하는 방법은 사용하는 제품에 따라 다릅니다. Claude Console 또는 Admin API를 통해 키를 설정할 수 있으며, 결과는 동일합니다. 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/ko/manage-claude/cmek-google-cloud-kms#organization-label)에서 설명한 대로 키에 레이블을 추가하세요. **Encryption keys** 목록에서 키 옆의 **Verify**를 클릭하세요. 검사가 통과하면 **Connected**가 표시됩니다. 실패하면 메시지에 그 이유가 표시됩니다. Claude Console에서 [Data retention](https://platform.claude.com/settings/privacy) 페이지(`platform.claude.com/settings/privacy`)로 이동하여 페이지 상단의 드롭다운 메뉴에서 워크스페이스를 선택하세요. **Encryption key** 아래에서 키를 선택하고 **Save**를 클릭한 다음 확인하세요. 키 연결은 취소할 수 없습니다. 이미 요청을 받고 있는 워크스페이스의 경우 키가 [적용되기까지 최대 하루가 걸릴 수 있습니다](https://platform.claude.com/docs/ko/manage-claude/cmek#how-it-works). 암호화 키 설정 아래의 전체 키 리소스 이름 기록 단계에서 얻은 리소스 이름을 사용하여 Admin API를 통해 외부 키 구성을 생성하세요. ```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": "", "geo": "us", "provider_config": { "type": "gcp", "key_name": "projects//locations//keyRings//cryptoKeys/" } }' ``` ```bash CLI ant organization:external-keys create <<'YAML' display_name: "" geo: us provider_config: type: gcp key_name: "projects//locations//keyRings//cryptoKeys/" YAML ``` ```python Python client = anthropic.Anthropic() external_key = client.organization.external_keys.create( display_name="", geo="us", provider_config={ "type": "gcp", "key_name": "projects//locations//keyRings//cryptoKeys/", }, ) 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: "", geo: "us", provider_config: { type: "gcp", key_name: "projects//locations//keyRings//cryptoKeys/" } }); 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 = "", Geo = Geo.Us, ProviderConfig = new GcpExternalKeyConfig { KeyName = "projects//locations//keyRings//cryptoKeys/" } }); 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(""), Geo: anthropic.OrganizationExternalKeyNewParamsGeoUs, ProviderConfig: anthropic.OrganizationExternalKeyNewParamsProviderConfigUnion{ OfGCP: &anthropic.GCPExternalKeyConfigParam{ KeyName: "projects//locations//keyRings//cryptoKeys/", }, }, }) 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("") .geo(ExternalKeyCreateParams.Geo.US) .gcpProviderConfig("projects//locations//keyRings//cryptoKeys/") .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: '', geo: Geo::US, providerConfig: [ 'type' => 'gcp', 'keyName' => 'projects//locations//keyRings//cryptoKeys/', ], ); 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: "", geo: :us, provider_config: { type: :gcp, key_name: "projects//locations//keyRings//cryptoKeys/" } ) puts "id: #{external_key.id}" puts "display_name: #{external_key.display_name}" ``` 응답에는 외부 키 ID가 포함됩니다: ```json { "type": "external_key", "id": "ekey_", "display_name": "" } ``` 키에 대해 암호화 및 복호화 왕복을 트리거하세요. ```bash cURL curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_/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_" ``` ```python Python client = anthropic.Anthropic() validation = client.organization.external_keys.validate("ekey_") print(f"status: {validation.status}") print(f"error: {validation.error}") ``` ```typescript TypeScript const client = new Anthropic(); const validation = await client.organization.externalKeys.validate("ekey_"); console.log(`status: ${validation.status}`); console.log(`error: ${validation.error}`); ``` ```csharp C# AnthropicClient client = new(); var validation = await client.Organization.ExternalKeys.Validate("ekey_"); 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_") 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_"); IO.println("status: " + validation.status().asString()); IO.println("error: " + validation.error().orElse("")); ``` ```php PHP $client = new Client(); $validation = $client->organization->externalKeys->validate( externalKeyID: 'ekey_', ); echo "status: {$validation->status}\n"; echo "error: {$validation->error}\n"; ``` ```ruby Ruby client = Anthropic::Client.new external_key_id = "ekey_" validation = client.organization.external_keys.validate(external_key_id) puts "status: #{validation.status}" puts "error: #{validation.error}" ``` 성공적인 응답은 다음과 같습니다: ```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 --project= --location= --keyring=`로 바인딩이 존재하는지 확인하세요. * **비활성화되거나 삭제된 키 버전:** 키의 기본 버전이 활성화되어 있고, 비활성화되거나, 삭제 예정이거나, 삭제되지 않았는지 확인하세요. 키가 검증되면, 해당 워크스페이스에 요청을 보내기 전에 새 워크스페이스에 키를 연결하세요. 이미 요청을 받고 있는 워크스페이스의 경우, 키가 [적용되는 데 최대 하루가 걸릴 수 있습니다](https://platform.claude.com/docs/ko/manage-claude/cmek#how-it-works). ```bash cURL curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "external_key_id": "ekey_" }' ``` ```bash CLI ant organization:workspaces update \ --workspace-id "" \ --external-key-id "ekey_" ``` ```python Python client = anthropic.Anthropic() workspace = client.organization.workspaces.update( "", external_key_id="ekey_" ) 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("", { external_key_id: "ekey_" }); 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("", new() { ExternalKeyID = "ekey_" }); 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(), "", anthropic.OrganizationWorkspaceUpdateParams{ ExternalKeyID: anthropic.String("ekey_"), }, ) 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_") .build(); var workspace = client.organization().workspaces().update("", 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: '', externalKeyID: 'ekey_', ); echo "id: {$workspace->id}\n"; echo "external_key_id: {$workspace->externalKeyID}\n"; ``` ```ruby Ruby client = Anthropic::Client.new workspace_id = "" workspace = client.organization.workspaces.update( workspace_id, external_key_id: "ekey_" ) puts "id: #{workspace.id}" puts "external_key_id: #{workspace.external_key_id}" ``` [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가 조직 전체에 적용되므로, 별도의 워크스페이스 연결 단계가 없으며, 조직은 하나의 키만 가질 수 있습니다. ## Terraform 코드형 인프라(infrastructure-as-code) 배포의 경우, 동일한 단계가 `google_kms_key_ring`, `google_kms_crypto_key`, `google_kms_crypto_key_iam_member` 리소스와 함께 `google` 공급자에 매핑됩니다.