Como restringir uma API key do Firebase, passo a passo

Uma API key do Firebase fica na configuração do seu app, então qualquer pessoa que abra seu site ou descompacte seu app pode copiá-la. Isso é esperado: o Firebase diz "API keys for Firebase services are OK to include in code or checked-in config files." (as API keys dos serviços do Firebase podem ser incluídas no código ou em arquivos de configuração versionados) (API keys do Firebase). O problema é uma chave que pode chamar mais do que o seu app precisa. A documentação do Google é direta: "Unrestricted API keys are insecure." (API keys sem restrições são inseguras) (restrições de API keys).

Três das nossas histórias de terror começaram do mesmo jeito, com uma chave pública que também podia chamar o Gemini: US$ 82.314 em 48 horas, €54.000 em 13 horas e US$ 67.000 em 19 horas.

O Firebase restringe as chaves que cria, mas uma chave antiga pode permitir mais do que você imagina. Quando o Firebase restringiu as chaves existentes em maio de 2024, cada uma ficou "restricted to the list of the Firebase-related APIs plus any of the project's currently enabled APIs." (restrita à lista de APIs relacionadas ao Firebase mais qualquer API que o projeto tivesse ativada naquele momento). Uma API paga ativada naquela época continuou na chave.

Abra APIs e serviços > Credenciais no console do Google Cloud e escolha seu projeto: todas as API keys aparecem ali. O Firebase cria uma por plataforma, uma Browser key junto com o projeto e uma chave de iOS ou Android quando você adiciona esses apps. Procure também chaves que você ou alguém do time criou à mão, e as que vieram com outros serviços do Google, como o Maps.

Para ver qual chave cada app usa, vá ao console do Firebase, Configurações do projeto > Geral > Seus apps. Apps web mostram a chave como apiKey no objeto de configuração, apps Android como current_key no google-services.json e apps Apple como API_KEY no GoogleService-Info.plist.

Esta é a restrição que limita o estrago. Sem ela, "an API key can be used to access any API that is enabled for the project." (uma API key pode ser usada para acessar qualquer API ativada no projeto) (API keys do Firebase).

Na página de Credenciais:

1. Clique no nome da chave.
2. Em Restrições de API, escolha Restringir chave.
3. Selecione só as APIs que seu app chama a partir do cliente. Num app Firebase típico, são as APIs do Firebase que ele usa, como Identity Toolkit para o Auth, Cloud Firestore e Firebase Installations.
4. Clique em Salvar.

Cuidado com as chaves de produção. Se você remover uma API de que o app precisa, as chamadas falham com um erro API_KEY_SERVICE_BLOCKED. O Firebase mantém uma lista das APIs que cada serviço do Firebase precisa: confira antes de remover uma, e teste a mudança primeiro numa chave de testes.

Pela linha de comando, liste as chaves para obter os IDs e depois defina as APIs. A lista que você passa é a lista inteira: "the service names provided replace any existing services on the key." (os nomes de serviço informados substituem os que a chave já tem)

gcloud services api-keys list --project=PROJECT_ID

gcloud services api-keys update KEY_ID \
  --api-target=service=identitytoolkit.googleapis.com \
  --api-target=service=securetoken.googleapis.com \
  --api-target=service=firestore.googleapis.com \
  --api-target=service=firebaseinstallations.googleapis.com

As restrições de aplicativo dizem quais sites ou apps podem usar a chave. Sem elas, nas palavras do Google, "API keys without application restrictions can be used from anywhere." (API keys sem restrições de aplicativo podem ser usadas de qualquer lugar). Cada chave aceita um único tipo: "You can apply only one application restriction type at a time." (você só pode aplicar um tipo de restrição de aplicativo por vez). Escolha o que corresponde à chave (restrições de API keys):

• Sites. Na Browser key, adicione seus domínios como referenciadores HTTP. Para liberar um site inteiro, a documentação do Google usa duas entradas, example.com/* e *.example.com/*. Use uma chave separada para localhost em vez de adicioná-lo à chave de produção.
• Apps Android. Adicione o nome do pacote e a impressão digital SHA-1 de cada certificado de assinatura.
• Apps iOS. Adicione o bundle ID.

Trate isso como um filtro, não como uma tranca. Sobre as restrições de Android e iOS, o Google avisa: "Bypassing this restriction is straightforward." (contornar essa restrição é simples). O referenciador também é só um cabeçalho, e um script fora do navegador pode enviar o valor que quiser. As restrições de aplicativo impedem o reúso casual da sua chave. As restrições de API do passo 2 são as que limitam a fatura.

O conselho do Firebase é direto: "never include the Gemini Developer API in the allowlist for a publicly accessible API key or a key used for other services." (nunca inclua a Gemini Developer API na lista de uma API key pública ou de uma chave usada para outros serviços) (API keys do Firebase). O mesmo vale para qualquer API cobrada do Google Cloud, como Maps, Vision ou Translation. Dê a ela uma chave separada que só possa chamar essa API, para poder restringir, rotacionar ou apagar sem mexer no Firebase.

Se o seu servidor chama a Gemini Developer API, essa chave é um segredo de verdade. O Firebase diz que ela "should never be included in your code or configuration files." (nunca deve ser incluída no seu código nem nos seus arquivos de configuração). Guarde-a nos segredos do seu backend, nunca no app.

Se o seu app chama o Gemini pelo Firebase AI Logic, as requisições passam pelo Firebase e não há chave do Gemini no cliente. Mesmo assim, qualquer pessoa com a configuração do seu app pode tentar enviá-las, então proteja-as com App Check e uma cota diária na API (como definir limites).

Uma chave que nunca deveria ser pública, como uma chave de servidor enviada para um repositório, precisa de mais do que restrições. Rotacione: na página da chave, clique em Rotacionar chave. O Google cria uma chave nova com as mesmas restrições, você passa seus apps e servidores para ela e depois apaga a anterior (rotacionar uma API key).

Uma chave do Firebase dentro de um app publicado é diferente. Cada cópia instalada a tem, então rotacioná-la quebra as versões antigas. Para essa chave, a solução são as restrições acima.

Uma chave restrita ainda pode chamar todas as APIs da lista, quantas vezes alguém quiser. Três camadas cobrem isso: as Security Rules decidem quem lê e escreve quais dados, o App Check rejeita requisições que não vêm do seu app real e as cotas limitam quantas chamadas uma API aceita por dia. Como limitar os gastos no Firebase explica cada uma.

E quando algo passa mesmo assim, o FireShield vigia o uso de cada API a cada poucos minutos. Um serviço sem tráfego que de repente recebe milhares de requisições, como o Gemini nas três histórias acima, é detectado em minutos e pode disparar uma ação, até desconectar o faturamento.