Codelab da Web do App Check

1. Introdução

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

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

É possível usar o Firebase App Check para evitar que clientes não autorizados acessem seus recursos de back-end, exigindo que as solicitações recebidas sejam anexadas com um atestado de que elas vêm do seu app original e bloqueando o tráfego que não tem 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 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 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 em busca de 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 ambiente de desenvolvimento integrado/editor de texto de sua escolha
• O npm do gerenciador de pacotes, que normalmente vem com o Node.js
• a CLI do Firebase instalada e configurada para funcionar com sua conta;
• Um terminal/console
• em 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 do codelab na linha de comando:

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

Como alternativa, se você não tiver o Git instalado, faça o download do repositório como um arquivo ZIP (link em inglês).

Importar o app inicial

Usando seu ambiente de desenvolvimento integrado, abra ou importe o diretório 📁 appcheck-start do repositório clonado. Esse 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 completo do codelab.

3. Criar e configurar um projeto do Firebase

criar um projeto do Firebase

1. Faça login no Firebase.
2. No Console do Firebase, clique em "Adicionar projeto" e nomeie seu projeto como FriendlyChat. Lembre-se do ID do seu projeto do Firebase.
3. Desmarque a opção "Ativar o Google Analytics para este projeto"
4. Clique em "Criar projeto".

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

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

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

Adicionar um app da Web do Firebase ao projeto

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

4. Em seguida, você verá uma opção para instalar a CLI do Firebase. Se ainda não tiver instalado, faça isso 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 no console. A implantação no Firebase Hosting será feita em uma etapa futura.

Ativar o Login do Google para Firebase Authentication

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

Será necessário ativar o Login do Google:

1. No Console do Firebase, localize a seção Build no painel esquerdo.
2. Clique em Autenticação e em Começar, se aplicável, depois na guia Método de login ou clique aqui.
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 para o projeto no menu suspenso.
5. Clique em Salvar.

Ativar o Cloud Firestore

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

Será necessário ativar o Cloud Firestore:

1. Na seção Build do Console do Firebase, clique em Firestore Database.
2. Clique em Criar banco de dados no painel do Cloud Firestore.

3. Selecione a opção Iniciar no modo de teste e clique em Próxima depois de ler a exoneração de responsabilidade sobre as regras de segurança.

O modo de teste garante que você possa gravar livremente no banco de dados durante o desenvolvimento. Você já tem regras de segurança escritas para você no código inicial. Eles serão usados neste codelab.

4. Defina o local em que os dados do Cloud Firestore são armazenados. Mantenha essa configuração como padrão ou escolha uma região próxima a você. Clique em Ativar para provisionar o Firestore.

Ative o Cloud Storage

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

Será necessário ativar o Cloud Storage:

1. Na seção Build do Console do Firebase, clique em Armazenamento.
2. Se o botão Começar não estiver disponível, isso significa que o Cloud Storage já está ativado e você não precisa seguir as etapas abaixo.
3. Clique em Começar.
4. Selecione a opção Iniciar no modo de teste e clique em Próxima depois de ler a exoneração de responsabilidade sobre as regras de segurança.

Com as regras de segurança padrão, qualquer usuário autenticado pode gravar o que quiser no Cloud Storage. Mais adiante neste codelab, vamos implantar regras de segurança já escritas para nós.

5. O local do Cloud Storage é pré-selecionado com a mesma região que você escolheu para seu banco de dados do Cloud Firestore. Clique em Concluído para finalizar a configuração.

4. Configurar o Firebase

No diretório appcheck-start, chame:

firebase use --add

Quando solicitado, selecione o ID do projeto e atribua um alias a ele. Neste projeto, basta atribuir um alias default. 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 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 o nome da variável é config.

firebase-config.js (link em inglês)

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

No mesmo diretório appcheck-start, chame:

firebase experiments:enable webframeworks

Isso permite o suporte à estrutura da Web com o qual este projeto foi criado.

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, comece instalando todas as dependências. No seu 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 o projeto funcione. Para iniciar o app no estado atual, execute firebase serve. O app pede que você faça login com uma Conta do Google, depois tente postar algumas mensagens e algumas fotos no chat.

Agora que você o testou localmente, é hora de vê-lo em produção. Execute firebase deploy para implantar o aplicativo da Web na Web. Essa é uma etapa crucial para demonstrar como o App Check funciona no mundo real, já que exige a configuração de um domínio para o provedor de atestado reCAPTCHA Enterprise.

Esperamos que você esteja usando o recurso padrão oferecido pelo app. Postar mensagens de chat e tudo o que só deveria ser feito por 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 em vigor pelos sistemas do Firestore e do Cloud Storage, mas, caso contrário, ainda poderão consultar, armazenar e acessar os dados armazenados neles.

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

Para começar, escolha uma chave reCAPTCHA Enterprise para seu projeto e adicione-a ao App Check. Para começar, acesse a seção reCAPTCHA Enterprise do console do Google Cloud. Selecione o 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. Depois, nesta seção, especifique um nome de exibição e selecione uma chave do tipo Site. Você precisa especificar os domínios em que seu aplicativo está hospedado. Como você está planejando hospedar isso no Firebase Hosting, você usa o nome de hospedagem padrão, que geralmente é ${YOUR_PROJECT_ID}.web.app. Encontre o domínio de hospedagem na seção "Hosting" do Console do Firebase. Após preencher essas informações, pressione Concluído e Criar tecla.

