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 compatível, o OAuth 2.0 para se autenticar.

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

Se 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. Confira mais detalhes em Usar o OAuth para apps do lado do servidor.

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, compatíveis com as APIs Maps Static e 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 fazer a rotação das chaves de API

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

Desativar serviços não utilizados

Outras recomendações para apps do lado do cliente

Usar SDKs do lado do cliente

Proteger chamadas de serviço da Web 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 de serviços 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 a 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 abusiva, você poderá migrar seus apps para várias chaves novas no seu próprio ritmo e manter a original até que haja apenas um tipo de tráfego. Assim, a chave de API poderá ser restringida com segurança a um único tipo de restrição de aplicativo sem causar interrupções não intencionais 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 protegê-la e deter o abuso. Em apps Android e iOS, as chaves não são substituídas até que os clientes façam a atualização dos aplicativos. Atualizar ou substituir chaves em páginas da Web ou em apps do lado do servidor é muito mais simples, mas ainda pode exigir planejamento cuidadoso e 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 limitar 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 para aplicativos no lado do cliente, endereços IP ou sub-redes do CIDR de 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 dos tipos que 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 no 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 há garantia de 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 inteira do referenciador, 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.

    1. Selecione Apps Android.
    2. Clique em + Adicionar.
    3. Insira o nome do pacote e a impressão digital do certificado SHA-1. Exemplo: 
      com.example.android.mapexample
       
      BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
    4. Clique em Salvar.

    Há dois tipos de certificado:

    • Certificado de depuração: use esse tipo apenas com apps em teste e outros códigos que não sejam de produção. Não tente publicar um app assinado com um certificado de depuração. As ferramentas do SDK do Android geram esse certificado automaticamente quando você executa uma versão de depuração.
    • Certificado de lançamento: use esse tipo quando tudo estiver pronto para lançar seu aplicativo em uma app store. As Ferramentas do SDK do Android geram esse certificado quando você executa um build de lançamento.

    Para mais informações sobre assinatura e certificados de app Android, consulte o guia de assinatura de apps.

    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.

    1. Selecione Apps iOS.
    2. Clique em + Adicionar.
    3. Adicione o ID do pacote para aceitar solicitações do app iOS com esse ID.
    4. Clique em Salvar.

    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 no 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.

Confira mais detalhes sobre as 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 utilização indesejada. 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 excluir 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 detalhes sobre restrições sugeridas, 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 do Metrics Explorer: 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 seja necessário usar restrições de endereço IP para limitar a chave de fato.

    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 plataformas:seu tráfego não pode ser protegido de forma adequada 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 alternar 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 compatíveis com as recomendações automáticas

  • API Maps JavaScript, incluindo serviço Directions (legado), serviço Distance Matrix (legado), serviço Elevation, serviço Geocoding, classe Place, widget Place Autocomplete (novo), API Place Autocomplete Data, biblioteca Places, serviço Places, widget Place Autocomplete e kit de interface do usuário Places

  • API Maps Static e API Street View Static

  • API Maps Embed

  • SDK do Maps para Android, SDK do Navigation para Android, SDK Places para Android e kit de interface do Places no Android

  • SDK do Maps para iOS, SDK Navigation para iOS, SDK Places para iOS, SDK Places Swift para iOS e kit de interface do Places no iOS.

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

Motivos para não receber recomendações

  • Você está usando a chave de API em outros serviços além da Plataforma Google Maps ou em serviços da Plataforma Google Maps 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 é legítimo o uso da API no Metrics Explorer do console do Google Cloud.

    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 incluídos na 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ê começou a usar há pouco tempo 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 é legítimo o uso da API no Metrics Explorer do console do Google Cloud.

    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 incluídos na 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 urgentemente restringir uma chave, por exemplo, devido a uso não autorizado, talvez seja melhor 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 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 no 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 sugestão seja atualizada.

    • Se precisar de mais ajuda com a recomendação, 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 de origem cruzada por motivos de privacidade, muitas vezes reduzindo-o ao Origin. No entanto, o comportamento exato depende da referrer-policy aplicada ao site host e também pode variar de acordo com o navegador e a versão do usuário.

