Aggiunta di restrizioni alle chiavi API

Le chiavi API identificano la tua applicazione o il tuo sito web per Google Cloud. Le limitazioni delle chiavi API garantiscono 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 specifichino:

Quali client o siti web possono utilizzare le tue chiavi API.
Le API Google Cloud che la tua applicazione può chiamare utilizzando le tue chiavi API.

Se un client utilizza una chiave API con limitazioni per inviare una richiesta che non soddisfa le limitazioni della chiave API, la richiesta non va a buon fine. Ad esempio, se una chiave API richiede che le richieste HTTP vengano emesse da un dominio specifico, ma viene ricevuta una richiesta HTTP 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 aggiungerle dopo la creazione della chiave utilizzando il metodo UpdateKey. Questa pagina descrive le limitazioni che puoi aggiungere a una chiave API e mostra come aggiungerle.

Prima di iniziare

La pagina utilizza curl e Google Cloud CLI per inviare richieste all'API API Keys. Per informazioni dettagliate su come configurare l'API per sperimentarla, consulta la sezione Introduzione alle chiavi API.

Aggiunta di limitazioni per i clienti

Le limitazioni dei client specificano quali siti web, indirizzi IP o app possono utilizzare una chiave API. Aggiungi limitazioni client in base al tipo di client che chiama la tua API. Puoi specificare uno dei seguenti tipi di limitazioni client:

browserKeyRestrictions: i referrer HTTP (siti web) autorizzati a utilizzare la chiave.
serverKeyRestrictions: Gli indirizzi IP dei chiamanti autorizzati a utilizzare la chiave.
androidKeyRestrictions: le app per Android autorizzate a utilizzare la chiave.
iosKeyRestrictions: le app per iOS autorizzate a utilizzare la chiave.

Aggiunta di limitazioni del browser

L'esempio seguente 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 Key aggiornato con le limitazioni.

L'esempio seguente 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 tabella seguente mostra alcuni scenari di esempio e le limitazioni del browser:

Scenario	Limitazioni
Consenti qualsiasi URL nel tuo sito	Devi impostare due URL nell'elenco `allowedReferers`. 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/*`
Consentire un URL specifico	Aggiungi un URL con un percorso esatto. Ad esempio: `www.example.com/path` `www.example.com/path/path`
Consenti qualsiasi URL in un singolo sottodominio o dominio nudo	Per consentire un intero dominio, devi impostare due URL nell'elenco `allowedReferers`. URL del 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/*`

Aggiunta di limitazioni del server

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

IPv4 (198.51.100.1)
IPv6 (2001:db8::1)
Una subnet che utilizza 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"]
      }
    }
  }'

Aggiunta di limitazioni per Android

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

Ad esempio, supponiamo 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 e il nome del pacchetto per 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"
          }
        ]
      }
    }
  }'

Aggiunta di limitazioni per iOS

Puoi limitare l'utilizzo di una chiave API solo alle tue app per iOS fornendo l'ID pacchetto di ciascuna app quando crei o aggiorni una chiave. L'esempio seguente mostra come impostare iosKeyRestrictions durante la creazione di 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"]
      }
    }
  }'

Aggiunta di limitazioni dell'API

Le limitazioni delle API ti consentono di specificare quali Google Cloud API possono essere chiamate utilizzando la chiave API. Ti consigliamo di aggiungere limitazioni sia per il client che per l'API a tutte le tue chiavi API.

Puoi specificare uno o più servizi nelle limitazioni API. Il seguente esempio 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 dei servizi abilitati nel tuo progettoGoogle Cloud , utilizza il comando gcloud services list.

Oltre a limitare l'utilizzo della chiave API a servizi specifici, puoi specificare facoltativamente i metodi in ogni 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"
  }'