As chaves de API são obrigatórias para apps e projetos que usam os SDKs e as APIs da Plataforma Google Maps. Este documento identifica o uso pretendido das chaves de API, como protegê-las da mesma forma que outras credenciais e quais restrições são apropriadas para os projetos.
O que são chaves de API?
As chaves de API são credenciais específicas do projeto que atendem a dois propósitos:
- Identificação do projeto.
Identificar o app ou projeto que está fazendo uma chamada para a API ou o SDK. - Autorização do projeto.
Verificar se o app recebeu acesso para chamar a API ou o SDK e conta com API ou SDK ativado no projeto.
Quando uma chave de API é criada, ela é associada a um projeto. Ao identificar o projeto da chamada, uma chave de API permite que as informações de uso sejam associadas a esse projeto e ajuda a garantir que as chamadas de outros projetos sejam rejeitadas.
Proteger chaves de API
Recomendamos proteger as chaves de API no seu aplicativo para todos os produtos da Plataforma Google Maps que ele usa. Para isso, coloque restrições e implemente as práticas recomendadas apropriadas para as APIs da Plataforma Google Maps no aplicativo. A exposição pública de credenciais não seguras pode resultar em uso não intencional, o que talvez gere cobranças inesperadas na sua conta.
As práticas a seguir descrevem estratégias para ajudar a proteger as chaves de API. As práticas recomendadas para um produto específico da Plataforma Google Maps, como a API Maps JavaScript, estão listadas na seção Restrições e práticas recomendadas da chave de API.
-
Restrinja suas chaves de API. Para proteger melhor sua chave, restrinja-a a determinados endereços IP, URLs referenciadores ou apps para dispositivos móveis e APIs específicas, porque isso reduz significativamente o impacto em caso de comprometimento da chave.
Para especificar restrições de aplicativo e API de uma chave no console, abra a página "Credenciais" e, em seguida, crie uma nova chave de API com as configurações desejadas ou edite as configurações de uma chave existente. Consulte a seção Restringir chaves de API para ver todos os detalhes.
- Use chaves de API independentes para apps diferentes. Isso limita o escopo de cada chave. Se uma chave de API for comprometida, será possível excluir e revogar essa chave sem precisar atualizar suas outras chaves.
- Exclua chaves de API desnecessárias.
Para excluir uma chave de API, faça o seguinte:
- Acesse o painel de credenciais.
- Selecione a chave de API que você quer excluir.
- Clique no botão Excluir, na parte superior da página.
- Quando o pop-up Excluir credencial for exibido, clique em EXCLUIR.
-
Tenha cuidado ao gerar novamente chaves de API. Se o tempo necessário para migrar os aplicativos da chave de API antiga para a nova ultrapassar 24 horas, as instâncias que não forem atualizadas serão interrompidas, já que fazem referência à chave antiga (que é destruída 24 horas após a nova emissão).
Quando você gera novamente uma chave de API, o seguinte acontece:
- Uma nova chave resulta do processo de regeneração.
- A nova chave recebe todas as restrições da chave antiga.
- A janela de 24 horas começa, marcando o período até que a chave antiga seja destruída.
-
Monitore o uso da API em busca de anomalias. Se você observar uso não autorizado, alterne suas chaves e notifique o Google.
Antes de alternar uma chave, mantenha as restrições associadas a ela, fazendo uma cópia em um arquivo.
-
Nos apps que usam as APIs Maps Web Service ou APIs Static Web, utilize os seguintes métodos para proteger seus apps e chaves de API:
- Não incorpore chaves de API ou chaves secretas de assinatura diretamente no código. Em vez de incorporar chaves de API ou quaisquer outras informações particulares diretamente no código do seu aplicativo, coloque-as em variáveis de ambiente ou inclua arquivos armazenados separadamente da maior parte do código, fora do repositório de origem do app. Em seguida, se você compartilhar seu código, as chaves de API ou as chaves secretas de assinatura não serão incluídas nos arquivos compartilhados.
- Não armazene chaves de API ou chaves secretas de assinatura em arquivos dentro da árvore de origem do aplicativo. Se você armazenar chaves de API ou outras informações particulares em arquivos, mantenha-os fora da árvore de origem do aplicativo para garantir que as informações não sejam inseridas no sistema de controle do código-fonte. Isso é especialmente importante se você usa um sistema de gerenciamento de código-fonte público, como o GitHub.
- Revise o código antes de liberá-lo publicamente. Verifique se o código não contém chaves de API, chaves secretas de assinatura ou qualquer outra informação particular antes de disponibilizá-lo publicamente.
-
Nos apps para dispositivos móveis que usam APIs Web Service ou APIs Static Web, utilize uma ou mais das seguintes técnicas para proteger suas chaves de API ou chaves secretas de assinatura:
-
Use um servidor proxy. O servidor proxy oferece uma fonte sólida para interagir com a API apropriada da Plataforma Google Maps. Para mais informações sobre como usar um servidor proxy, consulte Living Vicariously: usar servidores proxy com as bibliotecas de cliente da API Google Data (em inglês).
- Ofusque ou criptografe a chave de API ou a chave secreta de assinatura. Isso complica a extração de chaves de API e outros dados particulares diretamente do aplicativo.
-
Restringir chaves de API
As chaves de API são credenciais que devem ser gerenciadas com cuidado. Siga as recomendações abaixo para manter as chaves seguras e garantir restrições para reduzir o impacto caso elas sejam comprometidas.
Para restringir uma chave de API, você pode especificar uma restrição de aplicativo ou uma ou mais restrições de API.
As restrições de aplicativo limitam o uso das chaves de API a sites específicos (endereço IP e site) ou plataformas específicas (Android e iOS). É possível selecionar no máximo uma restrição dessa categoria (consulte APIs da Plataforma Google Maps por plataforma).
As restrições da API limitam o uso das chaves a um ou mais SDKs ou APIs da Plataforma Google Maps. Os pedidos para usar APIs ou SDKs associados a uma chave de API serão processados, enquanto os pedidos de APIs ou SDKs que não estão associados a uma chave falharão. Para uma chave de API, você pode especificar quantas restrições forem necessárias. Verifique se as APIs ou os SDKs associados a uma chave são compatíveis com a restrição de aplicativo definida para ela.
Definir uma restrição de aplicativo para uma chave de API
- Acesse o painel de credenciais.
- Selecione a chave de API em que você quer definir uma restrição. A página de propriedades será exibida.
- Em Restrições de chave, selecione Restrições de aplicativo.
Selecione um dos tipos de restrição e insira as informações solicitadas após a lista de restrições.Tipo de restrição Descrição Referenciadores HTTP Aceita solicitações da lista de sites que você disponibilizar.
Abaixo dos tipos, especifique um ou mais sites referenciadores. É possível usar caracteres curinga para nomear sites semelhantes. Por exemplo,
*.google.comaceita todos os sites que terminam emgoogle.com, comohttps://developers.google.com.Endereços IP Aceita as solicitações da lista de endereços IP do servidor da Web que você disponibilizar.
Abaixo dos tipos, especifique um endereço IPv4 ou IPv6 ou uma sub-rede usando a notação CIDR (por exemplo, 192.168.0.0/22). Se você precisar inserir outra entrada, uma nova caixa aparecerá depois que a ação anterior for concluída.
Apps Android Insere o nome do seu pacote e a impressão digital do certificado de assinatura SHA-1 para restringir o uso ao seu app Android.
Abaixo dos tipos, adicione a impressão digital do certificado de assinatura SHA-1 e o nome do pacote Android retirado do arquivo AndroidManifest.xml.
Apps iOS Aceita solicitações do app iOS com o identificador do pacote que você disponibilizar.
Abaixo dos tipos, selecione o identificador iOS correto na lista.
- Clique em Salvar.
A restrição se torna parte da definição de chave de API após essa etapa. Se você não enviar os detalhes corretos ou não clicar em "Salvar", a chave de API não será restringida. Para mais informações, consulte o guia Acessar uma chave de API da API ou do SDK específico em que você tem interesse.
Definir uma restrição de API em uma chave de API
- Acesse o painel de credenciais.
- Selecione a chave de API que você quer restringir.
A página Restringir e renomear a chave de API é exibida. - Em Restrições de API:
- Clique em Restringir chave.
- Clique na lista suspensa Selecionar APIs e escolha as APIs ou os SDKs que seu aplicativo deve acessar usando a chave de API. Se uma API ou um SDK não aparecer na lista, será preciso ativá-lo.
- Clique em Salvar.
A restrição se torna parte da definição de chave de API após essa etapa. Se você não enviar os detalhes corretos ou não clicar em "Salvar", a chave de API não será restringida. Para mais informações, consulte o guia Acessar uma chave de API da API ou do SDK específico em que você tem interesse.
Restrições e práticas recomendadas para chaves de API
As tabelas a seguir mostram as restrições de chave de API e as práticas recomendadas adequadas para cada API, SDK ou serviço da Plataforma Google Maps.
Sites com APIs Maps JavaScript, Embed ou Static
Apps e servidores que usam serviços da Web
Apps Android
| API/SDK/serviço | Restrição de aplicativo(1) | Restrição de API(1) | Práticas recomendadas |
|---|---|---|---|
| SDK do Maps para Android | Restrição para Android | SDK do Maps para Android | |
| SDK do Places para Android | Restrição para Android | API Places |
Apps iOS
| API/SDK/serviço | Restrição de aplicativo(1) | Restrição de API(1) | Práticas recomendadas |
|---|---|---|---|
| SDK do Maps para iOS | Restrição para iOS | SDK do Maps para iOS | |
| SDK do Places para iOS | Restrição para iOS | API Places |
1 Você pode usar uma chave de API sem restrição com qualquer API ou SDK da Plataforma Google Maps. No entanto, é altamente recomendável restringir as chaves, principalmente nos seguintes cenários:
- O ambiente de teste será ou está visível publicamente.
- O aplicativo que usa uma chave de API está pronto para ser usado em um ambiente de produção.
2 Em aplicativos para dispositivos móveis, é recomendável usar o SDK do Maps para Android e o SDK do Maps para iOS nativo.
3 Para a API Maps Static e a API Street View Static, além de uma chave de API, você precisa disponibilizar uma assinatura digital para exceder a cota diária de 25 mil carregamentos de mapa.
Observação: as chaves secretas compartilhadas usadas para assinatura exigem pelo menos o mesmo nível de segurança das chaves de API usadas com as APIs Maps Web Service.
Se você precisar assinar suas solicitações de imagem dinamicamente, faça isso do lado do servidor. Se os aplicativos dependem de entrada do lado do cliente para gerar as imagens estáticas, proteja-as com uma ou mais das seguintes técnicas:
Se você assina suas solicitações, reveja também quantas solicitações não assinadas gostaria de permitir por dia, e ajuste as cotas conforme necessário.
4 As restrições de IP podem ser inviáveis, como em aplicativos para dispositivos móveis e ambientes na nuvem que dependem de endereços IP dinâmicos. Ao usar as APIs Maps Web Service nesses cenários, proteja seus apps empregando uma ou mais das técnicas abaixo:
5 Em aplicativos para dispositivos móveis, é recomendável usar o SDK do Places para Android e o SDK do Places para iOS nativo.