Saiba como usar e gerenciar chaves de API para o Firebase

Uma chave de API é uma string exclusiva usada para encaminhar solicitações a seu projeto do Firebase quando você interage com os serviços do Firebase e do Google. Nesta página, você encontra as informações básicas sobre as chaves de API, além das práticas recomendadas para usar e gerenciar essas chaves com os apps do Firebase.

Informações gerais sobre chaves de API e o Firebase

Chaves de API para Firebase são diferentes das chaves de API tradicionais

Diferentemente da forma como as chaves de API costumam ser usadas, as chaves de API para serviços do Firebase não são usadas para controlar o acesso aos recursos de back-end, que só pode ser realizado com as regras de segurança do Firebase (para controlar quais usuários podem acessar recursos) e App Check (para controlar quais apps podem acessar os recursos).

Normalmente, é necessário proteger rapidamente as chaves de API, por exemplo, usando um serviço do Vault ou definindo as chaves como variáveis de ambiente. No entanto, é possível incluir chaves de API para serviços do Firebase em arquivos de configuração ou códigos de configuração de check-in.

Embora as chaves de API para serviços do Firebase sejam seguras e possam ser incluídas no código, existem alguns casos específicos para quando você precisa limitar sua chave de API. Por exemplo, se você usa o Firebase ML, o Firebase Authentication com método de login com e-mail/senha ou uma API faturável do Google Cloud. Saiba mais sobre esses casos posteriormente nesta página.

Proteja seu banco de dados e as informações do Cloud Storage usando as regras de segurança do Firebase sem restringir e/ou ocultar as chaves de API.

Como criar chaves de API

Um projeto do Firebase pode ter muitas chaves de API, mas cada uma delas só pode ser associada a um único projeto do Firebase.

O Firebase cria automaticamente chaves de API para seu projeto quando você realiza uma das seguintes ações:

• cria um projeto do Firebase > Browser key criado automaticamente;
• cria um app para Apple do Firebase > iOS key criado automaticamente;
• cria um app Android do Firebase > Android key criado automaticamente.

Importante: por padrão, as chaves de API criadas automaticamente pelo Firebase não têm restrições. No entanto, há alguns casos específicos em que é recomendado definir limites para a chave de API.

Também é possível criar suas próprias chaves de API no Console do Google Cloud, por exemplo, para desenvolvimento ou depuração. Mais a frente nesta página, saiba mais sobre quando isso pode ser recomendado.

Como encontrar chaves de API

É possível ver e gerenciar todas as chaves de API do seu projeto no painel APIs e serviços > Credenciais no console do Google Cloud.

Outra opção é descobrir nos locais a seguir qual chave de API corresponde automaticamente a um app do Firebase. Por padrão, todos os apps do Firebase do seu projeto na mesma plataforma (Apple x Android x Web) usarão a mesma chave de API.

• Apps para Apple do Firebase: encontre a chave de API com correspondência automática de um app no arquivo de configuração do Firebase, GoogleService-Info.plist, no campo API_KEY.

• Apps Android do Firebase: encontre a chave de API com correspondência automática de um app no arquivo de configuração do Firebase, google-services.json, no campo current_key.

• Apps da Web do Firebase: encontre a chave de API com correspondência automática de um app no objeto de configuração do Firebase, no campo apiKey.

Como usar uma chave de API

As chaves de API são usadas para identificar seu projeto do Firebase durante a interação com os serviços do Firebase/Google. Elas são usadas especificamente para associar solicitações de API ao projeto para cota e faturamento. Elas também são úteis para acessar dados públicos.

Por exemplo, é possível usar explicitamente uma chave de API transmitindo o valor dela para uma chamada da API REST como um parâmetro de consulta. Este exemplo mostra como é possível fazer uma solicitação para o encurtador de link da API Dynamic Links:

POST https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY

Quando seu app faz uma chamada para uma API do Firebase, ele verifica automaticamente a chave da API do projeto no arquivo/objeto de configuração do Firebase. No entanto, é possível definir suas chaves de API usando um mecanismo diferente, incluindo variáveis de ambiente.

Aplicar restrições a chaves de API (recomendado)

Não é necessário tratar uma chave de API para serviços do Firebase como um secret, mas há alguns casos específicos (veja abaixo) em que é possível adotar medidas extras para proteger seu projeto do uso indevido da chave.

Se uma chave de API estiver sendo usada por um app de produção, tome cuidado ao adicionar restrições a essa chave. É necessário testar as restrições em um app de teste e com uma chave de API de teste antes de adicionar restrições à sua chave de API de produção.

Observação: se você aplicar restrições a uma chave de API usada para acessar os serviços do Firebase e receber erros, talvez seja necessário incluir a API Firebase Management na lista de APIs permitidas. Isso ocorre principalmente quando você usa o Google Analytics com um app da Web.

Reduzir cota em caso de uso de autenticação com base em senha

Independentemente da opção de autenticação usada, proteja o banco de dados e dados do Cloud Storage usando Regras de segurança do Firebase.

Se você usar o Firebase Authentication com senha e alguém conseguir sua chave de API, essa pessoa não terá acesso aos dados do Cloud Storage ou do banco de dados do projeto do Firebase, desde que essas informações estejam protegidas pelas regras de segurança do Firebase. No entanto, ela poderá usar a chave de API para acessar os endpoints de autenticação do Firebase e fazer solicitações de autenticação para o projeto.

Para reduzir a possibilidade de alguém usar uma chave de API de forma indevida para tentar um ataque de força bruta, é possível reduzir a cota padrão dos endpoints identitytoolkit.googleapis.com para refletir as expectativas normais de tráfego do seu app. Lembre-se de que, se você reduzir essa cota, e seu app ganhar muitos usuários, erros de login poderão acontecer até você aumentar a cota. É possível alterar as cotas da API do seu projeto no Console do Google Cloud.

Usar chaves de API restritas e separadas para tipos específicos de APIs

As chaves de API utilizadas para serviços do Firebase geralmente não precisam ser tratadas como secrets. Mesmo assim, tome algumas precauções extras com as chaves de API usadas para conceder acesso às APIs do Google Cloud que você ativou manualmente.

Se você usa uma API do Google Cloud (em qualquer plataforma) que não é ativada automaticamente pelo Firebase (ou seja, que você ativou por conta própria), considere criar chaves restritas e separadas para usar com essas APIs. Isso é importante se a API for de um serviço faturável do Google Cloud.

Por exemplo, se você utiliza as APIs Cloud Vision do Firebase ML no iOS, crie chaves de API separadas que serão usadas apenas para acessar essas APIs.

Ao usar chaves de API separadas e restritas para APIs que não são do Firebase, é possível girar ou substituir as chaves quando necessário e adicionar outras restrições às chaves de API, sem interromper o uso dos serviços do Firebase.

Expanda esta seção para saber como criar chaves específicas da API

Com estas instruções, você aprenderá a criar uma chave de API restrita e separada para uma API falsa chamada Super Service API.

Etapa 1: configure suas chaves de API atuais para proibir o acesso a Super Service API

1. Abra a página Credenciais do Console do Google Cloud. Quando solicitado, selecione o projeto.

2. Para cada chave de API na lista, abra a visualização de edição.

3. Na seção Restrições da API, selecione Restringir chave e adicione à lista de todas as APIs que você quer que a chave tenha acesso. Não inclua a API para a qual você está criando a chave separada (exemplo: Super Service API).

   Quando você configura as restrições de API de uma chave de API, declara explicitamente as APIs a que a chave tem acesso. Por padrão, quando a seção Restrições da API tiver a opção Não restringir a chave selecionada, uma chave de API poderá ser usada para acessar qualquer API ativada para o projeto.

Agora, suas chaves de API existentes não concederão acesso a Super Service API, mas continuarão funcionando para as APIs adicionadas à lista de restrições da API.

