Codelab do App Check para Web

1. Introdução

Última atualização:23/02/2023

Como impedir o acesso não autorizado aos seus recursos do Firebase?

Use o Firebase App Check para impedir que clientes não autorizados acessem os recursos de back-end. Para isso, exija que as solicitações recebidas venham com um atestado de que a solicitação é do seu app original e bloqueie o tráfego sem um atestado adequado. O Firebase App Check depende de provedores de atestado específicos da plataforma para verificar a autenticidade do cliente. Para apps da Web, o App Check oferece suporte ao reCAPTCHA v3 e ao reCAPTCHA Enterprise como provedores de atestado.

O App Check pode ser usado para proteger solicitações ao Cloud Firestore, ao Realtime Database, ao Cloud Functions, ao Firebase Authentication com o Identity Platform e em back-ends hospedados por você.

O que você vai criar

Neste codelab, você vai proteger um aplicativo de chat primeiro adicionando e depois aplicando o App Check.

O que você aprenderá

• Como monitorar seu back-end para detectar acesso não autorizado
• Como adicionar a aplicação ao Firestore e ao Cloud Storage
• Como executar seu aplicativo com um token de depuração para desenvolvimento local

O que é necessário

• O IDE/editor de texto de sua escolha
• O gerenciador de pacotes npm, que geralmente vem com o Node.js
• A CLI do Firebase instalada e configurada para funcionar com sua conta
• Um terminal/console
• Um navegador da sua escolha, como o Chrome
• O exemplo de código do codelab. Consulte a próxima etapa para saber como acessar o código.

2. Acessar o exemplo de código

Clone o repositório do GitHub (link em inglês) do codelab na linha de comando:

git clone https://github.com/firebase/codelab-friendlychat-web

Se preferir, e se você não tiver o Git instalado, baixe o repositório como um arquivo ZIP.

O repositório friendlychat-web contém projetos de exemplo para várias plataformas.

Este codelab usa apenas estas duas pastas:

• 📁 appcheck-start: o código inicial que você vai usar como base neste codelab.
• 📁 appcheck: o código completo do app de amostra finalizado.

Observação: se você quiser executar o app finalizado, crie um projeto do Firebase no console do Firebase. Consulte as instruções na seção Criar e configurar um projeto do Firebase deste codelab.

Importar o app inicial

Usando seu ambiente de desenvolvimento integrado, abra ou importe o diretório 📁 appcheck-start do repositório clonado. O diretório 📁 appcheck-start contém o código inicial do codelab, que será um app de chat da Web totalmente funcional. O diretório 📁 appcheck terá o código concluído do codelab.

3. Criar e configurar um projeto do Firebase

Criar um projeto do Firebase

1. Faça login no console do Firebase usando sua Conta do Google.
2. Clique no botão para criar um projeto e insira um nome (por exemplo, FriendlyChat).
   

   Esse nome é usado como um nome de exibição nas interfaces do Firebase, e o Firebase cria automaticamente um ID exclusivo com base nele. Se quiser, clique no ícone Editar agora para definir o ID do projeto que preferir, mas não é possível mudar esse ID depois da criação do projeto.

   Lembre-se do ID do projeto porque você vai precisar dele mais tarde para identificar seu projeto do Firebase na CLI do Firebase. Se você esquecer seu ID, é possível encontrá-lo mais tarde nas Configurações do projeto.

3. Clique em Continuar.
4. Se solicitado, leia e aceite os Termos do Firebase e clique em Continuar.
5. (Opcional) Ative a assistência de IA no console do Firebase (chamada de "Gemini no Firebase").
6. Neste codelab, você não precisa do Google Analytics. Portanto, desative a opção do Google Analytics.
7. Clique em Criar projeto, aguarde o provisionamento e clique em Continuar.

Fazer upgrade do plano de preços do Firebase

Para usar o Cloud Storage para Firebase, seu projeto do Firebase precisa estar no plano de preços de pagamento por uso (Blaze), o que significa que ele está vinculado a uma conta do Cloud Billing.

