AmministrazioneChiavi di crittografia

Configurare Azure Key Vault per CMEK

Usa Azure Key Vault per fornire una chiave di crittografia per la tua organizzazione.

Configure with the /claude-api skill in Claude Code

claude "/claude-api help me configure a customer-managed encryption key with Azure Key Vault"

Questa guida illustra come configurare una chiave di Azure Key Vault come "customer-managed encryption key" (chiave di crittografia gestita dal cliente), o CMEK, per la tua organizzazione Anthropic.

L'abilitazione di CMEK è permanente. Se la tua chiave di Key Vault viene eliminata o disabilitata, Anthropic non può recuperare i dati crittografati con essa. Consulta le avvertenze e limitazioni prima di iniziare.

Prerequisiti

Un Azure Key Vault con autorizzazione RBAC abilitata (enableRbacAuthorization: true) e accesso alla rete pubblica consentito. Anthropic chiama il tuo vault tramite l'endpoint pubblico del data-plane; gli endpoint privati non sono supportati.
Protezione dall'eliminazione abilitata (enablePurgeProtection: true) sul vault. Senza di essa, una chiave eliminata può essere rimossa definitivamente durante la finestra di conservazione del soft-delete, causando la perdita irreversibile dei dati protetti da CMEK. La protezione dall'eliminazione non può essere disabilitata una volta abilitata.
Autorizzazioni per creare chiavi nel vault e per assegnare ruoli RBAC su di esso.
Autorizzazioni per creare service principal nel tuo tenant Entra (Application Administrator, Cloud Application Administrator o un ruolo personalizzato equivalente).
Una chiave API Admin di Anthropic per la tua organizzazione.
La CLI az installata e autenticata.
Impostazioni di diagnostica configurate sul vault per instradare la categoria di log AuditEvent a Log Analytics, a un account di archiviazione o a un hub eventi. Azure Key Vault non emette log di audit del data-plane (come KeyWrap, KeyUnwrap e KeyGet) per impostazione predefinita, quindi senza questa configurazione non ottieni alcuna traccia di audit per le operazioni sulla chiave eseguite da Anthropic.

Informazioni sull'app Anthropic

Affinché Anthropic utilizzi la tua chiave di crittografia, devi configurare un ID applicazione multi-tenant e un nome visualizzato di Anthropic. Questi valori sono:

Campo	Valore
ID client app multi-tenant (US)	`8635ae1a-3e5d-44e8-a4ed-e0f614466f87`
Nome visualizzato app	`anthropic-cmek-client-us`

Usa solo questo ID client e nome visualizzato pubblicati. Non fidarti mai di un identificatore fornito tramite email, chat o qualsiasi canale di onboarding.

Configurazione della chiave di crittografia