Os aplicativos da Web que usam esquemas de URI opacos ou locais para carregar conteúdo geralmente fazem com que o navegador ou a WebView de renderização oculte completamente o cabeçalho Referer de todas as chamadas de saída, o que pode fazer com que as solicitações falhem ao usar chaves de API com restrições de site.

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

Instruções para resolver problemas em apps baseados em navegador e WebView:

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

    Esquemas de URI exóticos são parcialmente compatíveis. Se partes do seu aplicativo não funcionarem com um esquema de URI exótico, mesmo depois de autorizar o referenciador 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.

  • Outras APIs da Plataforma Maps geralmente 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.

    Esquemas de URI exóticos não são compatíveis.

Apps Android

Use o Android Debug Bridge (adb) ou o Logcat

Apps iOS

Consulte Como visualizar mensagens de registro.

Apps que chamam serviços da Web diretamente

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

Apps Android e iOS

Se o aplicativo Android ou iOS chamar os serviços da Plataforma Google Maps diretamente sem usar nenhum dos SDKs de cliente disponíveis da Plataforma Google Maps, consulte Apps Android e Apps iOS para mais dicas de solução de problemas e Chamadas seguras de serviços da Web do lado do cliente para conhecer 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ê aplicou restrições de endereço IP à sua chave e o serviço registra 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 a API Maps Static, a API Street View Static e as APIs mais recentes da Plataforma Google Maps também ofereçam suporte a restrições de referenciador, observe que os navegadores da Web ou webviews provavelmente vão restringir o cabeçalho Referer ao Origin para solicitações de origem cruzada e provavelmente vão omitir o envio dele por completo, por exemplo, para recursos acessados localmente ou para recursos veiculados por protocolos diferentes de HTTP ou HTTPS.

Se não for possível usar a API Maps JavaScript no seu aplicativo e as restrições de site não funcionarem, consulte Proteger chamadas de serviço da Web do lado do cliente para saber como emitir chamadas de serviço da Web da Plataforma Google Maps com segurança no seu aplicativo do lado do cliente baseado em navegador.

Dicas para verificar restrições de API

Para verificar as restrições de API necessárias, consulte Determinar as APIs que usam sua 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 no 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 conclusão da propagação, todo tráfego que usar a chave de API excluída será recusado.

Cuidado ao fazer a rotação de chaves de API

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 restringir 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 acima, e você tiver que alternar sua chave de API para evitar o uso não autorizado:

  1. Abra a página Credenciais da Plataforma Google Maps no 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 página da nova 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: nos aplicativos para dispositivos móveis, esse processo pode levar meses até que todos os usuários atualizem com a versão mais recente e a nova chave de API.

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

Se você precisar chamar os serviços da Plataforma Google Maps em aplicativos do lado do servidor e diretamente em aplicativos do lado do cliente executados em dispositivos do usuário final, o Google recomenda dividir o uso entre dois projetos separados.

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

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

Desativar serviços não utilizados

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

Adicionar restrições de API a uma chave impede o uso dela em serviços para os quais não foi autorizada, 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 do lado do cliente, você sempre poderá aplicar as restrições adequadas à sua 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 App Check do Firebase nas superfícies de API da Plataforma Google Maps que oferecem suporte a ele. Consulte Usar o App Check 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 Proteja suas chamadas de serviço da Web do lado do cliente.

Para saber mais sobre a disponibilidade de SDKs da Plataforma Google Maps do 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. Confirme também 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:

  • Gere URLs de solicitação assinados das APIs Maps Static e Street View Static no lado do servidor ao veicular uma página da Web ou em resposta a uma solicitação do seu aplicativo 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 dinâmico da Web, consulte os exemplos de código disponíveis para assinatura de solicitação de URL.

  • 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 essas chaves ou outras informações particulares em arquivos, mantenha esses documentos fora da árvore de origem do aplicativo e, portanto, 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ços 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 Proteger chamadas 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 adicionar arquivos armazenados de forma separada e, depois, compartilhar seu código, as chaves de API não vão ser 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 de serviço da Web contra uso acidental, o Google recomenda aplicar restrições de API a qualquer chave usada na Plataforma Google Maps. Além disso, aplicar restrições de endereço IP à chave do serviço da Web ajuda a proteger contra uso não autorizado de outros endereços IP de origem, mesmo que a chave vaze 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 utilize 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 muito 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 executados em dispositivos de usuários finais, recomendamos outros métodos de autenticação, como chaves de API.