• Uma conta do Cloud Billing exige uma forma de pagamento, como cartão de crédito.
• Se você ainda não conhece o Firebase e o Google Cloud, confira se tem qualificação para receber um crédito de US$300 e uma conta de teste sem custos financeiros do Cloud Billing.
• Se você estiver fazendo este codelab como parte de um evento, pergunte ao organizador se há créditos do Cloud disponíveis.

Para fazer upgrade do seu projeto para o plano Blaze, siga estas etapas:

1. No console do Firebase, selecione Fazer upgrade do seu plano.
2. Selecione o plano Blaze. Siga as instruções na tela para vincular uma conta do Cloud Billing ao seu projeto.
   Se você precisou criar uma conta do Cloud Billing como parte desse upgrade, talvez seja necessário voltar para o fluxo de upgrade no console do Firebase para concluir o processo.

Observação: você pode fazer downgrade do seu projeto para o plano de preços sem custo financeiro (Spark) depois de concluir este codelab.

Adicionar um app da Web do Firebase ao projeto

1. Clique no ícone da Web para criar um app da Web do Firebase.
2. Registre o app com o apelido Friendly Chat e marque a caixa ao lado de Também configurar o Firebase Hosting para este app. Clique em Registrar app.
3. Na próxima etapa, você vai encontrar um comando para instalar o Firebase usando o npm e um objeto de configuração. Você vai copiar esse objeto mais tarde no codelab. Por enquanto, pressione Próxima.

4. Em seguida, você vai encontrar uma opção para instalar a CLI do Firebase. Se ainda não tiver feito isso, instale agora usando o comando npm install -g firebase-tools. Depois clique em Next.
5. Em seguida, você verá uma opção para fazer login no Firebase e implantar no Firebase Hosting. Faça login no Firebase usando o comando firebase login e clique em Continuar para o console. Você vai implantar no Firebase Hosting em uma etapa futura.

Configurar produtos do Firebase

O aplicativo que vamos criar usa produtos do Firebase disponíveis para apps da Web:

• Firebase Authentication para permitir que os usuários façam login facilmente no app.
• Cloud Firestore para salvar dados estruturados na nuvem e receber notificações instantâneas quando os dados são alterados.
• Cloud Storage para Firebase para salvar arquivos na nuvem.
• Firebase Hosting para hospedar e veicular seus recursos.
• Firebase Cloud Messaging para enviar notificações push e exibir notificações pop-up do navegador.
• Monitoramento de desempenho do Firebase para coletar dados de performance do usuário no seu app.

Alguns desses produtos precisam de configuração especial ou precisam ser ativados usando o Console do Firebase.

Ativar o Login do Google para o Firebase Authentication

Para permitir que os usuários façam login no app da Web com as Contas do Google deles, vamos usar o método de login do Google.

Ative o Login do Google:

1. No console do Firebase, localize a seção Build no painel à esquerda.
2. Clique em Autenticação, em Começar, se aplicável, e na guia Método de login (ou clique aqui para acessar diretamente).
3. Ativar o provedor de Login do Google
4. Defina o nome público do app como Friendly Chat e escolha um e-mail de suporte do projeto no menu suspenso.
5. Clique em Salvar.

Configurar o Cloud Firestore

O app da Web usa o Cloud Firestore para salvar e receber mensagens de chat.

Veja como configurar o Cloud Firestore no seu projeto do Firebase:

1. No painel à esquerda do console do Firebase, expanda Build e selecione Banco de dados do Firestore.
2. Clique em Criar banco de dados.
3. Deixe o ID do banco de dados definido como (default).
4. Selecione um local para o banco de dados e clique em Próxima.
   No caso de apps reais, escolha um local próximo aos usuários.
5. Clique em Iniciar no modo de teste. Leia o aviso sobre as regras de segurança.
   Mais adiante neste codelab, você vai adicionar regras de segurança para proteger seus dados. Não distribua ou exponha um aplicativo publicamente sem adicionar regras de segurança ao seu banco de dados.
6. Clique em Criar.

Configurar o Cloud Storage para Firebase

O app da Web usa o Cloud Storage para Firebase para armazenar, fazer upload e compartilhar fotos.

Veja como configurar o Cloud Storage para Firebase no seu projeto do Firebase:

1. No painel à esquerda do console do Firebase, expanda Build e selecione Storage.
2. Clique em Começar.
3. Selecione um local para seu bucket de armazenamento padrão.
   Os buckets em US-WEST1, US-CENTRAL1 e US-EAST1 podem aproveitar o nível"Sempre sem custo financeiro" do Google Cloud Storage. Os buckets em todos os outros locais seguem os preços e usos do Google Cloud Storage.
4. Clique em Iniciar no modo de teste. Leia o aviso sobre as regras de segurança.
   Mais adiante neste codelab, você vai adicionar regras de segurança para proteger seus dados. Não distribua ou exponha um aplicativo publicamente sem adicionar regras de segurança ao bucket do Storage.
5. Clique em Criar.

4. configurar o Firebase

No diretório appcheck-start, chame:

firebase use --add

Quando solicitado, selecione o ID do projeto e atribua um alias ao projeto do Firebase. Para este projeto, basta dar um alias de default. Em seguida, configure seu projeto local para trabalhar com o Firebase.

1. Acesse as Configurações do projeto no console do Firebase.
2. No card "Seus apps", selecione o apelido do app que precisa de um objeto de configuração.
3. Selecione Config no painel de snippets do SDK do Firebase.
4. Copie o snippet do objeto de configuração e adicione-o a appcheck-start/hosting/src/firebase-config.js. No restante do codelab, vamos presumir que a variável se chama config.

firebase-config.js

const config = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  databaseURL: "https://PROJECT_ID.firebaseio.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-MEASUREMENT_ID",
};

O código acima precisa conter o objeto de configuração do Firebase específico do app, não os valores de marcador de posição.

No mesmo diretório appcheck-start, chame:

firebase experiments:enable webframeworks

Isso ativa o suporte a frameworks da Web com que este projeto foi criado.

Agora está tudo pronto para executar o projeto e testar se o projeto padrão funciona.

5. Testar o app sem o App Check

Agora que você configurou o app e o SDK, tente usar o app como ele foi originalmente projetado. Primeiro, instale todas as dependências. No terminal, navegue até o diretório appcheck-start/hosting. Enquanto estiver nesse diretório, execute npm install. Isso busca todas as dependências para que seu projeto funcione. Para iniciar o app no estado atual, execute firebase serve. O app pede para você fazer login com uma Conta do Google. Faça isso e tente postar algumas mensagens de chat e fotos no chat.

Agora que você testou localmente, é hora de conferir na produção. Execute firebase deploy para implantar o web app na Web. Essa parte é uma etapa crucial para demonstrar como o App Check funciona no mundo real, já que exige que um domínio seja configurado para o provedor de attestação do reCAPTCHA Enterprise.

Esperamos que você esteja aproveitando a capacidade padrão oferecida pelo app. Postar mensagens de chat e tudo mais que só pode ser feito em um app como este. A desvantagem do estado atual é que qualquer pessoa com a configuração do app da etapa anterior pode acessar os recursos de back-end. Eles ainda precisam obedecer às regras de segurança implementadas pelos sistemas do Firestore e do Cloud Storage, mas, caso contrário, ainda podem consultar, armazenar e acessar os dados armazenados lá.

Nas próximas etapas, você vai:

• Inscreva-se para usar o App Check
• Validar a aplicação
• Começar a aplicar regras

6. Ativar o App Check e a aplicação

Vamos começar pegando uma chave do reCAPTCHA Enterprise para seu projeto e adicionando ao App Check. Comece acessando a seção reCAPTCHA Enterprise do console do Google Cloud. Selecione seu projeto e ative a API reCAPTCHA Enterprise. Ative a API e aguarde alguns minutos até que ela seja concluída. Em seguida, clique em Criar chave ao lado de Chaves empresariais. Em seguida, especifique um nome de exibição e selecione uma chave do tipo Site. Você precisa especificar os domínios em que seu app está hospedado. Como você planeja hospedar isso no Firebase Hosting, use o nome de hospedagem padrão, que geralmente é ${YOUR_PROJECT_ID}.web.app. O domínio de hospedagem está na seção "Hosting" do Console do Firebase. Depois de preencher essas informações, pressione Concluído e Criar chave.