Fornisci il consenso all'applicazione multi-tenant di Anthropic
Questo crea un service principal nel tuo tenant Entra per l'applicazione client CMEK di Anthropic. L'applicazione non richiede autorizzazioni Microsoft Graph; esiste esclusivamente come destinazione di federazione per l'accesso al data-plane di Key Vault.
az ad sp create --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87
Dall'output, acquisisci il campo id. Questo è l'object ID del service principal nel tuo tenant, che utilizzerai quando assegni il ruolo RBAC.
{ "appId": "8635ae1a-3e5d-44e8-a4ed-e0f614466f87", "displayName": "anthropic-cmek-client-us", "id": "<sp-object-id>" }
Se il service principal esiste già nel tuo tenant (da un tentativo precedente o da un'altra integrazione), az ad sp create termina con un errore "already exists". In tal caso, recupera il suo object ID:
az ad sp show --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87 --query id -o tsv
Questo passaggio non ha un equivalente nel Portale. Se non hai la CLI di Azure installata localmente, apri Cloud Shell dalla barra di navigazione superiore del Portale. Dopo che il comando ha avuto successo, puoi trovare l'object ID del service principal in Microsoft Entra ID > Enterprise applications rimuovendo il filtro predefinito sul tipo di applicazione e cercando anthropic-cmek-client-us.
Trova l'Object ID del service principal nella panoramica dell'applicazione enterprise di Entra.
Crea una chiave RSA nel tuo vault
Azure Key Vault non supporta il wrapping di chiavi simmetriche, quindi la chiave deve essere RSA (3072 bit o superiore) con wrapKey e unwrapKey tra le operazioni consentite.
az keyvault key create \ --vault-name <your-vault-name> \ --name <your-key-name> \ --kty RSA --size 3072 \ --ops wrapKey unwrapKey
Per chiavi supportate da HSM, usa --kty RSA-HSM (richiede un vault con SKU Premium). Le chiavi RSA protette da software sono accettabili per questa integrazione.
Dal Portale, apri il tuo Key Vault, seleziona Keys, quindi Generate/Import. Imposta il tipo di chiave su RSA e la dimensione su 3072 o superiore. Per limitare la chiave alle sole operazioni di wrap e unwrap, apri la versione della chiave, scorri fino a Permitted operations e deseleziona tutto tranne Wrap Key e Unwrap Key.
Crea una chiave RSA di dimensione 3072 o superiore.
Limita le operazioni consentite (Permitted operations) a Wrap Key e Unwrap Key.
Concedi al service principal di Anthropic l'accesso alla tua chiave
Assegna il ruolo Key Vault Crypto User al service principal del primo passaggio, con ambito limitato alla singola chiave anziché all'intero vault.
VAULT_ID=$(az keyvault show --name <your-vault-name> --query id -o tsv) az role assignment create \ --role "Key Vault Crypto User" \ --assignee-object-id <sp-object-id> \ --assignee-principal-type ServicePrincipal \ --scope "${VAULT_ID}/keys/<your-key-name>"
Il ruolo predefinito Key Vault Crypto User concede operazioni crittografiche sulla chiave (encrypt, decrypt, wrap, unwrap, sign, verify) oltre alla lettura della chiave nell'ambito assegnato. La restrizione --ops wrapKey unwrapKey che hai impostato sulla chiave nel passaggio precedente limita ulteriormente quali di queste operazioni possono avere successo su questa chiave, quindi in pratica Anthropic può solo eseguire wrap e unwrap.
Dal Portale, apri la chiave (non il vault), seleziona la scheda Access control (IAM), fai clic su Add > Add role assignment, seleziona Key Vault Crypto User e assegnalo al service principal anthropic-cmek-client-us.
Alternativa con vault dedicato: Microsoft consiglia un vault dedicato per applicazione con ruoli assegnati a livello di vault. Se esegui il provisioning di un vault che contiene solo questa chiave CMEK di Anthropic, puoi assegnare il ruolo a livello di vault e l'effetto è identico. Limita l'ambito alla singola chiave quando la chiave risiede in un vault condiviso.
Assegna Key Vault Crypto User al service principal di Anthropic, con ambito limitato alla chiave.
Verifica la configurazione del tuo vault
az keyvault show --name <your-vault-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}"
Verifica che:
- rbac sia true.
- purge sia true. Se è false o null, abilita la protezione dall'eliminazione sul vault prima di procedere. Senza di essa, una chiave eliminata con soft-delete può essere rimossa definitivamente durante la finestra di conservazione, rendendo i tuoi dati protetti da CMEK irrecuperabili.
- pub sia "Enabled". Se è "Disabled", Anthropic non può raggiungere il vault tramite il suo endpoint pubblico del data-plane e la validazione fallisce.
- net sia "Allow", oppure, se è "Deny", che ipRules includa gli intervalli di egress di Anthropic (contatta Anthropic per l'elenco aggiornato).
- uri sia l'URI del vault che utilizzi quando registri la chiave.
- tenantId sia il tenant che governa il vault. Usa questo valore come tenant_id quando registri la chiave, non il tenant della tua sottoscrizione attualmente attiva (i due possono differire nelle configurazioni cross-tenant).

Registra la chiave con Anthropic

Crea una configurazione di chiave esterna tramite l'Admin API.

curl -sS https://api.anthropic.com/v1/organizations/external_keys \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "display_name": "<friendly-name>",
    "geo": "us",
    "provider_config": {
      "type": "azure",
      "vault_uri": "https://<your-vault-name>.vault.azure.net/",
      "key_name": "<your-key-name>",
      "tenant_id": "<your-tenant-id>"
    }
  }'

La risposta contiene l'ID della chiave esterna:

{
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

Valida la chiave
Attiva un ciclo completo di crittografia e decrittografia sulla tua chiave. Questo conferma che Anthropic può autenticarsi nel tuo tenant ed eseguire operazioni di wrap e unwrap.
curl -sS -X POST https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate \ -H "x-api-key: <anthropic-admin-api-key>" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" -d '{}'
Una risposta di successo ha questo aspetto:
{ "type": "external_key_validation", "status": "success", "error": null }
Se la validazione fallisce, il campo error descrive il problema. Le cause comuni sono:
- Ritardo di propagazione RBAC: le assegnazioni di ruolo possono richiedere alcuni minuti per diventare effettive. Attendi e riprova.
- ACL di rete che bloccano Anthropic: verifica l'accesso alla rete pubblica e le ipRules come descritto nel passaggio di verifica.
- Criteri di accesso condizionale sulle identità dei carichi di lavoro: se il tuo tenant ha criteri di accesso condizionale che hanno come destinazione i service principal, escludi il service principal di Anthropic o aggiungi gli intervalli di egress di Anthropic alle posizioni denominate del criterio.

Collega la chiave a un workspace

Una volta validata la chiave, collegala a un workspace per abilitare CMEK per i dati di quel workspace.

curl -sS -X POST https://api.anthropic.com/v1/organizations/workspaces/<workspace-id> \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "external_key_id": "ekey_<id>"
  }'

