Orientações de segurança da Plataforma Google Maps

Os apps e projetos que usam as APIs e os SDKs da Plataforma Google Maps precisam usar chaves de API ou, se for compatível, o OAuth 2.0 para se autenticar.

Estas práticas recomendadas mostram como proteger seu acesso à Plataforma Maps.

Se você quiser usar o OAuth 2.0 para autorizar o tráfego de servidor para servidor, procure o tópico sobre o OAuth na documentação da API. Consulte Usar o OAuth para apps do lado do servidor para mais detalhes.

Além disso, para aplicar restrições à chave de API e ao aplicativo, siga as práticas de segurança relacionadas aos produtos específicos da Plataforma Google Maps. Por exemplo, confira a API Maps JavaScript abaixo em Restrições recomendadas de API e aplicativo.

Se você já utiliza as chaves de API, confira as recomendações abaixo em Se você estiver restringindo uma chave de API em uso.

Para mais detalhes sobre assinaturas digitais, aceitas pela API Maps Static e pela API Street View Static, consulte o Guia de assinatura digital.

Práticas recomendadas

Para ter mais proteção e evitar cobranças por uso não autorizado, siga estas práticas recomendadas de segurança de API relacionadas a todos os serviços, SDKs ou APIs da Plataforma Google Maps:

Restringir suas chaves de API

Usar chaves de API diferentes em cada app

Excluir chaves de API não usadas

Verificar o uso da sua chave de API

Cuidado ao alternar chaves de API

Dividir o uso do lado do cliente e do servidor em projetos separados

Desativar serviços não usados

Outras recomendações para apps do lado do cliente

Usar SDKs do lado do cliente

Chamadas de serviço da Web seguras do lado do cliente

Mais recomendações para sites ou apps do lado do cliente que usam APIs Static Web

Proteger o uso da API Static Web

Mais recomendações para apps do lado do servidor que usam serviços da Web

Proteger chaves de API do serviço da Web

Usar o OAuth para apps do lado do servidor

Se você estiver restringindo ou alternando uma chave de API em uso

  • Antes de mudar a chave de API, verifique a utilização dela. Essa etapa é muito importante se você está adicionando restrições para uma chave que já está em uso em um aplicativo de produção.

  • Depois da mudança, atualize todos os apps com as novas chaves de API, conforme necessário.

  • Se a chave de API não tiver sido comprometida e não estiver sendo usada de forma ativa, você poderá migrar seus apps para várias chaves de API novas no seu próprio ritmo, deixando a chave de API original intacta até que haja apenas um tipo de tráfego, e a chave de API poderá ser restrita com segurança com um único tipo de restrições de aplicativo, sem causar interrupções indesejadas no serviço.

    Se quiser mais detalhes, consulte Migrar para várias chaves de API.

    Monitore o uso ao longo do tempo e saiba quando APIs, tipos de plataformas e domínios específicos migraram da chave de API antiga antes de restringir ou excluir essa chave. Para mais informações, consulte Relatórios e monitoramento e Métricas.

  • Se a chave de API foi comprometida, é necessário agir rápido para proteger a chave e deter o abuso. Em apps Android e iOS, as chaves não são substituídas até que os clientes atualizem os apps. Atualizar ou substituir chaves em páginas da Web ou em apps do lado do servidor é muito mais simples, mas ainda pode exigir um planejamento cuidadoso e um trabalho rápido.

    Para mais informações, consulte Abordagem quanto ao uso não autorizado de uma chave de API.

Mais informações

Restrições recomendadas de API e aplicativo

Restringir suas chaves de API

A prática recomendada é sempre restringir as chaves de API com um tipo de restrição de aplicativo e uma ou mais restrições de API. Para conferir restrições sugeridas por serviço de API, SDK ou JavaScript, consulte Restrições recomendadas de API e aplicativo abaixo.

  • Restrições de aplicativo: você pode limitar o uso de uma chave de API a plataformas específicas: aplicativos Android ou iOS, sites específicos para aplicativos no lado do cliente, endereços IP ou sub-redes CIDR específicos para apps no lado do servidor que emitem chamadas de API REST em serviços da Web.

    Você limita uma chave adicionando uma ou mais restrições de aplicativo do tipo que você quer autorizar. Depois disso, apenas solicitações dessas origens são permitidas.

  • Restrições de API: você pode limitar as APIs, os SDKs ou os serviços da Plataforma Google Maps em que a chave de API pode ser usada. As restrições de API permitem solicitações apenas às APIs e SDKs especificados por você. É possível definir quantas restrições de API forem necessárias para uma chave. A lista de APIs disponíveis inclui todas aquelas que estão ativas em um projeto.

