Repository Public
1---2title: Configure Azure Key Vault for CMEK3url: https://platform.claude.com/docs/en/manage-claude/cmek-azure-key-vault4description: Use Azure Key Vault 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 Azure Key Vault"9```1011This guide walks through configuring an Azure Key Vault 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 Key Vault 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 start.15</Warning>1617## Prerequisites1819* An Azure Key Vault with **RBAC authorization enabled** (`enableRbacAuthorization: true`) and **public network access allowed**. Anthropic calls your vault over the public data-plane endpoint; private endpoints are not supported.20* **Purge protection enabled** (`enablePurgeProtection: true`) on the vault. Without it, a deleted key can be permanently purged during the soft-delete retention window, causing irreversible loss of your CMEK-protected data. Purge protection cannot be disabled once enabled.21* Permissions to create keys in the vault and to assign RBAC roles on it.22* Permissions to create service principals in your Entra tenant (`Application Administrator`, `Cloud Application Administrator`, or an equivalent custom role).23* An Anthropic Admin API key for your organization.24* The [`az` CLI](https://learn.microsoft.com/en-us/cli/azure/?view=azure-cli-latest) installed and authenticated.25* **Diagnostic Settings** configured on the vault to route the `AuditEvent` log category to Log Analytics, a storage account, or an event hub. Azure Key Vault does not emit data-plane audit logs (such as `KeyWrap`, `KeyUnwrap`, and `KeyGet`) by default, so without this you get no audit trail for Anthropic's key operations.2627## Anthropic app information2829To have Anthropic use your encryption key, you must configure an Anthropic multitenant application ID and display name. Those values are:3031| Field | Value |32| ------------------------------ | -------------------------------------- |33| Multitenant app client ID (US) | `8635ae1a-3e5d-44e8-a4ed-e0f614466f87` |34| App display name | `anthropic-cmek-client-us` |3536<Warning>37 Use only this published client ID and display name. Never trust an identifier provided over email, chat, or any onboarding channel.38</Warning>3940## Encryption key setup4142<Steps>43 <Step title="Consent to the Anthropic multitenant application">44 This creates a service principal in your Entra tenant for Anthropic's CMEK client application. The application requests no Microsoft Graph permissions; it exists solely as a federation target for Key Vault data-plane access.4546 ```bash47 az ad sp create --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f8748 ```4950 From the output, capture the `id` field. This is the service principal's object ID in your tenant, which you use when you assign the RBAC role.5152 ```json53 {54 "appId": "8635ae1a-3e5d-44e8-a4ed-e0f614466f87",55 "displayName": "anthropic-cmek-client-us",56 "id": "<sp-object-id>"57 }58 ```5960 If the service principal already exists in your tenant (from a prior attempt or another integration), `az ad sp create` exits with an "already exists" error. Fetch its object ID instead:6162 ```bash63 az ad sp show --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87 --query id -o tsv64 ```6566 This step has no Portal equivalent. If you do not have the Azure CLI installed locally, open Cloud Shell from the Portal's top navigation bar. After the command succeeds, you can find the service principal's object ID in **Microsoft Entra ID > Enterprise applications** by clearing the default application-type filter and searching for `anthropic-cmek-client-us`.6768 <Frame caption="Find the service principal's Object ID on its Entra enterprise application overview.">69 70 </Frame>71 </Step>7273 <Step title="Create an RSA key in your vault">74 Azure Key Vault does not support symmetric key wrapping, so the key must be RSA (3072-bit or larger) with `wrapKey` and `unwrapKey` in its allowed operations.7576 ```bash77 az keyvault key create \78 --vault-name <your-vault-name> \79 --name <your-key-name> \80 --kty RSA --size 3072 \81 --ops wrapKey unwrapKey82 ```8384 For HSM-backed keys, use `--kty RSA-HSM` (requires a Premium-SKU vault). Software-protected RSA keys are acceptable for this integration.8586 From the Portal, open your Key Vault, select **Keys**, then **Generate/Import**. Set the key type to RSA and the size to 3072 or larger. To restrict the key to wrap and unwrap only, open the key version, scroll to **Permitted operations**, and uncheck everything except **Wrap Key** and **Unwrap Key**.8788 <Frame caption="Create an RSA key sized 3072 or larger.">89 90 </Frame>9192 <Frame caption="Restrict permitted operations to Wrap Key and Unwrap Key.">93 94 </Frame>95 </Step>9697 <Step title="Grant the Anthropic service principal access to your key">98 Assign the `Key Vault Crypto User` role to the service principal from the first step, scoped to the **individual key** rather than the whole vault.99100 ```bash101 VAULT_ID=$(az keyvault show --name <your-vault-name> --query id -o tsv)102103 az role assignment create \104 --role "Key Vault Crypto User" \105 --assignee-object-id <sp-object-id> \106 --assignee-principal-type ServicePrincipal \107 --scope "${VAULT_ID}/keys/<your-key-name>"108 ```109110 The built-in `Key Vault Crypto User` role grants key cryptographic operations (encrypt, decrypt, wrap, unwrap, sign, verify) plus key read on its assigned scope. The `--ops wrapKey unwrapKey` restriction you set on the key in the previous step further narrows which of those operations can succeed against this key, so in practice Anthropic can only wrap and unwrap.111112 From the Portal, open the **key** (not the vault), select its **Access control (IAM)** tab, click **Add > Add role assignment**, select **Key Vault Crypto User**, and assign it to the `anthropic-cmek-client-us` service principal.113114 <Note>115 **Dedicated vault alternative:** Microsoft recommends a dedicated vault per application with roles assigned at the vault scope. If you provision a vault that holds only this Anthropic CMEK key, you can assign the role at the vault scope instead and the effect is identical. Scope to the individual key when the key lives in a shared vault.116 </Note>117118 <Frame caption="Assign Key Vault Crypto User to the Anthropic service principal, scoped to the key.">119 120 </Frame>121 </Step>122123 <Step title="Verify your vault configuration">124 ```bash125 az keyvault show --name <your-vault-name> \126 --query "{rbac:properties.enableRbacAuthorization, purge:properties.enablePurgeProtection, pub:properties.publicNetworkAccess, net:properties.networkAcls.defaultAction, ipRules:properties.networkAcls.ipRules, uri:properties.vaultUri, tenantId:properties.tenantId}"127 ```128129 Confirm that:130131 * `rbac` is `true`.132 * `purge` is `true`. If it is `false` or `null`, enable purge protection on the vault before proceeding. Without it, a soft-deleted key can be permanently purged during the retention window, making your CMEK-protected data unrecoverable.133 * `pub` is `"Enabled"`. If it is `"Disabled"`, Anthropic cannot reach the vault over its public data-plane endpoint and validation fails.134 * `net` is `"Allow"`, or, if it is `"Deny"`, that `ipRules` include Anthropic's egress ranges (contact Anthropic for the current list).135 * `uri` is the vault URI you use when you register the key.136 * `tenantId` is the tenant that governs the vault. Use this value as `tenant_id` when you register the key, not the tenant of your currently-active subscription (the two can differ in cross-tenant setups).137 </Step>138</Steps>139140## Register the key with Anthropic141142How you register the key depends on which product you use.143144<Tabs>145 <Tab title="Claude Platform">146 You can set up the key in the Claude Console or through the Admin API, with the same result.147148 <Tabs>149 <Tab title="Claude Console">150 <Steps>151 <Step title="Register the key with Anthropic">152 In the Claude Console, open **Settings > Encryption keys** and click **Add key**. Enter a display name, choose **Azure Key Vault**, and click **Continue**. Fill in **Vault URI**, **Key name**, and **Tenant ID**, and click **Add**.153 </Step>154155 <Step title="Validate the key">156 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.157 </Step>158159 <Step title="Attach the key to a workspace">160 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).161 </Step>162 </Steps>163 </Tab>164165 <Tab title="API">166 <Steps>167 <Step title="Register the key with Anthropic">168 Create an external key configuration through the Admin API.169170 <CodeGroup>171 ```bash cURL172 curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \173 -H "x-api-key: $ANTHROPIC_API_KEY" \174 -H "anthropic-version: 2023-06-01" \175 -H "content-type: application/json" \176 -d '{177 "display_name": "<friendly-name>",178 "geo": "us",179 "provider_config": {180 "type": "azure",181 "vault_uri": "https://<your-vault-name>.vault.azure.net/",182 "key_name": "<your-key-name>",183 "tenant_id": "<your-tenant-id>"184 }185 }'186 ```187188 ```bash CLI189 ant beta:organization:external-keys create <<'YAML'190 display_name: "<friendly-name>"191 geo: us192 provider_config:193 type: azure194 vault_uri: "https://<your-vault-name>.vault.azure.net/"195 key_name: "<your-key-name>"196 tenant_id: "<your-tenant-id>"197 YAML198 ```199200 ```python Python201 client = anthropic.Anthropic()202203 external_key = client.beta.organization.external_keys.create(204 display_name="<friendly-name>",205 geo="us",206 provider_config={207 "type": "azure",208 "vault_uri": "https://<your-vault-name>.vault.azure.net/",209 "key_name": "<your-key-name>",210 "tenant_id": "<your-tenant-id>",211 },212 )213214 print(f"id: {external_key.id}")215 print(f"display_name: {external_key.display_name}")216 ```217218 ```typescript TypeScript219 const client = new Anthropic();220221 const externalKey = await client.beta.organization.externalKeys.create({222 display_name: "<friendly-name>",223 geo: "us",224 provider_config: {225 type: "azure",226 vault_uri: "https://<your-vault-name>.vault.azure.net/",227 key_name: "<your-key-name>",228 tenant_id: "<your-tenant-id>"229 }230 });231232 console.log(`id: ${externalKey.id}`);233 console.log(`display_name: ${externalKey.display_name}`);234 ```235236 ```csharp C#237 using Anthropic.Models.Beta.Organization.ExternalKeys;238239 AnthropicClient client = new();240241 var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()242 {243 DisplayName = "<friendly-name>",244 Geo = Geo.Us,245 ProviderConfig = new BetaAzureExternalKeyConfigParam246 {247 VaultUri = "https://<your-vault-name>.vault.azure.net/",248 KeyName = "<your-key-name>",249 TenantID = "<your-tenant-id>"250 }251 });252253 Console.WriteLine($"id: {externalKey.ID}");254 Console.WriteLine($"display_name: {externalKey.DisplayName}");255 ```256257 ```go Go258 client := anthropic.NewClient()259260 externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{261 DisplayName: anthropic.String("<friendly-name>"),262 Geo: anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,263 ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{264 OfAzure: &anthropic.BetaAzureExternalKeyConfigParam{265 VaultURI: "https://<your-vault-name>.vault.azure.net/",266 KeyName: "<your-key-name>",267 TenantID: "<your-tenant-id>",268 },269 },270 })271 if err != nil {272 log.Fatal(err)273 }274275 fmt.Printf("id: %s\n", externalKey.ID)276 fmt.Printf("display_name: %s\n", externalKey.DisplayName)277 ```278279 ```java Java280 import com.anthropic.models.beta.organization.externalkeys.BetaAzureExternalKeyConfigParam;281 import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;282283 void main() {284 AnthropicClient client = AnthropicOkHttpClient.fromEnv();285286 var params = ExternalKeyCreateParams.builder()287 .displayName("<friendly-name>")288 .geo(ExternalKeyCreateParams.Geo.US)289 .providerConfig(BetaAzureExternalKeyConfigParam.builder()290 .vaultUri("https://<your-vault-name>.vault.azure.net/")291 .keyName("<your-key-name>")292 .tenantId("<your-tenant-id>")293 .build())294 .build();295 var externalKey = client.beta().organization().externalKeys().create(params);296297 IO.println("id: " + externalKey.id());298 IO.println("display_name: " + externalKey.displayName().orElseThrow());299 }300 ```301302 ```php PHP303 use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;304 // ...305306 $client = new Client();307308 $externalKey = $client->beta->organization->externalKeys->create(309 displayName: '<friendly-name>',310 geo: Geo::US,311 providerConfig: [312 'type' => 'azure',313 'vaultURI' => 'https://<your-vault-name>.vault.azure.net/',314 'keyName' => '<your-key-name>',315 'tenantID' => '<your-tenant-id>',316 ],317 );318319 echo "id: {$externalKey->id}\n";320 echo "display_name: {$externalKey->displayName}\n";321 ```322323 ```ruby Ruby324 client = Anthropic::Client.new325326 external_key = client.beta.organization.external_keys.create(327 display_name: "<friendly-name>",328 geo: :us,329 provider_config: {330 type: :azure,331 vault_uri: "https://<your-vault-name>.vault.azure.net/",332 key_name: "<your-key-name>",333 tenant_id: "<your-tenant-id>"334 }335 )336337 puts "id: #{external_key.id}"338 puts "display_name: #{external_key.display_name}"339 ```340 </CodeGroup>341342 The response contains the external key ID:343344 ```json345 {346 "type": "external_key",347 "id": "ekey_<id>",348 "display_name": "<friendly-name>"349 }350 ```351 </Step>352353 <Step title="Validate the key">354 Trigger an encrypt and decrypt round-trip against your key. This confirms that Anthropic can authenticate to your tenant and perform wrap and unwrap operations.355356 <CodeGroup>357 ```bash cURL358 curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \359 -H "x-api-key: $ANTHROPIC_API_KEY" \360 -H "anthropic-version: 2023-06-01"361 ```362363 ```bash CLI364 ant beta:organization:external-keys validate --external-key-id "ekey_<id>"365 ```366367 ```python Python368 client = anthropic.Anthropic()369370 validation = client.beta.organization.external_keys.validate("ekey_<id>")371372 print(f"status: {validation.status}")373 print(f"error: {validation.error}")374 ```375376 ```typescript TypeScript377 const client = new Anthropic();378379 const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");380381 console.log(`status: ${validation.status}`);382 console.log(`error: ${validation.error}`);383 ```384385 ```csharp C#386 AnthropicClient client = new();387388 var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");389390 Console.WriteLine($"status: {validation.Status.Raw()}");391 Console.WriteLine($"error: {validation.Error}");392 ```393394 ```go Go395 client := anthropic.NewClient()396397 validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")398 if err != nil {399 log.Fatal(err)400 }401402 fmt.Printf("status: %s\n", validation.Status)403 fmt.Printf("error: %s\n", validation.Error)404 ```405406 ```java Java407 AnthropicClient client = AnthropicOkHttpClient.fromEnv();408409 var validation = client.beta().organization().externalKeys().validate("ekey_<id>");410411 IO.println("status: " + validation.status().asString());412 IO.println("error: " + validation.error().orElse(""));413 ```414415 ```php PHP416 $client = new Client();417418 $validation = $client->beta->organization->externalKeys->validate(419 externalKeyID: 'ekey_<id>',420 );421422 echo "status: {$validation->status}\n";423 echo "error: {$validation->error}\n";424 ```425426 ```ruby Ruby427 client = Anthropic::Client.new428429 validation = client.beta.organization.external_keys.validate("ekey_<id>")430431 puts "status: #{validation.status}"432 puts "error: #{validation.error}"433 ```434 </CodeGroup>435436 A successful response looks like this:437438 ```json439 { "type": "external_key_validation", "status": "success", "error": null }440 ```441442 If validation fails, the `error` field describes the problem. Common causes are:443444 * **RBAC propagation delay:** role assignments can take a few minutes to take effect. Wait and retry.445 * **Network ACLs blocking Anthropic:** confirm public network access and `ipRules` as described in the verification step.446 * **Conditional access policies on workload identities:** if your tenant has conditional access policies that target service principals, exclude the Anthropic service principal or add Anthropic's egress ranges to the policy's named locations.447 </Step>448449 <Step title="Attach the key to a workspace">450 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).451452 <CodeGroup>453 ```bash cURL454 curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \455 -H "x-api-key: $ANTHROPIC_API_KEY" \456 -H "anthropic-version: 2023-06-01" \457 -H "content-type: application/json" \458 -d '{459 "external_key_id": "ekey_<id>"460 }'461 ```462463 ```bash CLI464 ant beta:organization:workspaces update \465 --workspace-id "<workspace-id>" \466 --external-key-id "ekey_<id>"467 ```468469 ```python Python470 client = anthropic.Anthropic()471472 workspace = client.beta.organization.workspaces.update(473 "<workspace-id>", external_key_id="ekey_<id>"474 )475476 print(f"id: {workspace.id}")477 print(f"external_key_id: {workspace.external_key_id}")478 ```479480 ```typescript TypeScript481 const client = new Anthropic();482483 const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {484 external_key_id: "ekey_<id>"485 });486487 console.log(`id: ${workspace.id}`);488 console.log(`external_key_id: ${workspace.external_key_id}`);489 ```490491 ```csharp C#492 AnthropicClient client = new();493494 var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()495 {496 ExternalKeyID = "ekey_<id>"497 });498499 Console.WriteLine($"id: {workspace.ID}");500 Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");501 ```502503 ```go Go504 client := anthropic.NewClient()505506 workspace, err := client.Beta.Organization.Workspaces.Update(507 context.Background(),508 "<workspace-id>",509 anthropic.BetaOrganizationWorkspaceUpdateParams{510 ExternalKeyID: anthropic.String("ekey_<id>"),511 },512 )513 if err != nil {514 log.Fatal(err)515 }516517 fmt.Printf("id: %s\n", workspace.ID)518 fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)519 ```520521 ```java Java522 import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;523524 void main() {525 AnthropicClient client = AnthropicOkHttpClient.fromEnv();526527 var params = WorkspaceUpdateParams.builder()528 .externalKeyId("ekey_<id>")529 .build();530 var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);531532 IO.println("id: " + workspace.id());533 IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());534 }535 ```536537 ```php PHP538 $client = new Client();539540 $workspace = $client->beta->organization->workspaces->update(541 workspaceID: '<workspace-id>',542 externalKeyID: 'ekey_<id>',543 );544545 echo "id: {$workspace->id}\n";546 echo "external_key_id: {$workspace->externalKeyID}\n";547 ```548549 ```ruby Ruby550 client = Anthropic::Client.new551552 workspace = client.beta.organization.workspaces.update(553 "<workspace-id>",554 external_key_id: "ekey_<id>"555 )556557 puts "id: #{workspace.id}"558 puts "external_key_id: #{workspace.external_key_id}"559 ```560 </CodeGroup>561 </Step>562 </Steps>563 </Tab>564 </Tabs>565 </Tab>566567 <Tab title="Claude Enterprise">568 In [claude.ai > Organization settings > Data and privacy](https://claude.ai/admin-settings/data-privacy-controls), open **Encryption keys**, then click **Add key**. Choose **Azure**, enter the vault URI, key name, and tenant ID from the verification 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.569570 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.571 </Tab>572</Tabs>573574## Terraform575576For infrastructure-as-code deployments, the same steps map to the `azurerm` and `azuread` providers.577