Terraform

Per i deployment infrastructure-as-code, gli stessi passaggi corrispondono ai provider azurerm e azuread.

Was this page helpful?

Prerequisiti

Un Azure Key Vault con autorizzazione RBAC abilitata (enableRbacAuthorization: true) e accesso alla rete pubblica consentito. Anthropic chiama il tuo vault tramite l'endpoint pubblico del data-plane; gli endpoint privati non sono supportati.

Protezione dall'eliminazione abilitata (enablePurgeProtection: true) sul vault. Senza di essa, una chiave eliminata può essere rimossa definitivamente durante la finestra di conservazione del soft-delete, causando la perdita irreversibile dei dati protetti da CMEK. La protezione dall'eliminazione non può essere disabilitata una volta abilitata.

Autorizzazioni per creare chiavi nel vault e per assegnare ruoli RBAC su di esso.

Autorizzazioni per creare service principal nel tuo tenant Entra (Application Administrator, Cloud Application Administrator o un ruolo personalizzato equivalente).

Una chiave API Admin di Anthropic per la tua organizzazione.

La CLI az installata e autenticata.

Impostazioni di diagnostica configurate sul vault per instradare la categoria di log AuditEvent a Log Analytics, a un account di archiviazione o a un hub eventi. Azure Key Vault non emette log di audit del data-plane (come KeyWrap, KeyUnwrap e KeyGet) per impostazione predefinita, quindi senza questa configurazione non ottieni alcuna traccia di audit per le operazioni sulla chiave eseguite da Anthropic.

Informazioni sull'app Anthropic

Affinché Anthropic utilizzi la tua chiave di crittografia, devi configurare un ID applicazione multi-tenant e un nome visualizzato di Anthropic. Questi valori sono:

Campo	Valore
ID client app multi-tenant (US)	`8635ae1a-3e5d-44e8-a4ed-e0f614466f87`
Nome visualizzato app	`anthropic-cmek-client-us`

Usa solo questo ID client e nome visualizzato pubblicati. Non fidarti mai di un identificatore fornito tramite email, chat o qualsiasi canale di onboarding.

Configurazione della chiave di crittografia

