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 (log di controllo dell'accesso ai dati) 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 possa utilizzare la tua chiave di crittografia, devi concedere all'account di servizio di Anthropic una chiave che possa utilizzare 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 su tale vincolo, oppure l'aggiunta del customer ID di Cloud Identity di Anthropic (formato C0xxxxxxxx) all'elenco consentito. Contatta Anthropic per ottenere il customer ID, 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 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. La protezione HSM è fortemente consigliata: le chiavi HSM di Cloud KMS sono convalidate 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 all'intero progetto o al key ring.
Crittografia e decrittografia, che Anthropic utilizza per crittografare e decrittografare le chiavi dati che proteggono i dati del tuo workspace (envelope encryption, ovvero 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 trovarti 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 della chiave dal menu delle azioni.

Registra la chiave con Anthropic

Crea una configurazione di chiave esterna tramite l'Admin API, utilizzando il nome della risorsa del passaggio precedente.

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 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 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 (log di controllo dell'accesso ai dati) 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 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. La protezione HSM è fortemente consigliata: le chiavi HSM di Cloud KMS sono convalidate 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 all'intero progetto o al key ring.
Crittografia e decrittografia, che Anthropic utilizza per crittografare e decrittografare le chiavi dati che proteggono i dati del tuo workspace (envelope encryption, ovvero 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 trovarti 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 della chiave dal menu delle azioni.

Registra la chiave con Anthropic

Crea una configurazione di chiave esterna tramite l'Admin API, utilizzando il nome della risorsa del passaggio precedente.

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>"
  }'