Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Gestione e sicurezza delle chiavi API

1. Introduzione

In passato, le chiavi API di Google venivano utilizzate per accedere alle API di Google quando altri metodi non erano disponibili o erano considerati scomodi. I casi d'uso più comuni erano l'accesso all'API di Google Maps e alle API di Google esposte da Firebase. Con l'introduzione di modelli di AI, agenti di AI come Gemini e framework di sviluppo di AI Studio e agenti come Agent Development Kit, le chiavi API sono diventate un metodo principale per accedere ai modelli linguistici di grandi dimensioni di Google.

Le chiavi API offrono un basso livello di protezione. Sebbene Google Cloud fornisca diversi metodi per impedire l'uso improprio delle chiavi, il possesso di una chiave API attiva consente l'accesso alle API di Google senza ulteriori convalide di autenticazione o autorizzazione. I metodi per limitare l'utilizzo delle chiavi API sono descritti nella documentazione. Il post Protezione delle chiavi API Gemini e Google nel blog di Cloud fornisce ulteriori consigli sulla manutenzione delle chiavi API. In questo codelab metterai in pratica questi consigli.

In questo lab proverai a:

Esamina le limitazioni applicate durante la creazione di nuove chiavi API su Google Cloud
Catalogare tutte le chiavi API e trovare quelle senza protezione di sicurezza
Applica restrizioni alle chiavi API esistenti in base al loro utilizzo
Definisci l'automazione che elimina la chiave in caso di utilizzo anomalo

Che cosa ti serve

Un browser web moderno (ad esempio Chrome).
Un Account Google

2. Configurazione

Le istruzioni di questo codelab presuppongono che tu esegua i comandi in Cloud Shell nella console Google Cloud. Se hai gcloud CLI nel tuo ambiente locale, puoi eseguire i comandi lì.

Sebbene le operazioni nei passaggi possano essere eseguite utilizzando la UI della console Cloud, i metodi sono diversi. Questo codelab utilizza l'interfaccia a riga di comando per semplificare le interazioni e consentire un'integrazione più semplice con gli agenti AI moderni (come Antigravity CLI).

Avvia un terminale Cloud Shell.

Apri la console Google Cloud utilizzando https://console.cloud.google.com/ in una nuova finestra del browser. Per un'esperienza utente ottimale, ti consigliamo di utilizzare Chrome.
Accedi al tuo Account Google in Google Cloud.
Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
Se visualizzate, fai clic nelle seguenti finestre:
- Continua nella finestra delle informazioni di Cloud Shell.
- Autorizza Cloud Shell a utilizzare le tue credenziali per effettuare chiamate API Google Cloud.

Seleziona un progetto Google Cloud

Dopo aver aperto la console Cloud, l'autenticazione viene eseguita e in genere viene selezionato un progetto per il tuo lavoro. L'ID progetto è una sequenza di 6-30 caratteri composta da lettere minuscole, numeri e simboli trattino, ad esempio qwiklabs-gcp-04-3075fc9fd77f. Il terminale Cloud Shell configura l'interfaccia a riga di comando gcloud con il progetto selezionato. Vedrai un output simile al seguente:

Your Cloud Platform project in this session is set to qwiklabs-gcp-04-3075fc9fd77f

Ciò significa che i comandi successivi a gcloud utilizzeranno l'ID progetto qwiklabs-gcp-04-3075fc9fd77f.

Imposta l'ID progetto come variabile di ambiente PROJECT_ID. Puoi visualizzare l'elenco di tutti i tuoi progetti utilizzando il seguente comando:

gcloud projects list

Sostituisci your-project-id ed esegui il comando se vuoi utilizzare un ID progetto diverso da quello configurato in gcloud.
```
export PROJECT_ID="your-project-id"
```
Ad esempio:
```
export PROJECT_ID="qwiklabs-gcp-04-3075fc9fd77f"
```
Esegui questo comando se vuoi utilizzare l'ID progetto selezionato:
```
export PROJECT_ID=$(gcloud config get project)
```

3. Limitare una nuova chiave API

