AmministrazioneChiavi di crittografia

Configurare Google Cloud KMS per CMEK

Utilizza Google Cloud KMS 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 Google Cloud KMS"

Questa guida illustra come configurare una chiave Google Cloud KMS come customer-managed encryption key (CMEK), ovvero chiave di crittografia gestita dal cliente, per la tua organizzazione Anthropic.

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

Prerequisiti

Un progetto Google Cloud con fatturazione abilitata.
L'API Cloud KMS abilitata (cloudkms.googleapis.com).
Autorizzazioni per creare key ring e chiavi KMS e per impostare policy IAM su di essi (roles/cloudkms.admin o equivalente).
Una chiave API Admin di Anthropic per la tua organizzazione.
La CLI gcloud installata e autenticata.
I Data Access audit logs di Cloud KMS abilitati per il progetto (IAM & Admin > Audit Logs > Cloud Key Management Service, con DATA_READ e DATA_WRITE). Questi sono disattivati per impostazione predefinita; senza di essi, le operazioni di crittografia e decrittografia di Anthropic non producono alcuna voce in Cloud Logging.

Email dell'account di servizio Anthropic

Affinché Anthropic utilizzi la tua chiave di crittografia, devi fornire all'account di servizio di Anthropic una chiave che possa usare per crittografare i dati. L'email dell'account di servizio per Anthropic CMEK è:

anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com

Utilizza esclusivamente questa email dell'account di servizio pubblicata. Non fidarti mai di un identificatore fornito tramite email, chat o qualsiasi canale di onboarding.

Condivisione limitata al dominio: se il tuo progetto si trova in un'organizzazione Google Cloud che applica constraints/iam.allowedPolicyMemberDomains, i binding IAM riportati di seguito vengono rifiutati perché l'account di servizio Anthropic è esterno alla tua organizzazione. È necessaria un'eccezione a livello di progetto per tale vincolo, oppure devi aggiungere l'ID cliente Cloud Identity di Anthropic (formato C0xxxxxxxx) all'elenco consentito. Contatta Anthropic per ottenere l'ID cliente, se necessario.

Configurazione della chiave di crittografia

Crea o scegli un key ring
Salta questo passaggio se hai già un key ring da riutilizzare. I key ring sono regionali. Scegli una località statunitense a singola regione come us-east5 che corrisponda all'area geografica Anthropic che stai configurando. Le località multi-regione come us e global non sono supportate.
gcloud kms keyrings create <your-keyring-name> \ --project=<your-project-id> \ --location=<region>
Crea la chiave crittografica
Crea una chiave simmetrica con lo scopo ENCRYPT_DECRYPT. La protezione HSM è fortemente consigliata: le chiavi HSM di Cloud KMS sono validate FIPS 140-2 Level 3 e la differenza di costo rispetto alle chiavi software è minima.
gcloud kms keys create <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --purpose=encryption \ --protection-level=hsm
Per utilizzare invece la protezione software, ometti --protection-level=hsm. Nient'altro in questa guida cambia.
Puoi anche creare la chiave dalla Google Cloud Console. Apri il key ring, fai clic su Create key, seleziona Generated key, imposta lo scopo e l'algoritmo su crittografia e decrittografia simmetrica e scegli HSM come livello di protezione.
Crea una chiave simmetrica di crittografia/decrittografia protetta da HSM.
Concedi all'account di servizio di Anthropic l'accesso alla chiave
Sono richiesti due binding IAM a livello di chiave. Entrambi sono limitati alla singola chiave crittografica, non a livello di progetto o di key ring.
Crittografia e decrittografia, che Anthropic utilizza per crittografare e decrittografare le chiavi dati che proteggono i dati del tuo workspace (envelope encryption):
gcloud kms keys add-iam-policy-binding <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \ --role=roles/cloudkms.cryptoKeyEncrypterDecrypter
Viewer, per la lettura dei metadati (cryptoKeys.get) che Anthropic esegue all'avvio per convalidare lo scopo e l'algoritmo della chiave:
gcloud kms keys add-iam-policy-binding <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \ --role=roles/cloudkms.viewer
Dalla Console, seleziona la chiave, apri il pannello Permissions, fai clic su Grant access e aggiungi l'account di servizio con entrambi i ruoli Cloud KMS CryptoKey Encrypter/Decrypter e Cloud KMS Viewer. Assicurati di essere nella pagina delle autorizzazioni della chiave, non del key ring o del progetto, in modo che la concessione sia limitata solo a questa chiave.
Concedi all'account di servizio Anthropic entrambi i ruoli, limitati alla chiave.
Annota il nome completo della risorsa chiave
Lo passerai ad Anthropic quando registri la chiave. Il formato è:
```
projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>
```
Recuperalo con:
gcloud kms keys describe <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --format="value(name)"
Dalla Console, apri la pagina dei dettagli della chiave e fai clic su Copy resource name.
Copia il nome completo della risorsa chiave dal menu delle azioni.

