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 seus recursos de back-end. Para isso, exija que as solicitações recebidas venham acompanhadas de um atestado de que a solicitação vem do seu app original e bloqueie o tráfego que não tiver um atestado adequado. O Firebase App Check depende de provedores de atestado específicos da plataforma para verificar a autenticidade do cliente. No caso de apps da Web, o App Check é compatível com o reCAPTCHA v3 e o reCAPTCHA Enterprise como provedores de atestado.

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

O que você vai criar

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

O que você aprenderá

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

O que é necessário

• O ambiente de desenvolvimento integrado/editor de texto de sua escolha
• O gerenciador de pacotes npm, que normalmente 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 (confira a próxima etapa para saber como acessar o código).

2. Acessar o exemplo de código

Clone o repositório do GitHub do codelab na linha de comando:

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

Se preferir, caso não tenha o Git instalado, baixe o repositório como um arquivo ZIP.

Importar o app inicial

Usando o 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 da Web de chat 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 novo projeto e insira um nome (por exemplo, FriendlyChat).
   
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 essa opção.
7. Clique em Criar projeto, aguarde o provisionamento do projeto 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 do Cloud Billing de teste sem custo financeiro.
• 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 ao fluxo de upgrade no console do Firebase para concluir o processo.

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 adiante no codelab. Por enquanto, pressione Próxima.

4. Em seguida, você verá uma opção para instalar a CLI do Firebase. Se você ainda não tiver instalado, faça isso 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 Ir 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 mudarem.
• Cloud Storage para Firebase para salvar arquivos na nuvem.
• Firebase Hosting para hospedar e disponibilizar seus recursos.
• Firebase Cloud Messaging para enviar notificações push e mostrar 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 necessitam 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, vamos usar o método de login do Google.

Você precisa ativar 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 as informações 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, abra Build e selecione Storage.
2. Clique em Começar.
3. Selecione um local para o bucket padrão do Storage.
   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 a exoneração de responsabilidade 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 dê um alias ao projeto do Firebase. Para este projeto, basta dar um alias de padrão. Em seguida, configure seu projeto local para funcionar 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 Configuração no painel de snippet do SDK do Firebase.
4. Copie o snippet do objeto de configuração e adicione-o a appcheck-start/hosting/src/firebase-config.js. O restante do codelab pressupõe 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",
};

No mesmo diretório appcheck-start, chame:

firebase experiments:enable webframeworks

Isso ativa o suporte ao framework 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 o app e o SDK estão configurados, 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. Dentro desse diretório, execute npm install. Isso busca todas as dependências para que o projeto funcione. Para iniciar o app no estado atual, execute firebase serve. O app vai pedir para você fazer login com uma Conta do Google. Depois disso, tente postar algumas mensagens e fotos no chat.

Agora que você testou localmente, é hora de ver em produção. Execute firebase deploy para implantar o aplicativo da Web 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 atestação do reCAPTCHA Enterprise.

Esperamos que você esteja aproveitando o recurso padrão que o app oferece. Postar mensagens de chat e tudo o que só deve ser feito em um app como esse. 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 em vigor nos sistemas do Firestore e do Cloud Storage, mas 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 obrigatória

Vamos começar pegando uma chave do reCAPTCHA Enterprise para seu projeto e adicionando-a ao App Check. Para começar, acesse 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 para que ela seja concluída. Em seguida, clique em Criar chave ao lado de Chaves Enterprise. Em seguida, nessa seção, 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 o app no Firebase Hosting, use o nome do host padrão, que geralmente é ${YOUR_PROJECT_ID}.web.app. O domínio de hospedagem está na seção "Hospedagem" do console do Firebase. Depois de preencher essas informações, pressione Concluído e Criar chave.

Depois de concluído, você verá um ID na parte superior da página Detalhes da chave.

Copie esse ID para a área de transferência. Essa é a chave que você usa para o App Check. Em seguida, acesse a seção App Check do console do Firebase e clique em Começar. Em seguida, clique em Registrar, em reCAPTCHA Enterprise e coloque o ID copiado na caixa de texto da chave do site do reCAPTCHA Enterprise. Não mude as outras configurações. 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 usando 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 para o back-end do Firebase, elas são monitoradas pelo App Check, mas não são aplicadas. Se você quiser ver 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, vai aparecer algo parecido com isto:

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 cliente estão executando a versão mais recente do cliente. Se estiverem, você poderá aplicar o App Check com segurança sem se preocupar em desativar o acesso de um cliente genuíno do seu aplicativo. Outra coisa que isso pode indicar é quantas tentativas de acesso ao back-end foram feitas sem vir do seu app. Podem ser usuários que 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 ver o que aconteceria com os usuários que podem ter uma solicitação não verificada para seu back-end antes de passar para a verificação das 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 iniciar a aplicação do App Check, que agora vai bloquear solicitações para seus serviços de back-end que não forem verificadas pelo provedor de atestação escolhido (neste caso, o reCAPTCHA Enterprise). Volte ao app da Web em execução, que deve estar em http://localhost:5000. Quando você atualiza a página e tenta receber dados do banco de dados, nada acontece. Se você abrir o console do Chrome para ler os erros, vai encontrar algo semelhante a isto:

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

Isso significa que 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, você vai aprender a 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 empresarial 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 disso, abra hosting/src/index.js e, na linha 51, adicione uma importação de firebase-config.js para buscar sua chave reCAPTCHA e também importe a biblioteca do App Check para trabalhar com o provedor 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, você vai criar uma função para configurar o App Check. A função vai verificar primeiro se você está em um ambiente de desenvolvimento e, se estiver, vai mostrar 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 funcionar com o provedor selecionado, que, neste caso, é o reCAPTCHA Enterprise. Também é recomendável atualizar automaticamente o token do App Check em segundo plano, o que evitaria qualquer tipo de atraso na interação do usuário com o 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 que você acabou de incluir.

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 disponibilizando 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 atestação do reCAPTCHA, e não o domínio localhost. Nunca registre o localhost como um domínio aprovado, porque isso permite que os usuários acessem seus back-ends restritos de um aplicativo em execução localmente na máquina deles. Em vez disso, como você definiu self.FIREBASE_APPCHECK_DEBUG_TOKEN = true, verifique no Console JavaScript se há uma linha parecida com 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 flutuante do seu app.

Dê ao token um nome exclusivo que você vai lembrar 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. Se você incorporar um token no app, ele poderá ser distribuído acidentalmente para os usuários finais, que poderão usá-lo para burlar 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 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 vão aparecer na versão local do aplicativo da Web. A mensagem com o token de depuração ainda vai aparecer no console.

Teste na produção

Quando você tiver certeza de que o App Check funciona localmente, implante o aplicativo da Web na produção. No terminal, chame firebase deploy novamente e atualize a página. Isso vai empacotar seu aplicativo da Web para ser executado no Firebase Hosting. Depois que o aplicativo estiver hospedado no Firebase Hosting, tente acessá-lo em ${YOUR_PROJECT_ID}.web.app. Abra o console JavaScript. O token de depuração não vai mais aparecer, e as conversas vão começar a carregar no projeto. Além disso, depois de interagir com o aplicativo por alguns instantes, acesse a seção "App Check" do console do Firebase e confirme se todas as solicitações para o aplicativo estão sendo 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 para ambientes de produção e até mesmo configurou tokens de depuração para desenvolvimento local. Isso garante que os apps ainda possam acessar os 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 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