In passato, gli utenti potevano creare chiavi API senza alcuna limitazione. Le chiavi senza restrizioni possono essere utilizzate per chiamare QUALSIASI API Google abilitata nel progetto in cui è stata creata la chiave. Anche se la console Google Cloud impedisce agli utenti di creare chiavi senza restrizioni, è comunque possibile utilizzare l'interfaccia a riga di comando gcloud o effettuare chiamate API dirette.

I passaggi riportati di seguito mostrano come creare una chiave API con limitazioni che limita l'utilizzo all'API specifica e al sito web specificato.

Per creare una nuova chiave API limitata all'utilizzo con l'API Google Maps Geolocation, esegui il seguente comando nel terminale della shell:
```
gcloud services api-keys create --key-id=restricted-api-key \
  --display-name="restricted api key" \
  --api-target=service=geolocation.googleapis.com \
  --project=${PROJECT_ID}
```
Questo comando crea una nuova chiave API che può essere utilizzata SOLO per chiamare il servizio di geolocalizzazione di Google Maps.
ℹ️ Nota:è possibile aggiungere più API all'elenco con limitazioni. Utilizza più parametri --api-target con un valore =service=SERVICE.googleapis.com, dove SERVICE è uno dei servizi Google.
Aumenta la sicurezza della chiave aggiungendo una limitazione dell'applicazione. Limita l'utilizzo della chiave a tutti i percorsi all'interno del sito web example.com. Esegui questo comando per aggiungere la limitazione dell'applicazione alla chiave:
```
gcloud services api-keys update restricted-api-key \
  --location=global \
  --allowed-referrers="example.com/*" \
  --project=${PROJECT_ID}
```
Anziché consentire l'utilizzo della chiave per siti web specifici, puoi utilizzare --allowed-application per definire le app per Android consentite oallowed-ips per definire gli indirizzi IP consentiti. Per tutte le opzioni, consulta la documentazione completa.
ℹ️ Nota:è possibile aggiungere più di una limitazione delle applicazioni dello STESSO tipo fornendo più parametri (ad es. --allowed-referrers). Se aggiungi più tipi di limitazioni delle applicazioni, nell'elenco dei parametri verrà salvato solo l'ultimo tipo.

Esegui la pulizia

Elimina la chiave API che hai creato, a meno che tu non preveda di utilizzarla:

gcloud services api-keys delete --key-id=restricted-api-key \
  --project=${PROJECT_ID}

4. Catalogare le chiavi API

In questo passaggio utilizzerai la CLI gcloud per ottenere un inventario delle tue chiavi API. L'elenco risultante mostra tutte le chiavi API attive (non eliminate) a cui hai accesso.

Esegui questo comando per visualizzare tutti i nomi delle chiavi, gli ID e le date di creazione:
```
gcloud services api-keys list --project=${PROJECT_ID} \
  --format='value(displayName,name.basename(),createTime.date())'
```
L'output mostrerà il nome leggibile della chiave, l'ID chiave e la data di creazione della chiave. Sarà simile al seguente:
```
api key 1	api-key-1	2024-05-10T07:53:24
api key 2	api-key-2	2025-06-12T14:47:57
```
Scegli uno degli ID chiave e incolla il seguente comando per verificare se la chiave presenta restrizioni. Sostituisci your-key-id con il valore dell'ID chiave selezionato:
```
gcloud services api-keys describe "your-key-id" --project=${PROJECT_ID}
```

L'output (in YAML) conterrà un elenco di limitazioni in restrictions.

createTime: '2024-05-10T07:53:24.986528Z'
displayName: api key 1
etag: W/"u1WuY41K2tPKUZd7cfLoKg=="
name: projects/123456789012/locations/global/keys/api-key-1
restrictions:
  apiTargets:
  - service: geolocation.googleapis.com
  browserKeyRestrictions:
    allowedReferrers:
    - https://example.com/*
uid: 1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6
updateTime: '2024-05-10T07:53:24.071228Z'

Tieni presente che se la chiave non è mai stata aggiornata, i campi createTime e updateTime avranno lo stesso timestamp.