Registra la chiave con Anthropic

La modalità di registrazione della chiave dipende dal prodotto che utilizzi.

Registra la chiave con Anthropic

Crea una configurazione di chiave esterna tramite l'Admin API, utilizzando il nome della risorsa ottenuto nel passaggio Annota il nome completo della risorsa chiave nella sezione Configurazione della chiave di crittografia.

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": "gcp",
      "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
    }
  }'

La risposta contiene l'ID della chiave esterna:

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

Convalida la chiave
Attiva un ciclo completo di crittografia e decrittografia sulla tua chiave.
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 riuscita ha questo aspetto:
{ "type": "external_key_validation", "status": "success", "error": null }
Se la convalida fallisce, le cause comuni sono:
- VPC Service Controls: se un perimetro di servizio protegge Cloud KMS nel tuo progetto, aggiungi Anthropic a un livello di accesso sul perimetro (o escludi il progetto della chiave) in modo che Anthropic possa raggiungere la chiave.
- Condivisione limitata al dominio: la policy dell'organizzazione constraints/iam.allowedPolicyMemberDomains può rimuovere il binding dell'account di servizio Anthropic (vedi la nota sopra). Verifica che il binding sia presente con gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name>.
- Versione della chiave disabilitata o distrutta: verifica che la versione primaria della chiave sia abilitata e non disabilitata, pianificata per la distruzione o distrutta.

Associa la chiave a un 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 le distribuzioni infrastructure-as-code, gli stessi passaggi corrispondono al provider google con le risorse google_kms_key_ring, google_kms_crypto_key e google_kms_crypto_key_iam_member.

Was this page helpful?

Prerequisiti

Un progetto Google Cloud con fatturazione abilitata.

L'API Cloud KMS abilitata (cloudkms.googleapis.com).

Autorizzazioni per creare key ring e chiavi KMS e per impostare policy IAM su di essi (roles/cloudkms.admin o equivalente).

Una chiave API Admin di Anthropic per la tua organizzazione.

La CLI gcloud installata e autenticata.

I Data Access audit logs di Cloud KMS abilitati per il progetto (IAM & Admin > Audit Logs > Cloud Key Management Service, con DATA_READ e DATA_WRITE). Questi sono disattivati per impostazione predefinita; senza di essi, le operazioni di crittografia e decrittografia di Anthropic non producono alcuna voce in Cloud Logging.

Email dell'account di servizio Anthropic

anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com

Utilizza esclusivamente questa email dell'account di servizio pubblicata. Non fidarti mai di un identificatore fornito tramite email, chat o qualsiasi canale di onboarding.

Configurazione della chiave di crittografia