Definir uma restrição de aplicativo para uma chave de API

  1. Abra a página Credenciais da Plataforma Google Maps do console do Google Cloud.

  2. Selecione a chave de API que você quer restringir.

  3. Na página Editar chave de API, em Restrições de chave, selecione Definir uma restrição de aplicativo.

    Página "Editar chave de API"

  4. Selecione um dos tipos de restrições e insira as informações pedidas seguindo a lista.

    Tipo de restrição Descrição
    Sites Especifique um ou mais sites de referenciadores.
    • Os esquemas de URI do referenciador com suporte universal são https e http. Não é garantido que outros esquemas funcionem corretamente, já que os navegadores da Web modernos não enviam um cabeçalho "Referer" em solicitações de saída por motivos de privacidade.
    • Sempre informe a string de referenciador inteira, incluindo o esquema do protocolo, o nome do host e a porta opcional (por exemplo, https://google.com).
    • Você pode usar caracteres curinga para autorizar todos os subdomínios. Por exemplo, https://*.google.com aceita todos os sites que terminam em .google.com.
    • Tenha cuidado ao autorizar referenciadores de caminho completo (por exemplo, https://google.com/some/path), já que a maioria dos navegadores da Web remove o caminho de solicitações de origem cruzada por motivos de privacidade.
    Endereços IP Especifique um ou mais endereços IPv4 ou IPv6 ou sub-redes usando notação do CIDR. Os endereços IP precisam corresponder ao endereço da origem que os servidores da Plataforma Google Maps observam. Se você usa conversão de endereços de rede (NAT), esse endereço geralmente corresponde ao endereço IP público da sua máquina.
    Apps Android Adicione o nome do pacote Android (do arquivo AndroidManifest.xml) e a impressão digital do certificado de assinatura SHA-1 de cada app Android que você quer autorizar. Se você usa a Assinatura de apps do Google Play, para buscar a impressão digital do certificado de assinatura, consulte Como trabalhar com provedores de API. Se você gerencia sua própria chave de assinatura, consulte Como assinar seu aplicativo automaticamente ou as instruções para seu ambiente de build.
    Apps iOS Adicione o identificador do pacote de cada app iOS que você quer autorizar.

    Para consultar restrições sugeridas de aplicativo, acesse Restrição recomendada de aplicativo.

  5. Selecione Salvar.

Definir restrições de API para uma chave de API

  1. Abra a página Credenciais da Plataforma Google Maps do console do Google Cloud.

  2. Selecione a chave de API que você quer restringir.

  3. Na página Editar chave de API, em Restrições de API:

    • Selecione Restringir chave.

    • Abra Selecionar APIs e escolha as APIs ou os SDKs que seu aplicativo vai acessar usando a chave de API.

    Ative as APIs ou os SDKs caso eles não apareçam na lista. Para mais detalhes, consulte Para ativar uma ou mais APIs ou SDKs.

    Restringir uma API na página "Editar chave de API"

  4. Selecione Salvar.

    Após essa etapa, a restrição vai se tornar parte da definição da chave de API. Não se esqueça de incluir os detalhes apropriados e escolher Salvar para salvar as restrições da chave de API. Para mais informações, consulte o guia Gerar uma chave de API na documentação da API ou do SDK em que você tem interesse.

Para conferir as restrições recomendadas de API, consulte Restrições recomendadas de API.

Verificar o uso da sua chave de API

Se você estiver restringindo chaves de API depois da criação delas ou se quiser saber quais APIs estão sendo usadas por uma chave para aplicar limitações a elas, verifique o uso da chave de API. Estas etapas mostram em que serviços e métodos de API uma chave de API está sendo usada. Se houver qualquer uso além dos serviços da Plataforma Google Maps, investigue para determinar se é necessário adicionar mais restrições e evitar uso indesejado. Você pode usar o Metrics Explorer do console do Cloud na Plataforma Google Maps para determinar qual restrição de API e aplicativo vai ser aplicada à chave de API:

Determinar as APIs que usam a chave de API

Com os relatórios de métricas a seguir, você consegue determinar quais APIs estão usando suas chaves. Use esses relatórios para fazer o seguinte:

  • Saber como suas chaves de API estão sendo usadas.
  • Identificar uso inesperado.
  • Verificar se é seguro excluir uma chave não usada. Para informações sobre como remover uma chave de API, consulte Excluir chaves de API não usadas.

Ao aplicar restrições de API, use esses relatórios para criar uma lista de APIs que serão autorizadas ou validar recomendações de restrição de chaves de API geradas automaticamente. Para mais informações sobre restrições recomendadas, consulte Aplicar restrições recomendadas. Para mais informações sobre como usar o Metrics Explorer, consulte Criar gráficos com o Metrics Explorer.

  1. Acesse o Metrics Explorer do console do Google Cloud.

  2. Faça login e selecione o projeto das chaves de API que você quer verificar.

  3. Acesse a página "Metrics Explorer" do seu tipo de API:

    • Para chaves de API que usam qualquer API, exceto a API Maps Embed: acesse a página Metrics Explorer.

    • Para chaves de API que usam a API Maps Embed: acesse o Metrics Explorer.

  4. Inspecione cada chave de API:

    1. Selecione ADICIONAR FILTRO.

    2. Escolha o marcador credential_id.

    3. Selecione o valor que corresponde à chave que você quer inspecionar.

    4. Observe em quais APIs essa chave de API está sendo usada e confirme se o uso é esperado.

    5. Quando terminar, escolha Remover filtro no fim da linha do filtro ativo para excluir o filtro extra.

  5. Repita o processo para as chaves restantes.

  6. Restrinja as chaves apenas às APIs que estão sendo usadas.

  7. Se você identificar uso não autorizado, consulte Abordagem quanto ao uso não autorizado de uma chave de API.

Escolher o tipo correto de restrição de aplicativo usando o Metrics Explorer

Depois de verificar e tomar as medidas necessárias para garantir que a chave de API esteja sendo usada apenas nos serviços da Plataforma Google Maps, confirme se ela tem as restrições de aplicativo corretas.

Aplique as restrições recomendadas da chave de API. Para mais detalhes, consulte Aplicar restrições recomendadas de chave de API.

Se a sua chave de API não tiver sugestões de restrição, determine o tipo de restrição de aplicativo que será usado, com base no platform_type informado no Metrics Explorer:

  1. Acesse o Metrics Explorer do console do Google Cloud.

  2. Faça login e selecione o projeto das APIs que você quer verificar.

  3. Acesse esta página: Metrics Explorer.

  4. Inspecione cada chave de API:

    1. Selecione ADICIONAR FILTRO.

    2. Escolha o marcador credential_id.

    3. Selecione o valor que corresponde à chave que você quer inspecionar.

    4. Quando terminar, escolha Remover filtro no fim da linha do filtro ativo para excluir o filtro extra.

  5. Repita o processo para as chaves restantes.

  6. Assim que você tiver o tipo de plataforma para suas chaves de API, aplique a restrição de aplicativo para esse platform_type:

    PLATFORM_TYPE_JS : aplique restrições de site à chave.

    PLATFORM_TYPE_ANDROID : aplique restrições de aplicativo Android à chave.

    PLATFORM_TYPE_IOS : aplique restrições de aplicativo iOS à chave.

    PLATFORM_TYPE_WEBSERVICE : Talvez você precise usar restrições de endereço IP na chave para restringir corretamente.

    Para recomendações sobre a API Maps Static e a API Street View Static, consulte Proteger o uso da API Static Web.

    Para recomendações da API Maps Embed, consulte Sites com a API Maps Embed.

    Minha chave de API está usando vários tipos de plataforma:não é possível proteger seu tráfego adequadamente com apenas uma chave de API. Você precisa migrar para várias chaves de API. Para mais informações, consulte Migrar para várias chaves de API.

Use chaves de API separadas para cada app

Essa prática limita o escopo de cada chave. Se uma chave de API for comprometida, será possível excluir ou girar essa chave sem precisar atualizar as outras. É possível criar até 300 chaves de API por projeto. Para mais informações, consulte Limites em chaves de API.

Embora uma chave de API por aplicativo seja ideal para fins de segurança, é possível usar chaves restritas em vários apps, contanto que elas tenham o mesmo tipo de restrição de aplicativo.

Aplicar restrições recomendadas à chave de API

Para alguns proprietários de projetos, editores e administradores de chaves de API, o console do Google Cloud sugere restrições específicas para chaves de API sem restrição com base no uso e na atividade da Plataforma Google Maps.

Se disponíveis, as recomendações aparecem como opções pré-preenchidas na página Credenciais da Plataforma Google Maps.

APIs e SDKs da Plataforma Google Maps com suporte às recomendações automatizadas

  • API Maps JavaScript, incluindo o serviço Directions (legado), o serviço Distance Matrix (legado), o serviço Elevation, o serviço de geocodificação, a classe Place, o widget Place Autocomplete (novo), a API Place Autocomplete Data, a biblioteca Places, o serviço Places e o widget Place Autocomplete

  • API Maps Static e API Street View Static

  • API Maps Embed

  • SDK do Maps para Android, SDK do Places para Android e SDK do Navigation para Android

  • SDK do Maps para iOS, SDK do Places para iOS, SDK do Places Swift para iOS e SDK do Navigation para iOS

Motivos para recomendações não aparecerem ou serem mostradas incompletas para você

Motivos para não aparecer nenhuma recomendação

  • Você está usando a chave de API em outros serviços que não são da Plataforma Google Maps ou que ainda não são compatíveis com as recomendações automáticas.

    Nesse caso, não implemente a recomendação antes de fazer o seguinte:

    1. Verifique se o uso da API no Metrics Explorer do console do Google Cloud é legítimo.

    2. Inclua de forma manual os serviços que estão faltando na lista de APIs que precisam de autorização.

    3. Adicione manualmente as restrições de aplicativo que estão faltando para os serviços adicionados à lista de APIs. Se isso exigir outro tipo de restrições de aplicativo, consulte Migrar para várias chaves de API.

  • Sua chave de API não está sendo usada em SDKs ou APIs no lado do cliente.

  • Você está utilizando a chave de API em um app ou site de baixo volume que não foi usado nos últimos 60 dias.

  • Você criou uma chave ou implantou uma em um novo app recentemente. Se for o caso, aguarde mais alguns dias para que as recomendações sejam atualizadas.

  • Você está usando a chave de API em vários aplicativos que exigem tipos conflitantes de restrições de aplicativo ou a mesma chave em muitos apps ou sites diferentes. Nos dois casos, a prática recomendada é migrar para várias chaves. Se quiser mais detalhes, consulte Migrar para várias chaves de API.

Motivos para uma recomendação incompleta aparecer

  • Você está utilizando a chave de API em um app ou site de baixo volume que não foi usado nos últimos 60 dias.

  • Você recentemente começou a usar uma chave em uma nova API ou serviço, e o pipeline automático de recomendação de restrição de chave de API ainda não processou as métricas de uso atualizadas. A propagação das métricas de uso pode levar alguns dias.

    Nesse caso, não implemente a recomendação antes de fazer o seguinte:

    1. Verifique se o uso da API no Metrics Explorer do console do Google Cloud é legítimo.

    2. Inclua de forma manual os serviços que estão faltando na lista de APIs que precisam de autorização.

    3. Adicione manualmente as restrições de aplicativo que estão faltando para os serviços adicionados à lista de APIs. Se isso exigir outro tipo de restrições de aplicativo, consulte Migrar para várias chaves de API.

    4. A menos que você precise restringir uma chave com urgência, por exemplo, devido a um uso não autorizado, talvez você possa esperar um ou dois dias para que as recomendações sejam atualizadas.

Motivos para recomendações que não estão nos gráficos aparecerem para você

  • Seu app ou site envia apenas bursts bem curtos de tráfego. Nesse caso, mude a visualização de GRÁFICO para TABELA ou AMBOS, já que o uso ainda está visível na legenda. Para mais informações, consulte Como ativar as legendas completas do gráfico.

  • Seu tráfego vem da API Maps Embed. Para instruções, consulte Determinar as APIs que usam a chave de API.

  • O tráfego do app ou site está fora do período disponível no Metrics Explorer do console do Google Cloud.

  1. Abra a página Credenciais da Plataforma Google Maps do console do Google Cloud.

  2. Se disponível, selecione Aplicar restrições recomendadas.

    Aplicar restrições recomendadas

  3. Selecione Verificar o uso da API para consultar quais serviços estão utilizando a chave de API. Se houver outros além dos serviços da Plataforma Google Maps, pause e revise manualmente seguindo as recomendações acima. Consulte as etapas para resolver problemas no começo da seção Aplicar restrições recomendadas à chave de API.

  4. Confira se as restrições pré-preenchidas correspondem aos sites e apps em que você espera usar sua chave de API.

    Prática recomendada: documente e remova as restrições de aplicativo ou API que não estejam associadas aos seus serviços. Se ocorrer algum erro devido a uma dependência inesperada, você poderá adicionar novamente as APIs ou apps necessários.

    • Se você reconhecer que um app, site ou API está faltando na sua recomendação, adicione manualmente ou espere alguns dias até que a recomendação seja atualizada.

    • Se precisar de mais ajuda com a recomendação sugerida, entre em contato com o suporte.

  5. Selecione Aplicar.

O que fazer se o aplicativo for rejeitado após a aplicação de uma recomendação

Se você notar que um app ou site foi rejeitado depois da aplicação de uma restrição, procure a restrição de aplicativo que você precisa adicionar na mensagem de erro de resposta da API.

SDKs e APIs do lado do cliente

Apps baseados em navegador e webview

Os navegadores modernos geralmente ocultam o cabeçalho Referer em solicitações entre origens por motivos de privacidade, muitas vezes reduzindo-o ao Origin. No entanto, o comportamento exato depende do referrer-policy aplicado do site de hospedagem e pode variar de acordo com a versão e o navegador do usuário.

Os aplicativos da Web que usam esquemas de URI opacos ou locais para carregar conteúdo normalmente têm o navegador de renderização ou a visualização da Web que oculta completamente o cabeçalho Referer de todas as chamadas de saída, o que pode causar falhas nas solicitações que usam chaves de API com restrições de site.

Para mais orientações, consulte Hospedar seus apps baseados em navegador em um servidor.

Instruções de solução de problemas para apps baseados em navegador e WebView:

  • Para a API Maps JavaScript, consulte o console de depuração do navegador para saber como autorizar seu aplicativo.

    Os esquemas de URI exóticos têm suporte parcial. Se partes do aplicativo não funcionarem com um esquema de URI exótico, mesmo após a autorização do referrer necessário, provavelmente será necessário hospedar o aplicativo remotamente em um servidor e carregá-lo por HTTPS (ou HTTP).

    Se precisar de ajuda com esquemas de URI exóticos, entre em contato com o suporte.

  • Em geral, outras APIs da Plataforma Maps retornam o referenciador que você precisa autorizar na resposta de erro da API, presumindo que o cliente enviou essas informações com a solicitação rejeitada.

    Não há suporte para esquemas de URI exóticos.

Apps Android

Use o Android Debug Bridge (adb) ou o Logcat.

Apps iOS

Consulte Como conferir mensagens de registro.

Apps que chamam serviços da Web diretamente

Para aplicativos que chamam a API REST HTTPS da Plataforma Google Maps ou os endpoints do gRPC diretamente sem um SDK da Plataforma Google Maps no lado do cliente, consulte abaixo:

Apps Android e iOS

Se o seu aplicativo Android ou iOS chamar os serviços da Plataforma Google Maps diretamente sem usar nenhum dos SDKs de cliente disponíveis, consulte os artigos Apps Android e Apps iOS para mais dicas de solução de problemas e Chamadas de serviço da Web seguras do lado do cliente para conferir as práticas recomendadas de segurança atuais para casos de uso em dispositivos móveis.

Se o app registrar respostas de erro da API da Plataforma Google Maps, as instruções acima para SDKs do lado do cliente também poderão ser úteis para resolver problemas de autenticação.

Apps do lado do servidor

Os aplicativos do lado do servidor que dependem de chaves de API são mais bem protegidos com restrições de endereço IP. Se você tiver aplicado restrições de endereço IP à chave e os registros do serviço registrarem respostas de erro da API da Plataforma Google Maps, verifique os registros do sistema para mais informações. A resposta de erro vai incluir o endereço IP do servidor que você precisa autorizar.

Apps baseados em navegador ou WebView

Embora as APIs Maps Static e Street View Static mais recentes da Plataforma Google Maps também ofereçam suporte a restrições de referrer, os navegadores ou visualizações da Web provavelmente vão restringir o cabeçalho Referer para Origin em solicitações entre origens e provavelmente não vão enviá-lo, por exemplo, para recursos acessados localmente ou para recursos veiculados por protocolos diferentes de HTTP ou HTTPS.

Se você não puder usar a API Maps JavaScript no seu aplicativo e as restrições do site não funcionarem, consulte Chamadas de serviço da Web seguras do lado do cliente para saber como emitir chamadas de serviço da Web da Plataforma Google Maps de forma segura no seu aplicativo do lado do cliente baseado em navegador.

Como verificar as restrições da API

Para verificar as restrições de API necessárias, consulte Determinar as APIs que usam a chave de API.

Se não conseguir determinar quais restrições serão aplicadas:

  1. Documente as restrições atuais para referência futura.
  2. Remova as restrições por enquanto e investigue o problema. Para saber qual foi o uso ao longo do tempo, consulte Verificar o uso da sua chave de API e siga as etapas.
  3. Se necessário, entre em contato com o suporte.

Excluir chaves de API não usadas

Antes de remover uma chave de API, verifique se ela não está sendo utilizada em produção. Se não houver tráfego bem-sucedido, a chave poderá ser excluída. Para mais informações, consulte Verificar o uso da sua chave de API.

Para excluir uma chave de API:

  1. Abra a página Credenciais da Plataforma Google Maps do console do Google Cloud.

  2. Selecione a chave de API que você quer excluir.

  3. Clique no botão Excluir na parte de cima da página.

  4. Na página Excluir credencial, selecione Excluir.

    A remoção de uma chave de API leva alguns minutos para ser propagada. Após a propagação, todo tráfego que usa a chave de API excluída é rejeitado.

Cuidado ao alternar as chaves de API

Fazer a rotação de uma chave de API cria uma nova chave com todas as restrições da antiga. Durante esse período, a chave antiga e a nova são aceitas. Assim, você pode migrar seus apps para usar a nova chave.

Antes de alternar uma chave de API:

  • Primeiro, tente limitar as chaves de API, como descrito em Restringir suas chaves de API.

  • Se não for possível fazer isso devido a tipos de restrições de aplicativo conflitantes, migre para várias chaves novas (restritas), como descrito em Migrar para várias chaves de API. É você quem controla os prazos de migração e lançamento das novas chaves de API.

Se não for possível aplicar as sugestões anteriores, e você precisar girar a chave de API para evitar o uso não autorizado, siga estas etapas:

  1. Abra a página Credenciais da Plataforma Google Maps do console do Google Cloud.

  2. Abra a chave de API que você quer girar.

  3. Na parte de cima da página, selecione Girar chave.

  4. Se quiser, mude o nome da chave de API.

  5. Selecione Criar.

  6. Atualize os apps para usar a nova chave.

Depois de atualizar os aplicativos para usar a nova chave, exclua a antiga clicando no botão Excluir a chave anterior na seção "Chave anterior" da nova página de chave de API.

Migrar para várias chaves de API

Se quiser usar uma única chave de API exclusiva para cada app, em vez de uma chave em vários aplicativos:

  1. Identifique quais apps vão precisar de novas chaves:

    • Os apps da Web são mais fáceis de atualizar, já que você controla todo o código. Atualize todas as chaves dos seus apps baseados na Web.
    • O processo é mais complexo em apps para dispositivos móveis, porque os clientes precisam atualizar o aplicativo antes de usar as novas chaves.

  2. Crie e restrinja as novas chaves: adicione uma restrição de aplicativo e, pelo menos, uma de API. Para mais informações, consulte Práticas recomendadas.

  3. Adicione as novas chaves aos seus apps: em apps para dispositivos móveis, esse processo pode levar meses até que todos os usuários atualizem para a versão mais recente e a nova chave de API.

Dividir o uso do lado do cliente e do servidor em projetos separados

Se você precisar chamar os serviços da Plataforma Google Maps tanto de aplicativos do lado do servidor quanto diretamente de aplicativos do lado do cliente em execução em dispositivos do usuário final, o Google recomenda dividir o uso entre dois projetos distintos.

Essa abordagem permite aplicar limites adequados de cota por minuto e por usuário na maioria dos serviços da Plataforma Google Maps no seu projeto do lado do cliente, ajudando a garantir que todos os usuários finais recebam uma parcela justa da cota geral do projeto sem afetar uns aos outros.

No entanto, como as restrições de cota por usuário afetam os aplicativos do lado do cliente e do servidor, se você também precisar de uma largura de banda maior para os trabalhos do lado do servidor, configure um projeto separado para esse caso de uso, configurado com um limite de cota maior ou nenhum por usuário.

Desativar serviços não usados

Não deixe serviços não utilizados ativados em um projeto, porque essa prática é vulnerável a abusos, especialmente se você não tiver restringido todas as chaves de API públicas. Como prática recomendada, só ative um serviço em um projeto quando ele for necessário para seus aplicativos.

Adicionar restrições de API a uma chave impede o uso dela em serviços que não foram autorizados, mas as restrições de API se aplicam apenas a essa chave específica. Desative um serviço no nível do projeto para evitar o uso não autorizado do serviço em qualquer chave vinculada ao projeto.

Usar SDKs do lado do cliente

Ao usar os SDKs da Plataforma Google Maps fornecidos do lado do cliente, você sempre poderá aplicar restrições adequadas à chave de API para proteger o uso do serviço.

O uso de SDKs do lado do cliente também permite adotar mecanismos de segurança mais avançados, como o Firebase App Check nas plataformas da API do Maps que oferecem suporte a ele. Consulte Usar a verificação de app para proteger sua chave de API para mais detalhes.

Se os SDKs do lado do cliente não estiverem disponíveis para sua plataforma, consulte Proteger suas chamadas de serviço da Web do lado do cliente.

Para conferir a disponibilidade de SDKs da Plataforma Google Maps no lado do cliente para diferentes plataformas, consulte Restrições recomendadas de API e aplicativo.

Proteger o uso da API Static Web

As APIs Static Web, como Maps Static e Street View Static, são semelhantes às chamadas de API dos serviços da Web.

É possível chamar ambas usando uma API REST HTTPS, e o URL da solicitação de API costuma ser gerado no servidor. No entanto, em vez de retornar uma resposta JSON, as APIs Static Web geram uma imagem que você pode incorporar ao código HTML criado. O mais importante é que geralmente é o cliente do usuário final, não o servidor, que chama o serviço da Plataforma Google Maps.

Usar uma assinatura digital

Como prática recomendada, sempre use assinaturas digitais além da chave de API. Além disso, revise quantas solicitações não assinadas você quer permitir por dia e ajuste as cotas.

Para mais detalhes sobre assinaturas digitais, consulte o Guia de assinatura digital.

Proteger a chave secreta de assinatura

Para proteger as APIs Static Web, não incorpore chaves secretas de assinatura da API diretamente ao código ou à árvore de origem nem exponha nos aplicativos no lado do cliente. Siga estas práticas recomendadas para proteger suas chaves secretas de assinatura:

  • Gerencie URLs de solicitação das APIs Maps Static e Street View Static assinados no lado do servidor ao veicular uma página da Web ou em resposta a uma solicitação do seu app para dispositivos móveis.

    Para conteúdo da Web estático, use o widget Assinar um URL agora na página Credenciais da Plataforma Google Maps no console do Cloud.

    Para conteúdo da Web dinâmico, consulte os exemplos de código de assinatura de solicitações de URL disponíveis.

  • Armazene chaves secretas de assinatura fora do código-fonte e da árvore de origem do seu aplicativo. Se você colocar essas chaves secretas ou qualquer outra informação particular em variáveis de ambiente ou adicionar arquivos armazenados de forma separada e, depois, compartilhar seu código, as chaves secretas de assinatura não vão ser incluídas nos arquivos compartilhados. Se você armazenar chaves secretas de assinatura ou outras informações particulares em arquivos, mantenha esses arquivos fora da árvore de origem do aplicativo para manter as chaves fora do sistema de controle do código-fonte. Essa precaução é especialmente importante se você usa um sistema de gerenciamento de código-fonte público, como o GitHub.

Proteger chaves de API de serviço da Web

Para usar com segurança as APIs e os serviços da Plataforma Google Maps em apps do lado do cliente, consulte Usar SDKs do lado do cliente e Chamadas seguras de serviços da Web do lado do cliente.

Armazene chaves de API fora do código-fonte ou da árvore de origem do seu aplicativo. Se você colocar essas chaves ou outras informações particulares em variáveis de ambiente ou incluir arquivos armazenados de forma separada e, em seguida, compartilhar o código, as chaves de API não serão incluídas nos arquivos compartilhados. Isso é especialmente importante se você usa um sistema de gerenciamento de código-fonte público, como o GitHub.

Para proteger sua chave de API do serviço da Web contra uso acidental, o Google recomenda aplicar restrições de API a qualquer chave usada para a Plataforma Google Maps. Além disso, aplicar restrições de endereço IP à chave do serviço da Web também ajuda a proteger contra o uso não autorizado de outros endereços IP de origem, mesmo que a chave seja divulgada acidentalmente.

Usar o OAuth para apps do lado do servidor

O OAuth 2.0 é um padrão aberto para delegação de acesso.

Embora o protocolo OAuth 2.0 ofereça suporte a casos de uso em que um usuário final autoriza um aplicativo a acessar dados pessoais em nome dele, o caso de uso pretendido para o OAuth 2.0 com a Plataforma Maps é que o desenvolvedor use tokens de acesso temporários para autorizar o aplicativo a chamar uma API em nome da conta de serviço do projeto do Google Cloud com as permissões da conta de serviço.

Como uma conta de serviço pode ter permissões extremamente amplas, o OAuth 2.0 é recomendado para autorizar chamadas de servidor para servidor entre os aplicativos confiáveis do lado do servidor de um desenvolvedor e os servidores da Plataforma Google Maps.

Para aplicativos do lado do cliente em execução em dispositivos do usuário final, outros métodos de autenticação, como chaves de API, são recomendados.

Se você quiser usar o OAuth 2.0 para autorizar o tráfego de servidor para servidor, procure o tópico sobre o OAuth na documentação da API.

Por exemplo, este é o tópico do OAuth para a API Address Validation.

Proteger chamadas de serviço da Web do lado do cliente

Se os SDKs do lado do cliente não estiverem disponíveis, consulte as recomendações abaixo.

Usar um servidor proxy

O uso de um servidor proxy seguro oferece uma fonte sólida para interagir com um endpoint do serviço da Web da Plataforma Google Maps em um aplicativo do lado do cliente sem expor a chave de API, o segredo de assinatura ou a conta de serviço do Google Cloud a usuários não autorizados.

Pontos principais

*   Construct your Google Maps Platform requests on the proxy server.
    **Don't** allow clients to relay arbitrary API calls using the proxy.

*   Post-process the Google Maps Platform responses on your proxy server.
Filter out data that the client doesn't need.

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.

Chamadas diretas seguras de serviços da Web para dispositivos móveis

Se não for possível configurar um servidor proxy seguro para o app do lado do cliente, siga estas etapas para proteger seu aplicativo:

  1. Use cabeçalhos HTTP:

    • Android: use os cabeçalhos HTTP X-Android-Package e X-Android-Cert.

    • iOS: use o cabeçalho HTTP X-Ios-Bundle-Identifier.

  2. Adicione as restrições de aplicativo correspondentes à chave do Android ou iOS.

  3. Antes de emitir chamadas diretamente do seu aplicativo para dispositivos móveis para um serviço da Web da API REST da Plataforma Google Maps, verifique se as solicitações com identificadores de aplicativo Android ou iOS incorretos são rejeitadas.

    Se as restrições de aplicativos Android e iOS não tiverem suporte no endpoint testado, o Google recomenda o uso de um servidor proxy seguro entre os clientes móveis e o endpoint do serviço da Web da Plataforma Google Maps.

Dicas para apps Android:

  • Antes de integrar seu aplicativo Android aos serviços da Plataforma Google Maps, verifique se o ID do aplicativo (também chamado de nome do pacote) está formatado corretamente. Para saber mais, consulte Configurar o módulo do app na documentação do Android.

  • Para transmitir X-Android-Package diretamente do seu aplicativo, pesquise-o de forma programática usando Context.getPackageName().

  • Para transmitir X-Android-Cert diretamente dos seus aplicativos, calcule a impressão digital SHA-1 necessária dos certificados de assinatura do aplicativo, acessível por PackageInfo.signingInfo.

  • Se você autorizar seu aplicativo Android usando o console do Google Cloud, a interface espera que a impressão digital SHA-1 seja uma string delimitada por dois-pontos, por exemplo, 00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33. No entanto, a ferramenta gcloud e a API de chaves de API esperam a string hexadecimal sem delimitadores.

Dicas para aplicativos iOS:

  • Antes de integrar seu aplicativo iOS aos serviços da Plataforma Google Maps, verifique se o ID do pacote está formatado corretamente.

  • Normalmente, é necessário transmitir o ID do pacote principal no cabeçalho X-Ios-Bundle-Identifier ao autorizar o aplicativo iOS.

Para mais informações, consulte os artigos Gerenciar chaves de API e Usar chaves de API para acessar APIs.

Hospedar seus apps baseados em navegador em um servidor

Frameworks, como o Apache Cordova, permitem criar apps híbridos multiplataforma executados em um WebView. No entanto, não há garantia de que as restrições de site da chave de API vão funcionar corretamente, a menos que o app da Web seja carregado usando HTTP ou HTTPS de um site que você controla e autorizou.

Em muitos casos, os recursos agrupados carregados localmente em um aplicativo híbrido ou acessados usando um URL de arquivo local impedem que a autorização baseada em referenciador funcione, já que o mecanismo do navegador que alimenta sua visualização da Web vai omitir o envio do cabeçalho Referer. Para evitar isso, hospede seus aplicativos da Web no servidor, não no cliente.

Como alternativa, para aplicativos para dispositivos móveis, use os SDKs nativos da Plataforma Google Maps para Android e iOS disponíveis em vez de um SDK baseado na Web.

Usar a verificação de app para proteger sua chave de API

Alguns SDKs e APIs do Maps permitem a integração com o Firebase App Check. O App Check oferece proteção para chamadas do seu app para a Plataforma Google Maps, bloqueando o tráfego que vem de fontes diferentes de apps legítimos. Para isso, ele verifica um token de um provedor de atestado. A integração dos seus apps com o App Check ajuda a proteger contra solicitações maliciosas, para que você não seja cobrado por chamadas de API não autorizadas.

Instruções de integração do App Check:

Abordagem para o uso não autorizado de uma chave de API

Se você detectar uso não autorizado da sua chave de API, faça o seguinte para lidar com o problema:

  1. Restrinja suas chaves: se você usou a mesma chave em vários apps, migre para várias chaves de API e use chaves diferentes em cada app. Para mais detalhes, consulte:

  2. Se você usa o SDK do Places ou a API Maps JavaScript, também é possível usar o App Check para proteger sua chave de API.

  3. Só substitua ou gire as chaves se a seguinte condição for verdadeira:

    • Você detectou uso não autorizado em chaves que não podem ser restringidas ou já estão restritas, e a verificação de apps não é aplicável.

    • Você quer proteger sua chave de API e interromper o abuso mais rapidamente, mesmo que isso possa afetar o tráfego legítimo do seu aplicativo.

    Antes de continuar, leia Cuidado ao rotacionar chaves de API.

  4. Se você ainda tiver problemas ou precisar de ajuda, entre em contato com o suporte.

Restrições recomendadas de API e aplicativo

Nas seções abaixo, sugerimos restrições de aplicativo e API apropriadas para cada API, SDK ou serviço da Plataforma Google Maps.

Restrições recomendadas de API

As seguintes diretrizes para restrições de API se aplicam a todos os serviços da Plataforma Google Maps:

  • Restrinja sua chave às APIs que você está usando com ela, exceto nos seguintes casos:

    • Se o app usa o SDK do Places para Android ou o SDK do Places para iOS, autorize a API Places (nova) ou a API Places, dependendo das versões do SDK que você usa. 1

    • Se o app usa a API Maps JavaScript, sempre autorize essa API na sua chave.

    • Se você também usa algum dos seguintes serviços da API Maps JavaScript, autorize as seguintes APIs:

      Serviço Restrição de APIs
      Serviço Directions (legado) API Directions (legada)
      Serviço Distance Matrix (legado) API Distance Matrix (legada)
      Serviço Elevation API Elevation
      Serviço Geocoding API Geocoding
      Classe "Place", widget do Place Autocomplete (novo) e API Place Autocomplete Data API Places (nova)2
      Biblioteca Places, serviço Places e widget Place Autocomplete API Places2

1 Para mais detalhes, consulte a documentação do SDK do Places para Android e do SDK do Places para iOS.

2 Se você não tiver certeza se precisa autorizar a API Places (nova) ou a API Places, consulte a documentação da API Maps JavaScript.

Alguns exemplos:

  • Você está usando o SDK do Maps e o SDK do Places para Android, por isso incluí o SDK do Maps para Android e a API Places (nova) como restrições de API.

  • Seu site usa a API Maps JavaScript, o serviço Elevation Service e a API Maps Static. Portanto, você adiciona restrições a todas estas APIs:

    • API Maps JavaScript
    • API Elevation
    • API Maps Static

Restrição recomendada de aplicativo

Sites

Para sites que usam os serviços da API Maps JavaScript, da API Maps Static ou da API Street View Static ou que chamam os serviços recentes da Plataforma Google Maps diretamente pela API REST HTTPS ou pelo gRPC, use a restrição de aplicativo Sites:

1 Em apps para dispositivos móveis, é recomendável usar o SDK do Maps para Android e o SDK do Maps para iOS nativo.

2 Em apps para dispositivos móveis, considere usar o SDK do Places para Android e o SDK do Places para iOS nativo.

3 Consulte também Proteger o uso da API Static Web.

Sites com a API Maps Embed

Embora o uso da API Maps Embed não tenha custo financeiro, ainda é possível restringir a chave de API usada para evitar abuso em outros serviços.

Prática recomendada: crie outra chave para a API Maps Embed e restrinja apenas à API Maps Embed. Essa restrição protege a chave de forma suficiente, evitando uso não autorizado em qualquer outro Serviço do Google. Para ter controle total sobre onde sua chave de API de incorporação do Maps pode ser usada, o Google recomenda também aplicar restrições de aplicativo Websites.

Se não for possível utilizar a API Maps Embed com uma chave de API diferente, proteja a chave usando a restrição de aplicativo Websites.

Apps e servidores que usam serviços da Web

Para servidores e apps do lado do cliente de redes internas corporativas confiáveis que usam serviços da Web com chaves de API, use a restrição de aplicativo IP addresses.

Apps e servidores que usam estas APIs:

4 Em apps para dispositivos móveis, considere usar o SDK do Navigation.

5 Para uso seguro em dispositivos móveis, use um servidor proxy seguro.

6 Para aplicativos do lado do cliente, considere usar o serviço de geolocalização nativa oferecido pela plataforma. Por exemplo, Geolocalização do W3C para navegadores da Web, LocationManager ou a API Fused Location Provider para Android ou o framework Core Location da Apple para iOS.

7 Em apps para dispositivos móveis, considere usar o SDK do Places para Android e o SDK do Places para iOS nativo.

8 Para uso seguro do lado do cliente, use um servidor proxy seguro.

Apps Android

Em apps Android, utilize a restrição de aplicativo Android apps. Usar para apps que usam estes SDKs:

Além disso, evite a verificação acidental de chaves de API no controle de versões usando o plug-in Secrets Gradle para injetar chaves secretas de um arquivo local em vez de armazená-las no Android Manifest.

Apps iOS

Em apps iOS, utilize a restrição de aplicativo iOS apps. Apps e servidores que usam estes SDKs:

Leitura adicional