AmministrazioneChiavi di crittografia

Configurare Google Cloud KMS per CMEK

Usa 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 (chiave di crittografia gestita dal cliente), o CMEK 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 gli avvisi e le limitazioni prima di iniziare.

Prerequisiti

Un progetto Google Cloud con la fatturazione abilitata.
L'API Cloud KMS abilitata (cloudkms.googleapis.com).
Le autorizzazioni per creare key ring e chiavi KMS, e per impostare i criteri 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 voci in Cloud Logging.

Email dell'account di servizio Anthropic

Per far sì che 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

Usa solo 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 sotto un'organizzazione Google Cloud che applica constraints/iam.allowedPolicyMemberDomains, i seguenti binding IAM vengono rifiutati perché l'account di servizio Anthropic è esterno alla tua organizzazione. Hai bisogno di un'eccezione a livello di progetto su quel vincolo, oppure di aggiungere l'ID cliente Cloud Identity di Anthropic (formato C0xxxxxxxx) all'elenco consentito. Contatta Anthropic per 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à US a regione singola 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. Anthropic raccomanda fortemente la protezione HSM: 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 la protezione software invece, 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 symmetric encrypt and decrypt, 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 hanno come ambito la singola chiave crittografica, non l'intero progetto o l'intero key ring.
Encrypt e decrypt, che Anthropic usa per crittografare e decrittografare le chiavi dati che proteggono i dati del tuo workspace (crittografia a busta):
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 abbia come ambito solo questa chiave.
Concedi all'account di servizio Anthropic entrambi i ruoli, con ambito limitato alla chiave.
Annota il nome completo della risorsa della 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 della chiave dal menu delle azioni.

Registra la chiave con Anthropic

Il modo in cui registri la 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 della 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 appare così:
{ "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: il criterio dell'organizzazione constraints/iam.allowedPolicyMemberDomains può rimuovere il binding dell'account di servizio Anthropic (vedi la nota precedente). Conferma 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: conferma che la versione primaria della chiave sia abilitata, e non disabilitata, pianificata per la distruzione o distrutta.

Collega 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 i deployment 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 la fatturazione abilitata.

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

Le autorizzazioni per creare key ring e chiavi KMS, e per impostare i criteri 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 voci in Cloud Logging.

Email dell'account di servizio Anthropic

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

Usa solo 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à US a regione singola 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. Anthropic raccomanda fortemente la protezione HSM: 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 la protezione software invece, 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 symmetric encrypt and decrypt, 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 hanno come ambito la singola chiave crittografica, non l'intero progetto o l'intero key ring.
Encrypt e decrypt, che Anthropic usa per crittografare e decrittografare le chiavi dati che proteggono i dati del tuo workspace (crittografia a busta):
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 abbia come ambito solo questa chiave.
Concedi all'account di servizio Anthropic entrambi i ruoli, con ambito limitato alla chiave.
Annota il nome completo della risorsa della 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 della chiave dal menu delle azioni.

Registra la chiave con Anthropic

Il modo in cui registri la 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 appare così:
{ "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: il criterio dell'organizzazione constraints/iam.allowedPolicyMemberDomains può rimuovere il binding dell'account di servizio Anthropic (vedi la nota precedente). Conferma 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: conferma che la versione primaria della chiave sia abilitata, e non disabilitata, pianificata per la distruzione o distrutta.

Collega 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