Codelab da Web do App Check

1. Introdução

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

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

Você pode usar o Firebase App Check para impedir que clientes não autorizados acessem seus recursos de back-end. Para isso, exija que as solicitações de entrada sejam anexadas a um atestado de que a solicitação vem do seu app original e bloqueie o tráfego que não tem um atestado adequado. O Firebase App Check usa 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, Realtime Database, Cloud Functions, Firebase Authentication com o 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 a verificação de app.

O que você aprenderá

• Como monitorar o 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 ambiente de desenvolvimento integrado/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 de sua escolha, como o Chrome
• O exemplo de código do codelab (confira a próxima etapa do codelab 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 o Git não estiver instalado, faça o download do 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. Esse 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 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 o projeto como "FriendlyChat". Lembre-se do ID do projeto do Firebase.
3. Desmarque a opção "Ativar o Google Analytics neste projeto"
4. Clique em "Criar projeto".

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

• Firebase Authentication: permite que os usuários façam login no app com facilidade.
• Cloud Firestore: usado 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 exibir 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 do seu app.

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

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), ou seja, 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 custo financeiro 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 ao fluxo de upgrade no console do Firebase para concluir o upgrade.

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 você ainda não instalou, faça isso agora usando o comando npm install -g firebase-tools. Depois clique em Next.
5. Em seguida, você vai encontrar 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. Você vai implantar no Firebase Hosting em uma etapa futura.

Ativar o Login do Google para o Firebase Authentication

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

É necessário 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 novas mensagens de chat.

Confira 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.

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

1. No painel à esquerda do Console do Firebase, expanda Build e selecione Armazenamento.
2. Clique em Começar.
3. Selecione um local para o bucket do Storage 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 o uso 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 usar o alias default. Em seguida, você vai precisar configurar 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 Configuração no painel do 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. No restante do codelab, presumimos que a variável seja chamada de 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 permite o suporte a frameworks da Web com que este projeto foi criado.

Agora você já pode 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 usá-lo como foi projetado originalmente. Primeiro, instale todas as dependências. No terminal, navegue até o diretório appcheck-start/hosting. Dentro desse diretório, execute npm install. Isso extrai todas as dependências para que o 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 e fotos no chat.

Agora que você testou localmente, é hora de conferir na produção. Execute firebase deploy para implantar o aplicativo da Web. Essa parte é uma etapa crucial para demonstrar como o App Check funciona na prática, porque exige que um domínio seja configurado para o provedor de atestado do reCAPTCHA Enterprise.

Esperamos que você esteja usando o recurso padrão fornecido pelo app. Postar mensagens de chat e tudo o mais que só pode 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 seus recursos de back-end. Elas ainda precisam obedecer às regras de segurança definidas pelos seus sistemas do Cloud Firestore e do Cloud Storage, mas podem consultar, armazenar e acessar os dados armazenados.

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 reCAPTCHA Enterprise para seu projeto e adicionando-a 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é a conclusão. Em seguida, clique em Criar chave ao lado de Chaves corporativas. Em seguida, especifique um nome de exibição e selecione uma chave do tipo Site. É necessário especificar os domínios em que o app está hospedado. Como você planeja hospedar o site no Firebase Hosting, use o nome de hospedagem padrão, que geralmente é ${YOUR_PROJECT_ID}.web.app. Encontre seu domínio de hospedagem na seção "Hospedar" do Console do Firebase. Depois de preencher essas informações, clique em Concluído e Criar chave.

Depois de concluído, 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 que você usa para a verificação de apps. Em seguida, acesse a seção App Check do console do Firebase e clique em Começar. Em seguida, clique em Registrar e em reCAPTCHA Enterprise e coloque o ID copiado na caixa de texto para a chave de site do reCAPTCHA Enterprise. Deixe o restante das configurações como padrão. A página de verificação do app vai ficar mais ou menos 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 executando firebase serve. Aqui, você tem o app da Web em execução localmente e pode começar a fazer solicitações ao back-end do Firebase novamente. Como as solicitações sã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 "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 clientes estão executando a versão mais recente do cliente. Se forem, você poderá aplicar o App Check com segurança sem se preocupar em desativar o acesso de um cliente genuíno do seu aplicativo. Isso também pode indicar quantas tentativas de acesso ao back-end foram feitas sem passar pelo app. Isso pode ser usuários que estão consultando o back-end diretamente sem seu conhecimento. Como você sabe que as solicitações não são verificadas, é hora de saber o que aconteceria com os usuários que têm uma solicitação não verificada no seu back-end antes de verificar as solicitações.

Solicitações não verificadas e aplicadas

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

Isso vai ativar o App Check, que vai bloquear as solicitações para os serviços de back-end que não forem verificados pelo provedor de atestado escolhido (neste caso, o reCAPTCHA Enterprise). Retorne ao app da Web em execução, que deve estar em http://localhost:5000. Quando você atualiza a página e tenta acessar os dados do banco de dados, nada acontece. Se você abrir o console do Chrome para ler os erros, verá algo semelhante a este:

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

Isso acontece quando o App Check bloqueia solicitações que não transmitiram um token de atestado válido para os 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 Chat amigável.

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 a chave reCAPTCHA Enterprise ao snippet de código abaixo:

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

Depois que isso for concluído, abra hosting/src/index.js e, na linha 51, adicione uma importação do firebase-config.js para buscar a chave do reCAPTCHA e também importar 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, você vai criar 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, que neste caso é o reCAPTCHA Enterprise. Você também vai querer atualizar automaticamente o token do App Check em segundo plano, o que vai evitar qualquer tipo de atraso na interação do usuário com seu serviço caso o token do App Check tenha expirado.

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, você precisa 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 o aplicativo localmente primeiro. Se você ainda não estiver veiculando o aplicativo localmente, execute firebase serve. O aplicativo ainda não carrega localmente. Isso ocorre porque você só registrou seu domínio do Firebase com o provedor de atestado do reCAPTCHA, e não com 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 executado localmente na máquina deles. Em vez disso, como você definiu self.FIREBASE_APPCHECK_DEBUG_TOKEN = true, verifique no console do JavaScript se há 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.

Você vai querer usar o token de depuração fornecido (no exemplo, ele é : 55183c20-de61-4438-85e6-8065789265be) e inseri-lo na configuração do App Check, no menu de contexto do 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 usá-lo para ignorar 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, você pode reativar a aplicação do App Check e testar se o conteúdo do app é carregado localmente chamando firebase serve no terminal. Os dados inseridos anteriormente vão ser veiculados para a versão local do aplicativo da Web. Você ainda vai ver a mensagem com o token de depuração impresso no console.

Testar na produção

Quando 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 execução no Firebase Hosting. Depois que o aplicativo for hospedado no Firebase Hosting, acesse-o em ${YOUR_PROJECT_ID}.web.app. Você pode abrir o console JavaScript. O token de depuração não será mais impresso nele, e os chats vão carregar no seu projeto. Além disso, depois de interagir com o aplicativo por alguns instantes, você pode acessar a seção "App Check" do console do Firebase e validar se todas as solicitações para seu aplicativo foram verificadas.

8. Parabéns!

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

Você configura o Console do Firebase para processar um token reCAPTCHA Enterprise para 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 que atividades fraudulentas ocorram no seu aplicativo.

Qual é a próxima etapa?

Consulte 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