Crea o scegli un key ring
Salta questo passaggio se hai già un key ring da riutilizzare. I key ring sono regionali. Scegli una località statunitense a singola regione come us-east5 che corrisponda all'area geografica Anthropic che stai configurando. Le località multi-regione come us e global non sono supportate.
gcloud kms keyrings create <your-keyring-name> \ --project=<your-project-id> \ --location=<region>
Crea la chiave crittografica
Crea una chiave simmetrica con lo scopo ENCRYPT_DECRYPT. La protezione HSM è fortemente consigliata: le chiavi HSM di Cloud KMS sono validate FIPS 140-2 Level 3 e la differenza di costo rispetto alle chiavi software è minima.
gcloud kms keys create <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --purpose=encryption \ --protection-level=hsm
Per utilizzare invece la protezione software, ometti --protection-level=hsm. Nient'altro in questa guida cambia.
Puoi anche creare la chiave dalla Google Cloud Console. Apri il key ring, fai clic su Create key, seleziona Generated key, imposta lo scopo e l'algoritmo su crittografia e decrittografia simmetrica e scegli HSM come livello di protezione.
Crea una chiave simmetrica di crittografia/decrittografia protetta da HSM.
Concedi all'account di servizio di Anthropic l'accesso alla chiave
Sono richiesti due binding IAM a livello di chiave. Entrambi sono limitati alla singola chiave crittografica, non a livello di progetto o di key ring.
Crittografia e decrittografia, che Anthropic utilizza per crittografare e decrittografare le chiavi dati che proteggono i dati del tuo workspace (envelope encryption):
gcloud kms keys add-iam-policy-binding <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \ --role=roles/cloudkms.cryptoKeyEncrypterDecrypter
Viewer, per la lettura dei metadati (cryptoKeys.get) che Anthropic esegue all'avvio per convalidare lo scopo e l'algoritmo della chiave:
gcloud kms keys add-iam-policy-binding <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \ --role=roles/cloudkms.viewer
Dalla Console, seleziona la chiave, apri il pannello Permissions, fai clic su Grant access e aggiungi l'account di servizio con entrambi i ruoli Cloud KMS CryptoKey Encrypter/Decrypter e Cloud KMS Viewer. Assicurati di essere nella pagina delle autorizzazioni della chiave, non del key ring o del progetto, in modo che la concessione sia limitata solo a questa chiave.
Concedi all'account di servizio Anthropic entrambi i ruoli, limitati alla chiave.
Annota il nome completo della risorsa chiave
Lo passerai ad Anthropic quando registri la chiave. Il formato è:
```
projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>
```
Recuperalo con:
gcloud kms keys describe <your-key-name> \ --project=<your-project-id> \ --location=<region> \ --keyring=<your-keyring-name> \ --format="value(name)"
Dalla Console, apri la pagina dei dettagli della chiave e fai clic su Copy resource name.
Copia il nome completo della risorsa chiave dal menu delle azioni.

Registra la chiave con Anthropic

La modalità di registrazione della chiave dipende dal prodotto che utilizzi.

Registra la chiave con Anthropic

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": "gcp",
      "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>"
    }
  }'

La risposta contiene l'ID della chiave esterna:

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

Convalida la chiave
Attiva un ciclo completo di crittografia e decrittografia sulla tua chiave.
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 riuscita ha questo aspetto:
{ "type": "external_key_validation", "status": "success", "error": null }
Se la convalida fallisce, le cause comuni sono:
- VPC Service Controls: se un perimetro di servizio protegge Cloud KMS nel tuo progetto, aggiungi Anthropic a un livello di accesso sul perimetro (o escludi il progetto della chiave) in modo che Anthropic possa raggiungere la chiave.
- Condivisione limitata al dominio: la policy dell'organizzazione constraints/iam.allowedPolicyMemberDomains può rimuovere il binding dell'account di servizio Anthropic (vedi la nota sopra). Verifica che il binding sia presente con gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name>.
- Versione della chiave disabilitata o distrutta: verifica che la versione primaria della chiave sia abilitata e non disabilitata, pianificata per la distruzione o distrutta.

Associa la chiave a un 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>"
  }'

Prerequisiti

Email dell'account di servizio Anthropic

Configurazione della chiave di crittografia

Registra la chiave con Anthropic

Terraform

Prerequisiti

Email dell'account di servizio Anthropic

Configurazione della chiave di crittografia

Registra la chiave con Anthropic

Terraform

Prerequisiti

Email dell'account di servizio Anthropic

Configurazione della chiave di crittografia

Registra la chiave con Anthropic

Terraform

Prerequisiti

Email dell'account di servizio Anthropic

Configurazione della chiave di crittografia

Registra la chiave con Anthropic

Terraform