Como adicionar restrições às chaves de API

As chaves de API identificam seu aplicativo ou site para o Google Cloud. As restrições de chave de API garantem que apenas seus apps e sites possam usar suas chaves. Por motivos de segurança, recomendamos que você adicione restrições que especifiquem:

Quais clientes ou sites podem usar suas chaves de API.
As APIs do Google Cloud que seu aplicativo pode chamar usando as chaves de API.

Se um cliente usar uma chave de API restrita para emitir uma solicitação que não atende às restrições da chave, a solicitação vai falhar. Por exemplo, se uma chave de API exigir que as solicitações HTTP sejam emitidas de um domínio específico, mas uma solicitação HTTP for recebida de um domínio diferente, ela será rejeitada com um erro.

É possível adicionar restrições ao criar uma chave de API com o método CreateKey ou depois que a chave for criada usando o método UpdateKey. Nesta página, descrevemos as restrições que podem ser adicionadas a uma chave de API e mostramos como fazer isso.

Antes de começar

A página usa curl e a Google Cloud CLI para enviar solicitações à API Keys. Consulte Como começar a usar as chaves de API para saber como se preparar para testar a API.

Como adicionar restrições de cliente

As restrições de cliente especificam quais sites, endereços IP ou apps podem usar uma chave de API. Você adiciona restrições de cliente com base no tipo de cliente que chama sua API. É possível especificar um dos seguintes tipos de restrições de cliente:

browserKeyRestrictions: os referenciadores HTTP (sites) que podem usar a chave.
serverKeyRestrictions: os endereços IP dos chamadores que podem usar a chave.
androidKeyRestrictions: os apps Android autorizados a usar a chave.
iosKeyRestrictions: os apps iOS autorizados a usar a chave.

Como adicionar restrições de navegador

O exemplo a seguir mostra como chamar o método UpdateKey para restringir o referenciador 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 a resposta de operations.get contém "done": true, o response contém o Key atualizado com as restrições.

O exemplo a seguir mostra como criar uma chave de API que permite apenas solicitações HTTP de uma lista de URLs específicos.

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

A tabela a seguir mostra alguns exemplos de cenários e restrições do navegador:

Cenário	Restrições
Permitir qualquer URL no site	É preciso definir dois URLs na lista `allowedReferers`. URL do domínio, sem um subdomínio e com um caractere curinga no caminho. Por exemplo: `example.com/` Um segundo URL que inclui um caractere curinga para o subdomínio e um curinga para o caminho. Por exemplo: `.example.com/*`
Permitir um URL específico	Adicione um URL com um caminho exato. Por exemplo: `www.example.com/path` `www.example.com/path/path`
Permitir qualquer URL em um único subdomínio ou domínio sem "www".	É preciso definir dois URLs na lista "allowedReferers" para permitir um domínio inteiro. URL para o domínio, sem uma barra no final. Por exemplo: `www.example.com` `sub.example.com` `example.com` Um segundo URL para o domínio que inclui um caractere curinga no caminho. Por exemplo: `www.example.com/` `sub.example.com/` `example.com/*`

Como adicionar restrições de servidor

Especifique um ou mais endereços IP dos autores da chamada, como servidores da Web ou cron jobs, que podem usar a chave de API. É possível especificar os endereços IP em qualquer um dos seguintes formatos:

IPv4 (198.51.100.1)
IPv6 (2001:db8::1)
Uma sub-rede usando a notação CIDR (198.51.100.0/24, 2001:db8::/64)

O exemplo a seguir mostra como criar uma chave de API com uma lista de 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"]
      }
    }
  }'

Como adicionar restrições do Android

É possível restringir o uso de uma chave de API apenas aos seus apps Android. Ao criar ou atualizar uma chave de API, forneça o nome do pacote e a impressão digital SHA-1 de 20 bytes para cada app.

Por exemplo, suponha que você tenha executado o utilitário keytool e ele tenha criado a seguinte impressão digital:

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

O exemplo a seguir mostra como criar uma chave de API com a impressão digital e o nome do pacote para o 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"
          }
        ]
      }
    }
  }'

Como adicionar restrições do iOS

É possível restringir o uso de uma chave de API apenas aos seus apps iOS fornecendo o ID do pacote de cada app ao criar ou atualizar uma chave. O exemplo a seguir mostra como definir o iosKeyRestrictions ao criar uma chave de 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"]
      }
    }
  }'

Como adicionar restrições de API

Com as restrições de API, é possível especificar quais APIs do Google Cloud podem ser chamadas usando a chave de API. Recomendamos que você adicione restrições de cliente e de API a todas as suas chaves de API.

É possível especificar um ou mais serviços nas restrições de API. O exemplo a seguir mostra como restringir o uso de uma nova chave de API apenas aos serviços 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"
        }
      ]
    },
  }'

Para receber uma lista de serviços ativados no seu projetoGoogle Cloud , use o comando gcloud services list (em inglês).

Além de restringir o uso da chave de API a serviços específicos, é possível especificar os métodos em cada serviço para restringir ainda mais a chave de API. O exemplo a seguir mostra como restringir a chave anterior apenas aos métodos permitidos de 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"
  }'