Depois de concluído, um ID vai aparecer na parte de cima da página Detalhes principais.

Copie esse ID para a área de transferência. Essa é a chave usada para o App Check. Em seguida, acesse a parte App Check do console do Firebase e clique em Começar. Em seguida, clique em Registrar e em reCAPTCHA Enterprise. Cole o ID copiado na caixa de texto da chave de site do reCAPTCHA Enterprise. Deixe o restante das configurações como padrão. A página do App Check vai ficar assim:

Solicitações não verificadas e não aplicadas

Agora que você tem uma chave registrada no console do Firebase, volte a executar o site no navegador com firebase serve. Agora o app da Web está sendo executado localmente, e você pode começar a fazer solicitações ao back-end do Firebase novamente. Como as solicitações vão contra o back-end do Firebase, elas são monitoradas pelo App Check, mas não são aplicadas. Para conferir o status das solicitações recebidas, acesse a seção Cloud Firestore na guia "APIs" da página do App Check no console do Firebase. Como você ainda não configurou o cliente para usar o App Check, algo parecido com isto vai aparecer:

O back-end tem 100% de solicitações não verificadas. Essa tela é útil porque mostra que quase todas as solicitações de clientes vêm de clientes que não têm o App Check integrado.

Esse painel pode indicar algumas coisas. A primeira coisa que ele pode indicar é se todos os apps clientes estão executando a versão mais recente do cliente. Se forem, você pode aplicar o App Check com segurança sem se preocupar em desativar o acesso de um cliente legítimo do seu aplicativo. Outra informação que isso pode fornecer é quantas tentativas de acesso ao seu back-end foram feitas sem vir de dentro do app. Isso pode indicar que os usuários estão consultando seu back-end diretamente sem seu conhecimento. Como você pode ver que as solicitações não são verificadas, é hora de saber o que aconteceria com os usuários que podem ter uma solicitação não verificada para seu back-end antes de você verificar as solicitações deles.

Solicitações não verificadas e aplicadas

Pressione o botão Aplicar na tela anterior e, em seguida, pressione Aplicar novamente, se solicitado.

Isso vai começar a aplicar o App Check, bloqueando solicitações aos serviços de back-end que não forem verificadas pelo provedor de attest escolhido (neste caso, o reCAPTCHA Enterprise). Volte para o web app em execução, que deve estar em http://localhost:5000. Quando você atualiza a página e tenta extrair dados do banco de dados, nada acontece. Se você abrir o console do Chrome para ler os erros, vai ver algo semelhante a isto:

Uncaught Error in snapshot listener: FirebaseError: [code=permission-denied]: Missing or insufficient permissions.

O App Check está bloqueando solicitações que não transmitiram um token de atestado válido nas solicitações aos recursos do Firebase. Por enquanto, você pode desativar a aplicação do App Check. Na próxima seção, vamos examinar como adicionar o App Check do reCAPTCHA Enterprise ao exemplo do Friendly Chat.

7. Adicionar a chave do reCAPTCHA Enterprise ao site

Vamos adicionar a chave corporativa ao seu aplicativo. Primeiro, abra hosting/src/firebase-config.js e adicione sua chave do reCAPTCHA Enterprise ao seguinte snippet de código:

const reCAPTCHAEnterpriseKey = {
  // Replace with your recaptcha enterprise site key
  key: "Replace with your recaptcha enterprise site key"
};

Depois de concluir essa etapa, abra hosting/src/index.js e, na linha 51, adicione uma importação de firebase-config.js para buscar sua chave do reCAPTCHA e também importe a biblioteca do App Check para trabalhar com o provedor do reCAPTCHA Enterprise.

// add from here
 import {
   initializeAppCheck,
   ReCaptchaEnterpriseProvider,
 } from 'firebase/app-check';
// to here

// replace this line
import { getFirebaseConfig } from './firebase-config.js';
// with this line
import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';

Em seguida, na próxima linha, crie uma função para configurar o App Check. A função primeiro verifica se você está em um ambiente de desenvolvimento e, em caso afirmativo, imprime um token de depuração que pode ser usado para desenvolvimento local.

import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';
// add from here
 function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
 }
// to here