Fornisci il consenso all'applicazione multi-tenant di Anthropic
Questo crea un service principal nel tuo tenant Entra per l'applicazione client CMEK di Anthropic. L'applicazione non richiede autorizzazioni Microsoft Graph; esiste esclusivamente come destinazione di federazione per l'accesso al data-plane di Key Vault.
az ad sp create --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87
Dall'output, acquisisci il campo id. Questo è l'object ID del service principal nel tuo tenant, che utilizzerai quando assegni il ruolo RBAC.
{ "appId": "8635ae1a-3e5d-44e8-a4ed-e0f614466f87", "displayName": "anthropic-cmek-client-us", "id": "<sp-object-id>" }
Se il service principal esiste già nel tuo tenant (da un tentativo precedente o da un'altra integrazione), az ad sp create termina con un errore "already exists". In tal caso, recupera il suo object ID:
az ad sp show --id 8635ae1a-3e5d-44e8-a4ed-e0f614466f87 --query id -o tsv
Questo passaggio non ha un equivalente nel Portale. Se non hai la CLI di Azure installata localmente, apri Cloud Shell dalla barra di navigazione superiore del Portale. Dopo che il comando ha avuto successo, puoi trovare l'object ID del service principal in Microsoft Entra ID > Enterprise applications rimuovendo il filtro predefinito sul tipo di applicazione e cercando anthropic-cmek-client-us.
Trova l'Object ID del service principal nella panoramica dell'applicazione enterprise di Entra.
Crea una chiave RSA nel tuo vault
Azure Key Vault non supporta il wrapping di chiavi simmetriche, quindi la chiave deve essere RSA (3072 bit o superiore) con wrapKey e unwrapKey tra le operazioni consentite.
az keyvault key create \ --vault-name <your-vault-name> \ --name <your-key-name> \ --kty RSA --size 3072 \ --ops wrapKey unwrapKey
Per chiavi supportate da HSM, usa --kty RSA-HSM (richiede un vault con SKU Premium). Le chiavi RSA protette da software sono accettabili per questa integrazione.
Dal Portale, apri il tuo Key Vault, seleziona Keys, quindi Generate/Import. Imposta il tipo di chiave su RSA e la dimensione su 3072 o superiore. Per limitare la chiave alle sole operazioni di wrap e unwrap, apri la versione della chiave, scorri fino a Permitted operations e deseleziona tutto tranne Wrap Key e Unwrap Key.
Crea una chiave RSA di dimensione 3072 o superiore.
Limita le operazioni consentite (Permitted operations) a Wrap Key e Unwrap Key.
Concedi al service principal di Anthropic l'accesso alla tua chiave
Assegna il ruolo Key Vault Crypto User al service principal del primo passaggio, con ambito limitato alla singola chiave anziché all'intero vault.
VAULT_ID=$(az keyvault show --name <your-vault-name> --query id -o tsv) az role assignment create \ --role "Key Vault Crypto User" \ --assignee-object-id <sp-object-id> \ --assignee-principal-type ServicePrincipal \ --scope "${VAULT_ID}/keys/<your-key-name>"
Il ruolo predefinito Key Vault Crypto User concede operazioni crittografiche sulla chiave (encrypt, decrypt, wrap, unwrap, sign, verify) oltre alla lettura della chiave nell'ambito assegnato. La restrizione --ops wrapKey unwrapKey che hai impostato sulla chiave nel passaggio precedente limita ulteriormente quali di queste operazioni possono avere successo su questa chiave, quindi in pratica Anthropic può solo eseguire wrap e unwrap.
Dal Portale, apri la chiave (non il vault), seleziona la scheda Access control (IAM), fai clic su Add > Add role assignment, seleziona Key Vault Crypto User e assegnalo al service principal anthropic-cmek-client-us.
Alternativa con vault dedicato: Microsoft consiglia un vault dedicato per applicazione con ruoli assegnati a livello di vault. Se esegui il provisioning di un vault che contiene solo questa chiave CMEK di Anthropic, puoi assegnare il ruolo a livello di vault e l'effetto è identico. Limita l'ambito alla singola chiave quando la chiave risiede in un vault condiviso.
Assegna Key Vault Crypto User al service principal di Anthropic, con ambito limitato alla chiave.
Verifica la configurazione del tuo vault
az keyvault show --name <your-vault-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}"
Verifica che:
- rbac sia true.
- purge sia true. Se è false o null, abilita la protezione dall'eliminazione sul vault prima di procedere. Senza di essa, una chiave eliminata con soft-delete può essere rimossa definitivamente durante la finestra di conservazione, rendendo i tuoi dati protetti da CMEK irrecuperabili.
- pub sia "Enabled". Se è "Disabled", Anthropic non può raggiungere il vault tramite il suo endpoint pubblico del data-plane e la validazione fallisce.
- net sia "Allow", oppure, se è "Deny", che ipRules includa gli intervalli di egress di Anthropic (contatta Anthropic per l'elenco aggiornato).
- uri sia l'URI del vault che utilizzi quando registri la chiave.
- tenantId sia il tenant che governa il vault. Usa questo valore come tenant_id quando registri la chiave, non il tenant della tua sottoscrizione attualmente attiva (i due possono differire nelle configurazioni cross-tenant).

Registra la chiave con Anthropic

Crea una configurazione di chiave esterna tramite l'Admin API.

curl -sS https://api.anthropic.com/v1/organizations/external_keys \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "display_name": "<friendly-name>",
    "geo": "us",
    "provider_config": {
      "type": "azure",
      "vault_uri": "https://<your-vault-name>.vault.azure.net/",
      "key_name": "<your-key-name>",
      "tenant_id": "<your-tenant-id>"
    }
  }'

La risposta contiene l'ID della chiave esterna:

{
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

Valida la chiave
Attiva un ciclo completo di crittografia e decrittografia sulla tua chiave. Questo conferma che Anthropic può autenticarsi nel tuo tenant ed eseguire operazioni di wrap e unwrap.
curl -sS -X POST https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate \ -H "x-api-key: <anthropic-admin-api-key>" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" -d '{}'
Una risposta di successo ha questo aspetto:
{ "type": "external_key_validation", "status": "success", "error": null }
Se la validazione fallisce, il campo error descrive il problema. Le cause comuni sono:
- Ritardo di propagazione RBAC: le assegnazioni di ruolo possono richiedere alcuni minuti per diventare effettive. Attendi e riprova.
- ACL di rete che bloccano Anthropic: verifica l'accesso alla rete pubblica e le ipRules come descritto nel passaggio di verifica.
- Criteri di accesso condizionale sulle identità dei carichi di lavoro: se il tuo tenant ha criteri di accesso condizionale che hanno come destinazione i service principal, escludi il service principal di Anthropic o aggiungi gli intervalli di egress di Anthropic alle posizioni denominate del criterio.

Collega la chiave a un workspace

Una volta validata la chiave, collegala a un workspace per abilitare CMEK per i dati di quel workspace.

curl -sS -X POST https://api.anthropic.com/v1/organizations/workspaces/<workspace-id> \
  -H "x-api-key: <anthropic-admin-api-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "external_key_id": "ekey_<id>"
  }'