SPB Git

Repository Public

cmek-azure-key-vault.md 25.6 KB 577 lines markdown

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      ![Microsoft Entra enterprise application overview for anthropic-cmek-client-us, showing its Application ID and Object ID.](https://platform.claude.com/docs/images/cmek/azure-service-principal.png)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      ![Azure Key Vault Create a key page with the Generate option, RSA key type, and 3072 RSA key size selected.](https://platform.claude.com/docs/images/cmek/azure-create-key.png)90    </Frame>9192    <Frame caption="Restrict permitted operations to Wrap Key and Unwrap Key.">93      ![Azure Key Vault key version with Permitted operations limited to Wrap Key and Unwrap Key.](https://platform.claude.com/docs/images/cmek/azure-permitted-operations.png)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      ![Key Vault IAM role assignments showing anthropic-cmek-client-us assigned the Key Vault Crypto User role.](https://platform.claude.com/docs/images/cmek/azure-role-assignment.png)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
Files main
Menu

Theme