Agora é hora de inicializar o App Check para trabalhar com o provedor selecionado. Neste caso, é o reCAPTCHA Enterprise. Você também vai querer atualizar automaticamente o token do App Check em segundo plano, o que evita qualquer tipo de atraso na interação do usuário com seu serviço caso o token do App Check tenha ficado desatualizado.

function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
// add from here
   // Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
   // site key and pass it to initializeAppCheck().
   initializeAppCheck(app, {
     provider: new ReCaptchaEnterpriseProvider(getReCaptchaKey()),
     isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
   });
// to here
 }

Por fim, depois de verificar se o app foi inicializado, chame a função setupAppCheck que você acabou de criar. Na parte de baixo do arquivo hosting/src/index.js, adicione a chamada ao método adicionado recentemente.

const firebaseApp = initializeApp(getFirebaseConfig());
// add from here
setupAppCheck(firebaseApp);
// to here
getPerformance();
initFirebaseAuth();
loadMessages();

Teste localmente primeiro

Teste o aplicativo localmente primeiro. Se você ainda não estiver veiculando o aplicativo localmente, execute firebase serve. Você vai notar que o aplicativo ainda não carrega localmente. Isso ocorre porque você registrou apenas o domínio do Firebase com o provedor de declaração do reCAPTCHA, e não o domínio localhost. Nunca registre localhost como um domínio aprovado, porque isso permite que os usuários acessem seus back-ends restritos de um aplicativo executado localmente na máquina deles. Em vez disso, como você definiu self.FIREBASE_APPCHECK_DEBUG_TOKEN = true, verifique no console JavaScript uma linha semelhante a esta:

App Check debug token: 55183c20-de61-4438-85e6-8065789265be. You will need to add it to your app's App Check settings in the Firebase console for it to work.

Pegue o token de depuração fornecido (no exemplo, é 55183c20-de61-4438-85e6-8065789265be) e insira-o na configuração do App Check no menu de estouro do seu app.

Dê um nome exclusivo e fácil de lembrar ao token e clique em Salvar. Essa opção permite usar um token gerado pelo cliente com seu app, o que é uma alternativa mais segura do que gerar um token de depuração e incorporá-lo ao aplicativo. A incorporação de um token no app pode fazer com que ele seja distribuído acidentalmente aos usuários finais, que podem explorar o token ignorando suas verificações. Se você quiser distribuir um token de depuração, por exemplo, em um ambiente de CI, leia esta documentação para saber mais sobre como fazer isso.

Depois de registrar o token de depuração no console do Firebase, reative a aplicação do App Check e teste se o conteúdo do app é carregado localmente chamando firebase serve no terminal. Os dados inseridos anteriormente serão veiculados para a versão local do aplicativo da Web. A mensagem com o token de depuração ainda vai aparecer no console.

Teste em produção

Depois de confirmar que o App Check funciona localmente, implante o aplicativo Web na produção. No terminal, chame firebase deploy novamente e atualize a página. Isso vai empacotar seu aplicativo da Web para execução no Firebase Hosting. Depois que o aplicativo for hospedado no Firebase Hosting, tente acessar ${YOUR_PROJECT_ID}.web.app. Abra o console JavaScript. O token de depuração não vai mais aparecer lá, e os chats vão carregar no seu projeto. Além disso, depois de interagir com o aplicativo por alguns momentos, acesse a seção "App Check" do Console do Firebase e valide se as solicitações ao aplicativo foram alternadas para serem verificadas.

8. Parabéns!

Parabéns! Você adicionou o Firebase App Check a um app da Web.

Você configurou o Console do Firebase para processar um token do reCAPTCHA Enterprise em ambientes de produção e até mesmo tokens de depuração para desenvolvimento local. Isso garante que seus apps ainda possam acessar recursos do Firebase de clientes aprovados e evita atividades fraudulentas no aplicativo.

Qual é a próxima etapa?

Confira a documentação a seguir para adicionar o Firebase App Check a:

• Ativar a aplicação obrigatória no Cloud Functions
• Verificar tokens do App Check em back-ends personalizados

Documentos de referência

• Comece a usar o App Check com o reCAPTCHA Enterprise em apps da Web
• Usar o provedor de depuração em apps da Web