Como adicionar restrições às chaves de API

As chaves de API identificam seu aplicativo ou site no Google Cloud. As restrições de chave de API garantem que somente 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 suas chaves de API.

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

É possível adicionar restrições ao criar uma chave de API com o método CreateKey ou adicionar as restrições após a criação da chave usando o método UpdateKey. Esta página descreve as restrições que você pode adicionar a uma chave de API e mostra como adicioná-las.

Antes de começar

A página usa curl com a ferramenta de linha de comando oauth2l para enviar solicitações à API de chaves de API. Consulte Primeiros passos com as chaves de API para detalhes sobre como começar a usar a API.

Como adicionar restrições de clientes

As restrições de cliente especificam quais sites, endereços IP ou apps podem usar uma chave de API. Adicione restrições de clientes 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) com permissão para usar a chave.
serverKeyRestrictions: os endereços IP dos autores da chamada que têm permissão para usar a chave.
androidKeyRestrictions: os apps para Android com permissão para usar a chave.
iosKeyRestrictions: os apps para iOS com permissão para usar a chave.

Como adicionar restrições ao 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, response contém o Key atualizado com as restrições.

O exemplo a seguir mostra como criar uma nova 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 de navegador:

Cenário	Restrições
Permitir qualquer URL no seu site	É preciso definir dois URLs na lista "allowedReferers". URL para o domínio, sem um subdomínio e com um caractere curinga para o caminho. Por exemplo: `example.com/` Um segundo URL que inclui um caractere curinga no subdomínio e um caractere curinga no 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"	Defina dois URLs na lista `allowedReferers` para permitir um domínio inteiro. URL do 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

É possível especificar um ou mais endereços IP de autores de chamadas, por exemplo, servidores da Web ou cron jobs com permissão para usar sua chave de API. É possível especificar os endereços IP em qualquer um dos formatos a seguir:

IPv4 (198.51.100.1)
IPv6 (2001:db8::1)
Uma sub-rede usando 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"]
      }
    }
  }'

Adicionar restrições do Android

Você pode restringir o uso de uma chave de API somente aos seus apps para 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 de cada app.

Por exemplo, suponha que você executou o utilitário keytool e criou a impressão digital a seguir:

  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 para iOS

É possível restringir o uso de uma chave de API somente aos apps para 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 com a chave de API. Recomendamos que você adicione restrições de cliente e API a todas as suas chaves de API.

É possível especificar um ou mais serviços nas restrições da 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 ver uma lista de serviços ativados no projeto do Cloud, use o comando gcloud services list.

Além de restringir a chave de API para uso com 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"
  }'