Scarica ed esegui lo script che esamina tutti i tuoi progetti e stampa tutte le chiavi API che NON hanno restrizioni:

curl -fsSL -o unrestricted_api_keys.sh \
  "https://github.com/GoogleCloudPlatform/devrel-demos/blob/main/security/api-key-audit/unrestricted_api_keys.sh"
chmod +x unrestricted_api_keys.sh
./unrestricted_api_keys.sh

Dopo aver eseguito lo script, vedrai un output nel formato:

DISPLAY NAME    KEY ID    PROJECT ID    CREATION DATE
Key 1    1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6    my-project-1    2024-05-10T07:53:24.071228Z

Puoi trovare tutti gli script utilizzati in questo CodeLab nella cartella Security del repository devrel-demos su GitHub.

5. Scopri l'utilizzo di una chiave API

In questo passaggio eseguirai una query sulle metriche di Google Cloud che ti aiutano a trovare le API chiamate utilizzando la tua chiave API. Utilizzando queste informazioni, puoi esaminare l'utilizzo attuale delle chiavi e applicare restrizioni API alla chiave in base a informazioni reali anziché fare ipotesi.

Utilizza lo stesso ID chiave utilizzato nel passaggio precedente o scegline un altro. Sostituisci your-key-id con l'ID chiave scelto nel comando seguente:
```
export KEY_UID=$(
   gcloud services api-keys describe "your-key-id" \
   --format='value(uid)' \
   --project=${PROJECT_ID})
```
Imposta la ricerca in modo che esamini la cronologia di utilizzo di un anno. Se vuoi cercare un periodo di tempo più lungo o più breve, sostituisci 365 (numero di giorni) con un altro numero positivo.
```
export DAYS=365
```
Aggiorna le credenziali predefinite dell'applicazione (ADC) per abilitare la chiamata diretta all'API Cloud Monitoring. Esegui questo comando e segui le istruzioni nel terminale:
```
gcloud auth application-default login
```
Esegui questo comando per inviare una richiesta di dati delle metriche di utilizzo del servizio all'API Cloud Monitoring:

curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  --data-urlencode "filter=metric.type=\"serviceruntime.googleapis.com/api/request_count\" AND resource.labels.credential_id=\"apikey:${KEY_UID}\"" \
  --data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)" \
  --data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  "https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries" \
  | jq -r '.timeSeries[]?.resource.labels.service' | sort -u

Il comando esegue una query sulla metrica integrata serviceruntime/api/request_count per i punti dati con l'etichetta credential_id che corrispondono all'ID univoco della chiave API scelta. Poi recupera i valori dell'etichetta service e li stampa eliminando le ripetizioni.

Protezione della chiave API

In questo passaggio utilizzerai le informazioni raccolte nei passaggi precedenti per aggiornare la configurazione delle limitazioni della chiave API in base alle informazioni sull'utilizzo.

Utilizzerai la stessa chiave API utilizzata nel passaggio precedente. Se necessario, esegui nuovamente le istruzioni dei passaggi precedenti per assicurarti che le variabili di ambiente PROJECT_ID, KEY_UID e DAYS siano impostate.

Esegui questo comando per recuperare l'elenco delle API di Google chiamate utilizzando la chiave API:

SERVICES=$(curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
–data-urlencode "filter=metric.type="serviceruntime.googleapis.com/api/request_count" AND resource.labels.credential_id="apikey:${KEY_UID}""
–data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)"
–data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
"https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries"
| jq -r ‘.timeSeries[]?.resource.labels.service' | sort -u)

1. Build the list of arguments to restrict the API usage for the API key based
on the retrieved list.

