Aggiunta di restrizioni alle chiavi API

Le chiavi API identificano l'applicazione o il sito web in Google Cloud. Le limitazioni relative alle chiavi API assicurano che solo le tue app e i tuoi siti web possano utilizzare le tue chiavi. Per motivi di sicurezza, ti consigliamo di aggiungere restrizioni che specificano:

I client o i siti web che possono utilizzare le tue chiavi API.
Le API di Google Cloud che la tua applicazione può effettuare chiamate utilizzando le tue chiavi API.

Se un client utilizza una chiave API con restrizioni per inviare una richiesta che non soddisfa le restrizioni della chiave API, la richiesta non riesce. Ad esempio, se una chiave API richiede l'emissione di richieste HTTP da un dominio specifico ma una richiesta HTTP viene ricevuta da un dominio diverso, la richiesta verrà rifiutata con un errore.

Puoi aggiungere limitazioni quando crei una chiave API con il metodo CreateKey oppure puoi aggiungere le restrizioni dopo la creazione della chiave con il metodo UpdateKey. Questa pagina descrive le restrizioni che puoi aggiungere a una chiave API e mostra come aggiungerle.

Prima di iniziare

La pagina utilizza curl con lo strumento a riga di comando oauth2l per inviare richieste all'API Chiavi API. Consulta la Guida introduttiva alle chiavi API per i dettagli su come configurare gli esperimenti con l'API.

Aggiungere limitazioni client

Le restrizioni del client specificano i siti web, gli indirizzi IP o le applicazioni che possono utilizzare una chiave API. Puoi aggiungere limitazioni client in base al tipo di client che chiama la tua API. Puoi specificare uno dei seguenti tipi di restrizioni del cliente:

browserKeyRestrictions: i referrer HTTP (siti web) che possono utilizzare la chiave.
serverKeyRestrictions: gli indirizzi IP dei chiamanti a cui è consentito utilizzare la chiave.
androidKeyRestrictions: le app Android autorizzate a utilizzare la chiave.
iosKeyRestrictions: le app iOS autorizzate a utilizzare la chiave.

Aggiungere limitazioni del browser

Il seguente esempio mostra come chiamare il metodo UpdateKey per limitare il referrer HTTP a www.example.com:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \
  --request PATCH \
  --data '{
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": "www.example.com"
      }
    }
    "etag": "ETAG"
  }'

Quando la risposta di operations.get contiene "done": true, response contiene i Key aggiornati con le limitazioni.

L'esempio riportato di seguito mostra come creare una nuova chiave API che consenta solo richieste HTTP da un elenco di URL specifici.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \
  --request POST \
  --data '{
    "displayName" : "API key with browser restrictions",
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": ["www.example.com", "www.example-2.com"]
      }
    }
  }'

La seguente tabella mostra alcuni scenari di esempio e limitazioni del browser:

Scenario	Limitazioni
Consenti qualsiasi URL nel tuo sito	Devi impostare due URL nell'elenco "AllowerReferences". URL per il dominio, senza un sottodominio e con un carattere jolly per il percorso. Ad esempio: `example.com/` Un secondo URL che include un carattere jolly per il sottodominio e un carattere jolly per il percorso. Ad esempio: `.example.com/*`
Consenti un URL specifico	Aggiungi un URL con un percorso esatto. Ad esempio: `www.example.com/path` `www.example.com/path/path`
Consentire qualsiasi URL in un singolo sottodominio o dominio semplice	Per consentire l'intero dominio, devi impostare due URL nell'elenco "Utenti autorizzati". URL per il dominio, senza barra finale. Ad esempio: `www.example.com` `sub.example.com` `example.com` Un secondo URL per il dominio che include un carattere jolly per il percorso. Ad esempio: `www.example.com/` `sub.example.com/` `example.com/*`

Aggiungere limitazioni del server

Puoi specificare uno o più indirizzi IP dei chiamanti, ad esempio i server web o i cron job che possono utilizzare la chiave API. Puoi specificare gli indirizzi IP in uno dei seguenti formati:

IPv4 (198.51.100.1)
IPv6 (2001:db8::1)
Una subnet utilizzando la notazione CIDR (198.51.100.0/24, 2001:db8::/64)

L'esempio seguente mostra come creare una chiave API con un elenco di allowedIps:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with server restrictions with IPv4, IPv6 and CIDR",
    "restrictions" : {
      "serverKeyRestrictions": {
        "allowedIps": ["198.51.100.1","198.51.100.0/24","2001:db8::1","2001:db8::/64"]
      }
    }
  }'

Aggiungere limitazioni Android

Puoi limitare l'utilizzo di una chiave API solo alle tue app Android. Quando crei o aggiorni una chiave API, fornisci il nome del pacchetto e l'impronta digitale SHA-1 per ogni app.

Supponi, ad esempio, di aver eseguito l'utilità keytool e che abbia creato la seguente impronta:

  Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

L'esempio seguente mostra come creare una chiave API con l'impronta digitale e il nome del pacchetto nel androidKeyRestrictions:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with Android restrictions",
    "restrictions" : {
      "androidKeyRestrictions": {
        "allowedApplications": [
          {
            "sha1Fingerprint": "DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09",
            "packageName": "com.example.my.app"
          }
        ]
      }
    }
  }'

Aggiungere limitazioni iOS

Puoi limitare l'utilizzo di una chiave API solo alle tue app iOS fornendo l'ID bundle di ogni app quando crei o aggiorni una chiave. L'esempio seguente mostra come impostare iosKeyRestrictions quando si crea una chiave API:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with iOs restrictions",
    "restrictions" : {
      "iosKeyRestrictions": {
        "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"]
      }
    }
  }'

Aggiungere restrizioni API

Le restrizioni delle API consentono di specificare quali API di Google Cloud possono essere chiamate utilizzando la chiave API. Consigliamo di aggiungere a entrambe le chiavi API le limitazioni client e API.

Puoi specificare uno o più servizi nelle limitazioni API. L'esempio seguente mostra come limitare l'utilizzo di una nuova chiave API solo ai servizi translate.googleapis.com e datastore.googleapis.com:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
  }'

Per ottenere un elenco di servizi abilitati nel progetto Cloud, utilizza il comando gcloud services list.

Oltre a limitare la chiave API per l'utilizzo a servizi specifici, puoi eventualmente specificare i metodi in ciascun servizio per limitare ulteriormente la chiave API. L'esempio seguente mostra come limitare la chiave precedente solo ai metodi consentiti di translate.googleapis.com:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions  \
  --request PATCH \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
          "methods": [
            "Get*",
            "DetectLanguage"
          ]
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
    "etag": "ETAG"
  }'