Depois disso, um ID vai aparecer na parte de cima da página Detalhes da chave.

Copie esse ID para a área de transferência. Essa é a chave usada para o App Check. Em seguida, acesse a parte do App Check no Console do Firebase e clique em Começar. Depois, clique em Registrar, clique em reCAPTCHA Enterprise e insira o ID copiado na caixa de texto referente ao reCAPTCHA Enterprise Site Key. Não altere 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, execute firebase serve para voltar a executar seu site no navegador. Aqui, o app da Web é executado localmente e é possível começar a fazer solicitações ao back-end do Firebase novamente. À medida que as solicitações são enviadas ao 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 semelhante a:

O back-end está recebendo 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 aplicativos clientes estão executando a versão mais recente do seu cliente. Se forem, você pode aplicar o App Check com segurança sem se preocupar em desativar o acesso para um cliente genuíno do seu aplicativo. Outra informação que ele pode informar é quantas tentativas de acesso ao back-end entraram sem sair do app. Podem ser usuários que estão consultando seu back-end diretamente sem seu conhecimento. Como é possível notar que as solicitações não são verificadas, é hora de conferir o que aconteceria com os usuários que talvez tivessem uma solicitação não verificada no seu back-end antes de passar para a verificação das solicitações.

Solicitações aplicadas e não verificadas

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

Isso vai aplicar o App Check e bloquear as solicitações para os serviços de back-end que não foram verificadas pelo provedor de atestado escolhido (neste caso, o reCAPTCHA Enterprise). Retorne ao seu app da Web em execução, que deveria ser executado em http://localhost:5000. Quando você atualiza a página e tenta obter dados do banco de dados, nada acontece. Ao abrir o console do Chrome para ler os erros, você verá algo parecido com isto:

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

Este é o bloqueio de solicitações do App Check que não transmitiram um token de atestado válido nas solicitações para seus recursos do Firebase. Por enquanto, você pode desativar a aplicação do App Check e, na próxima seção, você vai examinar como adicionar o reCAPTCHA Enterprise App Check ao exemplo do Friendly Chat.

7. Adicionar a chave reCAPTCHA Enterprise ao site

Vamos adicionar a chave corporativa ao seu aplicativo. Primeiro, abra hosting/src/firebase-config.js e adicione sua chave 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 o arquivo hosting/src/index.js e, na linha 51, adicione uma importação de firebase-config.js para buscar sua chave reCAPTCHA e 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';

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, em caso afirmativo, imprimirá 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. Também é importante atualizar automaticamente o token do App Check em segundo plano, o que evitaria qualquer tipo de atraso por parte do usuário na interação com o serviço caso o token do App Check fique 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 conferir se o app foi inicializado, você vai precisar chamar a função setupAppCheck que 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 seu aplicativo localmente primeiro. Se você ainda não estiver disponibilizando o aplicativo localmente, execute firebase serve. Perceba que o aplicativo ainda não carrega localmente. Isso ocorre porque você registrou seu domínio do Firebase apenas no provedor de atestado reCAPTCHA, e não no domínio localhost. Nunca registre o host local como um domínio aprovado, porque isso permite que os usuários acessem seus back-ends restritos a partir de um aplicativo executado localmente na máquina. Em vez disso, como você definiu self.FIREBASE_APPCHECK_DEBUG_TOKEN = true, é importante verificar 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.

Use o token de depuração fornecido (no caso de exemplo : 55183c20-de61-4438-85e6-8065789265be) e conecte-o à configuração do App Check no menu flutuante do seu app.

Dê ao token um nome exclusivo que seja fácil de lembrar e clique em Salvar. Essa opção permite usar um token gerado pelo cliente com seu aplicativo, 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 aplicativo pode tê-lo distribuído acidentalmente para os usuários finais e esses usuários podem aproveitá-lo ignorando suas verificações. Se você quer distribuir um token de depuração, por exemplo, em um ambiente de CI, leia esta documentação para saber como distribuí-lo.

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. Você vai perceber que os dados inseridos anteriormente estão sendo veiculados na versão local do aplicativo da Web. Você ainda verá a mensagem com o token de depuração impresso no console.

Testar na produção

Quando você achar que o App Check funciona localmente, implante o aplicativo da Web em produção. No seu terminal, chame firebase deploy novamente e atualize a página. Isso empacotará o aplicativo da Web para ser executado no Firebase Hosting. Depois que seu aplicativo estiver hospedado no Firebase Hosting, tente acessá-lo em ${YOUR_PROJECT_ID}.web.app. Você pode abrir o console JavaScript e não verá mais o token de depuração impresso, e os chats serão carregados no seu projeto. Além disso, depois de interagir com o aplicativo por alguns momentos, você pode acessar a seção App Check no console do Firebase e confirmar que as solicitações para seu aplicativo mudaram para todas as que 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 reCAPTCHA Enterprise em ambientes de produção e até mesmo configurar tokens de depuração para desenvolvimento local. Isso garante que seus apps ainda possam acessar os recursos do Firebase de clientes aprovados e impede a ocorrência de atividades fraudulentas.

Qual é a próxima etapa?

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

• 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