```shell
API_TARGET_ARGS=()
for SERVICE in $SERVICES; do
  API_TARGET_ARGS+=("--api-target=service=${SERVICE}")
done

Sostituisci l'elenco delle API limitate con l'elenco non vuoto:

if [ ${#API_TARGET_ARGS[@]} -gt 0 ]; then
    gcloud services api-keys update "projects/${PROJECT_ID}/locations/global/keys/${KEY_UID}" \
    ${API_TARGET_ARGS}
fi

6. Definisci il rilevamento dell'utilizzo anomalo

I passaggi precedenti hanno mostrato come esplorare e proteggere le chiavi API. Questo passaggio mostra come automatizzare una risposta al picco inatteso di utilizzo della chiave con l'aiuto degli avvisi di monitoraggio.

Le seguenti istruzioni creano un avviso che viene attivato quando la frequenza delle chiamate API che utilizzano una chiave API aumenta di oltre il 10% negli ultimi 5 minuti. L'avviso è configurato per attivare uno script Cloud Build che elimina la chiave API per impedirne l'ulteriore utilizzo. La chiave può essere ripristinata nei prossimi 30 giorni. Consulta la documentazione per scoprire come recuperare la chiave.

Le istruzioni riutilizzano le variabili PROJECT_ID e KEY_UID che hai utilizzato nei passaggi precedenti. Se vuoi selezionare una chiave e/o un progetto diversi, imposta i nuovi valori per queste variabili come descritto nei passaggi Configurazione e scoperta dell'utilizzo di una chiave API.

Esegui il seguente script per creare un file di criteri di avviso:

cat <<EOF > alert_policy.json
{
  "displayName": "Credential API Request Count Increase Alert (Project: ${PROJECT_ID})",
  "combiner": "OR",
  "conditions": [
    {
      "displayName": "API Request Count Increase > 10% in 5m with Min Volume",
      "conditionPrometheusQueryLanguage": {
        "query": "(sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) / (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m] offset 5m)) or on() vector(1)) > 1.10) and (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) > 50)",
        "duration": "0s",
        "evaluationInterval": "60s"
      }
    }
  ],
  "enabled": true
}
EOF

La policy di avviso utilizza il seguente filtro PromQL per attivare l'avviso:

 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m])
 ) /
 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m] offset 5m)
 ) or on() vector(1)) > 1.10)
and
 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\"YOUR_CREDENTIAL_ID_HERE\"}[5m])) > 50)

Calcola il tasso di aumento e lo confronta con una finestra precedente. e attiva l'avviso solo se è superiore di oltre il 10%. Per evitare di attivare l'avviso quando il numero totale di chiamate è trascurabile, la condizione di attivazione prevede più di 50 chiamate API nella finestra. Per evitare il calcolo della divisione per zero quando la frequenza di 5 minuti precedente era 0, il denominatore viene sostituito con 1 se la frequenza della finestra precedente è zero.Puoi modificare i parametri dell'avviso, ad esempio la durata della finestra (5m), la soglia minima (50) o la soglia di aumento del 10% (1.10).I parametri aggiuntivi dei criteri definiscono che, una volta raggiunta la condizione, l'avviso deve essere attivato (duration) e che la condizione deve essere verificata ogni 60 secondi (evaluationInterval).NaN

Esegui il comando seguente per creare un argomento Pub/Sub che verrà utilizzato per pubblicare le notifiche di avviso:
```
gcloud pubsub topics create api-key-alert-notifications --project=$PROJECT_ID
```

Esegui il comando seguente per creare un canale di notifica per gli avvisi che utilizza Pub/Sub.

CHANNEL_NAME=$(gcloud beta monitoring channels create \
  --display-name="Pub/Sub Alert Channel" \
  --type="pubsub" \
  --channel-labels="topic=projects/$PROJECT_ID/topics/api-key-alert-notifications" \
  --format='value(name)' \
  --project=$PROJECT_ID)

Utilizzerai la variabile di ambiente CHANNEL_NAME nel passaggio di pulizia.

Esegui questo comando per creare un nuovo avviso di monitoraggio:

gcloud monitoring policies create --policy-from-file=alert_policy.json \
  --project=$PROJECT_ID

Esegui questo comando per concedere al servizio Cloud Build le autorizzazioni per eliminare le chiavi API nel progetto.
```
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/apikeys.admin"
```
È possibile limitare il ruolo apikeys.admin alla manipolazione solo di istanze specifiche delle chiavi API. Per ulteriori dettagli, consulta la pagina Condizioni IAM.

Esegui il seguente script per creare un trigger di build Cloud Build che elimini la chiave API.

cat <<EOF > trigger_config.yaml
name: "delete-compromised-api-key"
description: "Triggered by Pub/Sub alert to automatically delete the leaking API Key"
pubsubConfig:
  topic: "projects/${PROJECT_ID}/topics/api-key-alert-notifications"
build:
  steps:
  - name: "gcr.io/google.com/cloudsdktool/cloud-sdk:slim"
    args:
    - "gcloud"
    - "services"
    - "api-keys"
    - "delete"
    - "${KEY_UID}"
    - "--quiet"
EOF

Esegui questo comando per creare un nuovo trigger di avviso di monitoraggio:

gcloud builds triggers create pubsub \
  --trigger-config=trigger_config.yaml \
  --project=$PROJECT_ID

Ora puoi eliminare i file di configurazione del criterio di avviso e del trigger di Cloud Build:

rm alert_policy.json trigger_config.yaml

In alternativa, puoi configurare questa automazione utilizzando il piano Terraform. Scarica i file Terraform dalla cartella abnormal-usage-detection nel repository Google Cloud DevRel. Il piano accetta un ID progetto e un UID chiave API come parametri di input e configura le risorse e le configurazioni che hai visto in questo passaggio.

7. Esegui la pulizia

Per evitare addebiti imprevisti sul tuo account Google Cloud, ricorda di eliminare l'argomento Pub/Sub, il trigger di build di Cloud Build e i criteri di avviso creati durante questo esercizio.

Esegui i seguenti comandi per eliminare tutte le risorse che hai creato:

gcloud builds triggers delete delete-compromised-api-key \
  --project=$PROJECT_ID
gcloud beta monitoring channels delete $CHANNEL_NAME \
  --project=$PROJECT_ID \
  --quiet
gcloud pubsub topics delete api-key-alert-notifications \
  --project=$PROJECT_ID
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/apikeys.admin"

8. Riepilogo

In questo codelab hai implementato un framework di automazione e sicurezza end-to-end solido per le chiavi API di Google Cloud:

Configurazioni predefinite rafforzate: hai creato e limitato le chiavi API per limitare l'accesso esclusivamente alle API necessarie e alle piattaforme attendibili (ad esempio referrer HTTP specifici).
Inventario delle chiavi sottoposto ad audit: hai eseguito la scansione degli ambienti del progetto per rilevare e isolare le chiavi senza restrizioni che presentano un rischio immediato per la sicurezza.
Dati di utilizzo analizzati: hai eseguito query a livello di programmazione sui dati delle metriche di Cloud Monitoring per profilare l'utilizzo storico delle chiavi, consentendoti di limitare le chiavi in base alle impronte di utilizzo verificate.
Mitigazione automatica delle minacce: hai creato un "interruttore di sicurezza" reattivo collegando una policy di avviso di Cloud Monitoring a un argomento Pub/Sub e a un trigger di build di Cloud Build, in modo da eliminare automaticamente le chiavi compromesse durante i picchi di traffico anomali.

Passaggi successivi

Applica limitazioni a tutte le tue chiavi API: utilizza ciò che hai imparato in questo lab per rilevare tutte le chiavi API parzialmente limitate o senza limitazioni e applica limitazioni API e client.
Configura l'interruttore di sicurezza per le chiavi API: proteggi ulteriormente le tue chiavi API da un utilizzo imprevisto configurando l'eliminazione automatica delle chiavi in caso di aumento improvviso del consumo. Utilizza i comandi gcloud o Terraform mostrati nel lab. Valuta la possibilità di rafforzare le autorizzazioni utilizzando le condizioni IAM.
Esplora gli avvisi di Monitoring: scopri di più sulla configurazione degli avvisi utilizzando il servizio Google Cloud Monitoring.
Scopri di più sul controllo dell'accesso disponibile su Google Cloud: consulta i criteri perimetrali di accesso e la propagazione delle modifiche all'accesso.