Importante: se você ativar outras APIs no futuro, será necessário adicioná-las à lista de restrições da API da chave.

Etapa 2: crie e use uma nova chave de API para acessar o Super Service API

1. Volte para a página Credenciais. Verifique se seu projeto do Firebase ainda está selecionado.

2. Clique em Criar credenciais > Chave de API. Anote a nova chave de API e clique em Restringir chave.

3. Na seção Restrições da API, selecione Restringir chave e adicione à lista somente a Super Service API.

   Essa nova chave de API concede acesso somente à Super Service API.

4. Configure o app e os serviços para usar a nova chave de API.

Usar chaves de API específicas do ambiente (recomendado)

Se você configurar diferentes projetos do Firebase para diferentes ambientes, como preparação e produção, é importante que cada instância do app interaja com o projeto do Firebase correspondente. Por exemplo, sua instância de app de teste nunca deve se comunicar com o projeto de produção do Firebase. Isso também significa que seu app de teste precisa usar chaves de API associadas ao projeto de teste do Firebase.

Para minimizar os problemas ao fazer alterações no código desde o desenvolvimento até o preparo e a produção, em vez de incluir chaves de API no próprio código, defina-as como variáveis de ambiente ou adicione-as a um arquivo de configuração.

Se você estiver usando o pacote do emulador local do Firebase para desenvolvimento com o Firebase ML, será preciso criar e aplicar uma chave de API exclusiva para depuração. As instruções para criar esse tipo de chave estão na documentação do Firebase ML.

Perguntas frequentes

Como posso determinar qual chave de API está associada ao meu app do Firebase?

Você pode usar qualquer uma das opções a seguir para determinar qual chave de API está associada ao seu app do Firebase:

Console do Firebase

1. Acesse Configurações do projeto e role para baixo até o card Seus apps.

2. Selecione o app desejado.

3. Consiga o objeto/arquivo de configuração do Firebase para o app e encontre a chave de API:

   • Apple: faça o download de GoogleService-Info.plist e localize o campo API_KEY.

   • Android: faça o download de google-services.json, localize a configuração do app desejado (procure o nome do pacote) e o campo current_key.

   • Web: selecione a opção Configuração e localize o campo apiKey.

CLI do Firebase

1. Consiga o objeto/arquivo de configuração do Firebase para o app desejado executando o comando a seguir:

   firebase apps:sdkconfig PLATFORM FIREBASE_APP_ID

   • PLATFORM (uma destas): IOS | ANDROID | WEB
   • FIREBASE_APP_ID: o identificador exclusivo atribuído pelo Firebase para seu app (encontre o ID do aplicativo)

2. Na configuração registrada do app do Firebase, encontre a chave de API:

   • Apple: encontre o campo API_KEY.

   • Android: encontre a configuração do app desejado (procure o nome do pacote) e, em seguida, o campo current_key.

   • Web: encontre o campo apiKey.

API REST

1. Para conseguir o apiKeyId (UID) da chave de API, chame o endpoint aplicável do app desejado e transmita o valor apiKeyId para a próxima etapa.

   • Apple: chame projects.iosApps.get.
   • Android: chame projects.androidApps.get.
   • Web: chame projects.webApps.get

2. Consiga a string da chave de API chamando projects.locations.keys.getKeyString.

   Esse keyString é o mesmo valor que pode ser encontrado no artefato de configuração do app (Apple | Android | Web).

Posso ter duas chaves de API listadas para o mesmo app do Firebase no meu objeto/arquivo de configuração?

• Apps para Apple do Firebase: cada app tem o próprio arquivo de configuração e pode ter apenas uma chave de API listada.

• Apps Android do Firebase: todos os apps para Android no projeto do Firebase são listados no mesmo arquivo de configuração, e cada app pode ter apenas uma chave de API listada. No entanto, cada app nesse arquivo de configuração pode ter uma chave diferente listada.

