--- title: CMEK를 위한 Azure Key Vault 구성 url: https://platform.claude.com/docs/ko/manage-claude/cmek-azure-key-vault description: Azure Key Vault를 사용하여 조직의 암호화 키를 제공하세요. --- Claude Code가 이 기능을 설정하도록 하세요 ```text /claude-api Azure Key Vault로 고객 관리형 암호화 키를 구성하도록 도와줘 ``` 이 가이드는 Azure Key Vault 키를 Anthropic 조직의 [고객 관리 암호화 키(customer-managed encryption key, CMEK)](https://platform.claude.com/docs/ko/manage-claude/cmek)로 구성하는 과정을 안내합니다. CMEK 활성화는 영구적입니다. Key Vault 키가 삭제되거나 비활성화되면 Anthropic은 해당 키로 암호화된 데이터를 복구할 수 없습니다. 시작하기 전에 [경고 및 제한 사항](https://platform.claude.com/docs/ko/manage-claude/cmek)을 검토하세요. ## 사전 요구 사항 * **RBAC 인증이 활성화되고**(`enableRbacAuthorization: true`) **공용 네트워크 액세스가 허용된** Azure Key Vault. Anthropic은 공용 데이터 플레인 엔드포인트를 통해 볼트를 호출하며, 프라이빗 엔드포인트는 지원되지 않습니다. * 볼트에 **제거 방지가 활성화됨**(`enablePurgeProtection: true`). 이것이 없으면 삭제된 키가 소프트 삭제 보존 기간 동안 영구적으로 제거될 수 있어 CMEK로 보호된 데이터가 돌이킬 수 없이 손실됩니다. 제거 방지는 한 번 활성화하면 비활성화할 수 없습니다. * 볼트에서 키를 생성하고 RBAC 역할을 할당할 수 있는 권한. * Entra 테넌트에서 서비스 주체를 생성할 수 있는 권한(`Application Administrator`, `Cloud Application Administrator` 또는 이에 상응하는 사용자 지정 역할). * 조직의 Anthropic Admin API 키. * 설치 및 인증된 [`az` CLI](https://learn.microsoft.com/en-us/cli/azure/?view=azure-cli-latest). * `AuditEvent` 로그 범주를 Log Analytics, 스토리지 계정 또는 이벤트 허브로 라우팅하도록 볼트에 구성된 **진단 설정**. Azure Key Vault는 기본적으로 데이터 플레인 감사 로그(예: `KeyWrap`, `KeyUnwrap`, `KeyGet`)를 내보내지 않으므로, 이것이 없으면 Anthropic의 키 작업에 대한 감사 추적을 얻을 수 없습니다. ## Anthropic 앱 정보 Anthropic이 암호화 키를 사용하도록 하려면 Anthropic 멀티테넌트 애플리케이션 ID와 표시 이름을 구성해야 합니다. 해당 값은 다음과 같습니다: | 필드 | 값 | | --------------------- | -------------------------------------- | | 멀티테넌트 앱 클라이언트 ID (US) | `8635ae1a-3e5d-44e8-a4ed-e0f614466f87` | | 앱 표시 이름 | `anthropic-cmek-client-us` | 게시된 이 클라이언트 ID와 표시 이름만 사용하세요. 이메일, 채팅 또는 온보딩 채널을 통해 제공된 식별자는 절대 신뢰하지 마세요. ## 암호화 키 설정 이렇게 하면 Anthropic의 CMEK 클라이언트 애플리케이션을 위한 서비스 주체가 Entra 테넌트에 생성됩니다. 이 애플리케이션은 Microsoft Graph 권한을 요청하지 않으며, Key Vault 데이터 플레인 액세스를 위한 페더레이션 대상으로만 존재합니다. ```bash az ad sp create --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87 ``` 출력에서 `id` 필드를 캡처하세요. 이것은 테넌트에 있는 서비스 주체의 객체 ID이며, RBAC 역할을 할당할 때 사용합니다. ```json { "appId": "8635ae1a-3e5d-44e8-a4ed-e0f614466f87", "displayName": "anthropic-cmek-client-us", "id": "" } ``` 서비스 주체가 이미 테넌트에 존재하는 경우(이전 시도 또는 다른 통합에서), `az ad sp create`는 "already exists" 오류와 함께 종료됩니다. 대신 해당 객체 ID를 가져오세요: ```bash az ad sp show --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87 --query id -o tsv ``` 이 단계에는 포털에 해당하는 기능이 없습니다. Azure CLI가 로컬에 설치되어 있지 않은 경우, 포털의 상단 탐색 모음에서 Cloud Shell을 여세요. 명령이 성공한 후, 기본 애플리케이션 유형 필터를 지우고 `anthropic-cmek-client-us`를 검색하여 **Microsoft Entra ID > Enterprise applications**에서 서비스 주체의 객체 ID를 찾을 수 있습니다. ![anthropic-cmek-client-us의 Application ID와 Object ID를 보여주는 Microsoft Entra 엔터프라이즈 애플리케이션 개요.](https://platform.claude.com/docs/images/cmek/azure-service-principal.png) Azure Key Vault는 대칭 키 래핑을 지원하지 않으므로, 키는 허용된 작업에 `wrapKey`와 `unwrapKey`가 포함된 RSA(3072비트 이상)여야 합니다. `--tags` 옵션은 조직 태그 `anthropic-org-`를 값 `true`와 함께 추가하며, 여기서 ``는 소문자로 된 Anthropic 조직 ID입니다. 이 태그는 Anthropic이 키를 검증하는 데 필요합니다. **조직 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/ko/api/organization/retrieve) 엔드포인트의 `id` 필드를 읽으세요. `org_` 접두사가 붙은 ID가 아닌 순수 UUID를 사용하세요. ```bash az keyvault key create \ --vault-name \ --name \ --kty RSA --size 3072 \ --ops wrapKey unwrapKey \ --tags anthropic-org-=true ``` HSM 기반 키의 경우 `--kty RSA-HSM`을 사용하세요(Premium-SKU 볼트 필요). 소프트웨어로 보호되는 RSA 키는 이 통합에 사용할 수 있습니다. 포털에서 Key Vault를 열고 **Keys**를 선택한 다음 **Generate/Import**를 선택하세요. 키 유형을 RSA로, 크기를 3072 이상으로 설정하세요. 키를 래핑 및 언래핑으로만 제한하려면 키 버전을 열고 **Permitted operations**로 스크롤한 다음 **Wrap Key**와 **Unwrap Key**를 제외한 모든 항목의 선택을 해제하세요. **Create a key** 페이지에서 **Tags** 아래에 조직 태그도 추가하세요. ![RSA, 키 크기 3072, 값이 true인 anthropic-org 태그가 지정된 Azure Key Vault의 Create a key 페이지.](https://platform.claude.com/docs/images/cmek/azure-create-key-tag.png) ![태그 1개가 있고 Permitted operations 항목이 Wrap Key와 Unwrap Key로 제한된 Azure Key Vault 키 버전.](https://platform.claude.com/docs/images/cmek/azure-permitted-operations-tag.png) 여러 Anthropic 조직 간에 하나의 키를 공유하려면 각 조직에 대해 이러한 태그를 하나씩 추가하세요. 키 버전은 자체 태그를 포함하여 최대 15개의 태그를 가질 수 있습니다. 이미 가지고 있는 키에 태그를 추가하려면 포털에서 키의 현재 버전을 열고 **Tags** 옆의 링크를 선택한 다음 태그를 추가하고 **Save**를 클릭하세요. Azure CLI에서는 `az keyvault key set-attributes --vault-name --name --tags anthropic-org-=true`를 실행하세요. 이 `--tags` 옵션은 버전의 태그를 대체하므로, 버전에 이미 있는 각 태그도 `name=value` 형식으로 `--tags`에 넣으세요. Managed HSM의 키의 경우 `--vault-name` 대신 `--hsm-name `을 사용하세요. 첫 번째 단계의 서비스 주체에 `Key Vault Crypto User` 역할을 할당하되, 전체 볼트가 아닌 **개별 키**로 범위를 지정하세요. ```bash VAULT_ID=$(az keyvault show --name --query id -o tsv) az role assignment create \ --role "Key Vault Crypto User" \ --assignee-object-id \ --assignee-principal-type ServicePrincipal \ --scope "${VAULT_ID}/keys/" ``` 기본 제공 `Key Vault Crypto User` 역할은 할당된 범위에서 키 암호화 작업(암호화, 복호화, 래핑, 언래핑, 서명, 검증)과 키 읽기 권한을 부여합니다. 이전 단계에서 키에 설정한 `--ops wrapKey unwrapKey` 제한은 이 키에 대해 성공할 수 있는 작업을 더욱 좁히므로, 실제로 Anthropic은 래핑과 언래핑만 수행할 수 있습니다. 포털에서 (볼트가 아닌) **키**를 열고 **Access control (IAM)** 탭을 선택한 다음 **Add > Add role assignment**를 클릭하고 **Key Vault Crypto User**를 선택한 후 `anthropic-cmek-client-us` 서비스 주체에 할당하세요. **전용 볼트 대안:** Microsoft는 볼트 범위에서 역할이 할당된 애플리케이션당 전용 볼트를 권장합니다. 이 Anthropic CMEK 키만 보유하는 볼트를 프로비저닝하는 경우, 대신 볼트 범위에서 역할을 할당할 수 있으며 효과는 동일합니다. 키가 공유 볼트에 있는 경우 개별 키로 범위를 지정하세요. ![anthropic-cmek-client-us에 Key Vault Crypto User 역할이 할당되어 있음을 보여주는 Key Vault IAM 역할 할당 목록.](https://platform.claude.com/docs/images/cmek/azure-role-assignment.png) ```bash az keyvault show --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의 송신 범위가 포함되어 있습니다(현재 목록은 Anthropic에 문의하세요). * `uri`가 키를 등록할 때 사용하는 볼트 URI입니다. * `tenantId`가 볼트를 관리하는 테넌트입니다. 키를 등록할 때 현재 활성 구독의 테넌트가 아닌 이 값을 `tenant_id`로 사용하세요(교차 테넌트 설정에서는 두 값이 다를 수 있습니다). ## 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**를 클릭하세요. 표시 이름을 입력하고 **Azure Key Vault**를 선택한 다음 **Continue**를 클릭하세요. **Vault URI**, **Key name**, **Tenant ID**를 입력하고 **Add**를 클릭하세요. 키 세부 정보 단계에 조직 태그가 표시됩니다. **Add**를 클릭하기 전에 [생성 단계](https://platform.claude.com/docs/ko/manage-claude/cmek-azure-key-vault#organization-tag)에서 설명한 대로 키에 태그를 추가하세요. **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": "azure", "vault_uri": "https://.vault.azure.net/", "key_name": "", "tenant_id": "" } }' ``` ```bash CLI ant organization:external-keys create <<'YAML' display_name: "" geo: us provider_config: type: azure vault_uri: "https://.vault.azure.net/" key_name: "" tenant_id: "" YAML ``` ```python Python client = anthropic.Anthropic() external_key = client.organization.external_keys.create( display_name="", geo="us", provider_config={ "type": "azure", "vault_uri": "https://.vault.azure.net/", "key_name": "", "tenant_id": "", }, ) 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: "azure", vault_uri: "https://.vault.azure.net/", key_name: "", tenant_id: "" } }); 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 AzureExternalKeyConfigParam { VaultUri = "https://.vault.azure.net/", KeyName = "", TenantID = "" } }); 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{ OfAzure: &anthropic.AzureExternalKeyConfigParam{ VaultURI: "https://.vault.azure.net/", KeyName: "", TenantID: "", }, }, }) 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.AzureExternalKeyConfigParam; import com.anthropic.models.organization.externalkeys.ExternalKeyCreateParams; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = ExternalKeyCreateParams.builder() .displayName("") .geo(ExternalKeyCreateParams.Geo.US) .providerConfig(AzureExternalKeyConfigParam.builder() .vaultUri("https://.vault.azure.net/") .keyName("") .tenantId("") .build()) .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' => 'azure', 'vaultURI' => 'https://.vault.azure.net/', 'keyName' => '', 'tenantID' => '', ], ); 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: :azure, vault_uri: "https://.vault.azure.net/", key_name: "", tenant_id: "" } ) puts "id: #{external_key.id}" puts "display_name: #{external_key.display_name}" ``` 응답에는 외부 키 ID가 포함됩니다: ```json { "type": "external_key", "id": "ekey_", "display_name": "" } ``` 키에 대해 암호화 및 복호화 왕복을 트리거하세요. 이는 Anthropic이 테넌트에 인증하고 래핑 및 언래핑 작업을 수행할 수 있음을 확인합니다. ```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 validation = client.organization.external_keys.validate("ekey_") puts "status: #{validation.status}" puts "error: #{validation.error}" ``` 성공적인 응답은 다음과 같습니다: ```json { "type": "external_key_validation", "status": "success", "error": null } ``` 검증이 실패하면 `error` 필드가 문제를 설명합니다. 일반적인 원인은 다음과 같습니다: * **RBAC 전파 지연:** 역할 할당이 적용되는 데 몇 분이 걸릴 수 있습니다. 기다렸다가 다시 시도하세요. * **Anthropic을 차단하는 네트워크 ACL:** 검증 단계에서 설명한 대로 공용 네트워크 액세스와 `ipRules`를 확인하세요. * **워크로드 ID에 대한 조건부 액세스 정책:** 테넌트에 서비스 주체를 대상으로 하는 조건부 액세스 정책이 있는 경우, Anthropic 서비스 주체를 제외하거나 정책의 명명된 위치에 Anthropic의 송신 범위를 추가하세요. 키가 검증되면 해당 워크스페이스에 요청을 보내기 전에 새 워크스페이스에 연결하세요. 이미 요청을 받고 있는 워크스페이스의 경우 키가 [적용되는 데 최대 하루가 걸릴 수 있습니다](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 = client.organization.workspaces.update( "", 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**를 클릭하세요. **Azure**를 선택하고 검증 단계의 볼트 URI, 키 이름, 테넌트 ID를 입력한 다음 **Continue**를 클릭하세요. Anthropic은 암호화 및 복호화 왕복으로 키를 검증합니다. 검증됨으로 표시되면 해당 시점부터 조직이 CMEK로 보호됩니다. Claude Enterprise에서는 CMEK가 전체 조직에 적용되므로 별도의 워크스페이스 연결 단계가 없으며, 조직은 하나의 키만 가질 수 있습니다. ## Terraform 코드형 인프라(infrastructure-as-code) 배포의 경우, 동일한 단계가 `azurerm` 및 `azuread` 공급자에 매핑됩니다.