Se 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, confira as recomendações abaixo.

Usar um servidor proxy

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

Pontos principais

  • Construa solicitações da Plataforma Google Maps no servidor proxy. Não permita que os clientes redirecionem chamadas de API arbitrárias usando o proxy.

  • Faça o pós-processamento das respostas da Plataforma Google Maps no seu servidor proxy. Filtre os dados que o cliente não precisa.

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).

Proteger chamadas diretas de serviços da Web para dispositivos móveis

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

  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 à sua chave do Android ou iOS.

  3. Antes de fazer 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 aplicativos Android ou iOS incorretos são rejeitadas.

    Se as restrições de aplicativos Android e iOS não forem compatíveis com o 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 mais detalhes, consulte Configurar o módulo do app. na documentação do Android.

  • Para transmitir X-Android-Package diretamente do seu aplicativo, procure-o programaticamente 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íveis em PackageInfo.signingInfo.

  • Se você autorizar seu aplicativo Android usando o console do Google Cloud, observe que 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 API Keys 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, você sempre precisa transmitir o ID do pacote do seu pacote principal no cabeçalho X-Ios-Bundle-Identifier ao autorizar seu aplicativo iOS.

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

Hospede seus apps baseados em navegador em um servidor

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

Recursos agrupados, carregados localmente em um aplicativo híbrido ou acessados usando um URL de arquivo local, em muitos casos, impedem que a autorização baseada em referenciador funcione, já que o mecanismo do navegador que alimenta sua WebView omite 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 disponíveis da Plataforma Google Maps para Android e iOS em vez de um SDK baseado na Web.

Usar o App Check 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 à Plataforma Google Maps, bloqueando o tráfego que vem de fontes diferentes de apps legítimos. Isso é feito verificando 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 receba cobranças 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 o seguinte for verdadeiro:

    • Você detecta o uso não autorizado em chaves que não podem ser restritas ou já estão restritas, e o App Check não é aplicável.

    • Você quer agir rápido para proteger a chave de API e deter o abuso, mesmo que isso afete o tráfego legítimo do aplicativo.

    Antes de continuar, leia Cuidado ao fazer a rotação de 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 seu app usa o SDK do Places para Android ou para iOS, autorize a API Places (nova) ou a API Places, dependendo das versões do SDK que você usa. 1

    • Se o app utiliza 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 APIs correspondentes:

      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 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 inclua o SDK do Maps para Android e a API Places (nova) como restrições de API.

  • Seu site usa as APIs Maps JavaScript, Elevation Service e Maps Static, então você adiciona restrições a todas estas APIs:

    • API Maps JavaScript
    • API Elevation
    • API Maps Static

Restrição recomendada de aplicativo

Sites

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

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

2 Em aplicativos 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 da API Maps Embed pode ser usada, o Google recomenda também aplicar restrições de aplicativo de Sites da Web.

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

Apps e servidores que usam serviços da Web

Para servidores e apps do lado do cliente de redes corporativas internas 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 Navigation.

5 Para usar dispositivos móveis com segurança, use um servidor proxy seguro.

6 Para aplicativos do lado do cliente, considere usar o serviço de geolocalização nativo oferecido pela plataforma. Por exemplo, W3C Geolocation para navegadores da Web, LocationManager ou a API Fused Location Provider para Android ou a estrutura 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 um uso seguro do lado do cliente, use um servidor proxy seguro.

Apps Android

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

Além disso, evite verificar acidentalmente as 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 manifesto do Android.

Apps iOS

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

Leitura adicional