Claude Platform Docs
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.

Prerequisiti

  • Un progetto Google Cloud con fatturazione abilitata.
  • La Cloud KMS API abilitata (cloudkms.googleapis.com).
  • Permessi 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). 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 fare in modo che Anthropic usi 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

Configurazione della chiave di crittografia

  1. 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 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>

  2. 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 crittografia e decrittografia simmetrica e scegli HSM sotto il livello di protezione.

    Pagina Create key di Google Cloud KMS con livello di protezione HSM e scopo Symmetric encrypt/decrypt.
    Crea una chiave simmetrica encrypt/decrypt (crittografia/decrittografia) protetta da HSM.

  3. Concedi all'account di servizio di Anthropic l'accesso alla chiave

    Sono necessari due binding IAM a livello di chiave. Entrambi sono limitati alla singola chiave crittografica, non all'intero progetto o all'intero key ring.

    Crittografia e decrittografia, che Anthropic usa 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 validare 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 dei permessi della chiave, non del key ring o del progetto, in modo che la concessione sia limitata solo a questa chiave.

    Finestra di dialogo Grant access con l'account di servizio Anthropic a cui sono assegnati i ruoli Cloud KMS CryptoKey Encrypter/Decrypter e Viewer.
    Concedi all'account di servizio Anthropic entrambi i ruoli tramite Grant access (concedi accesso), limitati alla chiave.

  4. 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.

    Dettagli del key ring di Google Cloud con l'azione Copy resource name evidenziata nel menu delle azioni della chiave.
    Copia il nome completo della risorsa della chiave con Copy resource name (copia nome risorsa) dal menu delle azioni.

Registra la chiave con Anthropic

Il modo in cui registri la chiave dipende dal prodotto che usi.

  1. Registra la chiave con Anthropic

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

    client = anthropic.Anthropic()

external_key = client.beta.organization.external_keys.create(
    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>",
    },
)

print(f"id: {external_key.id}")
print(f"display_name: {external_key.display_name}")

    La risposta contiene l'ID della chiave esterna:

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

  2. Valida la chiave

    Attiva un ciclo completo di crittografia e decrittografia sulla tua chiave.

    client = anthropic.Anthropic()

validation = client.beta.organization.external_keys.validate("ekey_<id>")

print(f"status: {validation.status}")
print(f"error: {validation.error}")

    Una risposta riuscita ha questo aspetto:

    { "type": "external_key_validation", "status": "success", "error": null }

    Se la validazione 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 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.

  3. Associa la chiave a un workspace

    Una volta validata la chiave, associala a un nuovo workspace prima di inviare qualsiasi richiesta a quel workspace. Per un workspace che riceve già richieste, la chiave può richiedere fino a un giorno per entrare in vigore.

    client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.update(
    "<workspace-id>", external_key_id="ekey_<id>"
)

print(f"id: {workspace.id}")
print(f"external_key_id: {workspace.external_key_id}")

Terraform

Per i deployment infrastructure-as-code (infrastruttura come codice), 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?