• Apps da Web do Firebase: cada app tem o próprio objeto de configuração e pode ter apenas uma chave de API listada.

No entanto, é possível usar várias chaves de API com um app. É necessário fornecer um mecanismo para que o app acesse essas outras chaves de API, como, por exemplo, usando uma variável de ambiente. O mecanismo de acesso a outras chaves de API não pode depender das que estão listadas no arquivo/objeto de configuração do Firebase.

Como o Firebase sabe qual chave de API corresponde a um app (como no objeto/arquivo de configuração)?

Quando você acessar o objeto/arquivo de configuração do seu app, o Firebase vai verificar se existem chaves de API no projeto com Restrições de aplicativos que correspondem ao app (por exemplo, um ID de pacote correspondente para o app da Apple).

Se o Firebase não encontrar chaves restritas correspondentes, ele vai listar no objeto/arquivo de configuração iOS key para apps da Apple, Android key para apps Android e Browser key para apps da Web (presumindo que essas chaves existam e não tenham "Restrições de aplicativo" que impeçam a correspondência com o app).

Posso excluir manualmente a chave e o campo da API do meu arquivo/objeto de configuração do Firebase?

Sim, é possível excluir manualmente sua chave de API do arquivo/objeto de configuração. No entanto, é preciso fornecer outro mecanismo para que o aplicativo acesse uma chave de API, por exemplo, por meio de uma variável de ambiente. Caso contrário, as chamadas para os serviços do Firebase falharão.

Posso editar manualmente meu arquivo/objeto de configuração do Firebase com chaves de API diferentes?

Sim, é possível editar manualmente um arquivo/objeto de configuração para associar uma outra chave de API a um app.

É possível editar manualmente a chave de API no seu arquivo/objeto de configuração do Firebase, mas, geralmente, não é recomendado. Isso aumenta as chances de problemas de acesso aos serviços do Firebase. No entanto, se você editar seu arquivo/objeto de configuração, verifique o seguinte:

• O escopo da chave de API é definido como o ID do projeto listado no objeto/arquivo de configuração.
• Não há Restrições de chave de API que impeçam a chave da API de ser usada com esse app.

Se você recuperar o objeto/arquivo de configuração do app no console, ele sempre vai listar as chaves de API que o Firebase corresponde automaticamente com esse app. Assim, você precisará repetir as edições manuais conforme necessário.

Posso mover uma chave de API de um projeto do Firebase para outro?

Não, uma chave de API identifica apenas um projeto específico e não pode ser movida para outro.

Recebi um e-mail ou erro informando que minha chave de API é inválida. O que aconteceu e como posso corrigir isso?

Veja a seguir algumas das causas mais comuns de chaves de API inválidas:

• A chave de API tem Restrições aplicadas a ela. Isso a torna incompatível com o app que tenta usar a chave (Restrições de aplicativo) ou inutilizável para a API chamada (Restrições de API).

• A chave de API foi excluída do projeto no Console do Google Cloud.

• A chave de API não foi criada para o ID do projeto listado no objeto/arquivo de configuração do Firebase para o app.

Uma maneira de corrigir esse problema é conseguir a versão atualizada do objeto/arquivo de configuração do Firebase do seu app e substituir o antigo pelo novo. Antes de enviar um arquivo de configuração para download ou exibir um objeto de configuração no console, o Firebase verifica se as chaves de API listadas correspondem aos apps.

Como posso corrigir este erro? "Falha ao buscar o ID de métricas do app do Firebase no servidor."

A chave de API usada pelo app da Web provavelmente tem Restrições de API aplicadas a ela. Nesse caso, verifique se a API Firebase Management está na lista de APIs permitidas.

O que vai acontecer se eu excluir uma chave de API listada no console do Google Cloud?

Se você excluir uma chave de API que está sendo usada por um app, as chamadas de API dele falharão. Talvez você receba relatórios, e-mails ou erros ao tentar usar uma chave de API inválida.

A exclusão de uma chave de API é permanente e não pode ser desfeita.