Comece a usar o App Check com o reCAPTCHA Enterprise em apps da Web

Nesta página, mostramos como ativar o App Check em um app da Web usando o provedor reCAPTCHA Enterprise. Ao ativar o App Check, você ajuda a garantir que apenas seu app possa acessar os recursos de back-end do seu projeto. Consulte a Visão geral desse recurso.

O App Check usa chaves de site baseadas em pontuação do reCAPTCHA Enterprise, o que o torna invisível para os usuários. O provedor reCAPTCHA Enterprise não exigirá que os usuários resolvam desafios em nenhum momento.

Se o seu caso de uso exigir recursos do reCAPTCHA Enterprise não implementados pelo App Check ou se você quiser usar o App Check com seu próprio provedor personalizado, consulte Implementar um provedor App Check personalizado.

1. Configurar seu projeto do Firebase

1. Adicione o Firebase ao seu projeto em JavaScript, caso ainda não tenha feito isso.

2. Abra a seção reCAPTCHA Enterprise do Console do Cloud e realize estas ações:

   1. Se você precisar ativar a API reCAPTCHA Enterprise, faça isso.
   2. Crie uma chave do tipo Site. Será necessário especificar os domínios em que você hospeda o app da Web. Deixe a opção "Usar desafio da caixa de seleção" desmarcada.

3. Registre seus apps para usar App Check com o provedor do reCAPTCHA Enterprise na seção App Check do console Firebase. Será necessário fornecer a chave do site que você recebeu na etapa anterior.

   Geralmente, é necessário registrar todos os apps do projeto porque, depois de ativar a aplicação de um produto do Firebase, somente apps registrados poderão acessar os recursos de back-end do produto.

4. Opcional: nas configurações de registro do aplicativo, defina um time to live (TTL) personalizado para os tokens do App Check emitidos pelo provedor. É possível definir o TTL como qualquer valor entre 30 minutos e 7 dias. Ao mudar esse valor, esteja ciente das seguintes compensações:

   • Segurança: os TTLs mais curtos oferecem maior segurança, porque reduzem a janela em que um token vazado ou interceptado pode ser usado por um invasor.
   • Desempenho: TTLs mais curtos significam que seu app realizará atestados com mais frequência. Como o processo de atestado do app adiciona latência às solicitações de rede sempre que é executado, um TTL curto pode afetar o desempenho do app.
   • Cota e custo: TTLs mais curtos e novos atestados frequentes esgotam sua cota mais rapidamente e, para serviços pagos, podem custar mais. Consulte Cotas e limites.

   O TTL padrão de uma hora é razoável para a maioria dos apps. A biblioteca App Check atualiza os tokens em aproximadamente metade da duração do TTL.

Definir configurações avançadas (opcional)

Quando um usuário acessa seu web app, o reCAPTCHA Enterprise avalia o nível de risco da interação do usuário e retorna uma pontuação entre 0,0 e 1,0, em incrementos de 0,1. A pontuação 1,0 indica que a interação apresenta risco baixo e muito provavelmente é legítima, enquanto 0,0 indica que a interação apresenta alto risco e pode ser fraudulenta. Com o App Check, é possível configurar um limite de risco do app para ajustar sua tolerância a esse risco.

Na maioria dos casos de uso, o valor de limite padrão de 0,5 é recomendado. Se o caso de uso exigir ajuste, ele poderá ser configurado na seção App Check do console Firebase para cada um dos seus web apps.

Detalhes

O App Check usa o limite de risco do app configurado como a pontuação mínima do reCAPTCHA Enterprise necessária para que uma interação do usuário seja considerada legítima. Todas as pontuações do reCAPTCHA Enterprise estritamente menores que o limite configurado serão rejeitadas. Ao ajustar o limite de risco do app, esteja ciente do seguinte:

• Dos 11 níveis de pontuação possíveis do reCAPTCHA Enterprise, apenas os quatro a seguir estão disponíveis antes de adicionar uma conta do Cloud Billing ao seu projeto: 0,1, 0,3, 0,7 e 0,9. Durante esse período, o App Check vai permitir apenas valores de limite de risco do app de 0,1, 0,3, 0,5, 0,7 e 0,9. Um valor de limite de risco do app de 0,5 ainda é recomendado para a maioria dos casos de uso.

  • Para ativar todos os 11 níveis de pontuação do reCAPTCHA Enterprise, adicione uma conta de faturamento do Google Cloud ao seu projeto. Uma maneira de fazer isso é fazer upgrade para o plano de preços Blaze. Depois disso, o App Check permite configurar qualquer valor limite de risco do app entre 0,0 e 1,0, em incrementos de 0,1.

    Observação: depois que uma conta do Cloud Billing é adicionada ao seu projeto, uma análise de segurança automática é acionada para ele. Para mais informações, consulte a documentação do reCAPTCHA Enterprise.

• Para monitorar a distribuição de pontuações altas e baixas do reCAPTCHA Enterprise no seu app da Web, acesse a página do reCAPTCHA Enterprise no console Google Cloud e selecione a chave de site usada pelo app.

• Se você tiver baixa tolerância ao risco de apps, mova o controle deslizante para a esquerda para aumentar o limite de risco.

  • Não recomendamos um valor de 1,0, já que essa configuração também pode negar o acesso a usuários legítimos que não atendem a esse alto limite de confiança.
  Aviso: antes de aumentar o limite de risco do app, considere desativar temporariamente a proteção do App Check para todos os serviços em vigor e evitar interrupções para seus usuários legítimos. Você precisa monitorar as métricas de solicitação do App Check para verificar se o tráfego não foi interrompido antes de retomar a aplicação.

• Se você tiver alta tolerância ao risco de apps, mova o controle deslizante para a direita para diminuir o limite de risco do app.

  • Não é recomendável usar o valor 0,0, porque essa configuração desativa a proteção contra abusos.

Consulte a documentação do reCAPTCHA Enterprise para mais detalhes.

2. Adicionar a biblioteca App Check ao app

Adicione o Firebase ao seu app da Web, caso ainda não tenha feito isso. Importe a biblioteca App Check.

3. Inicializar o App Check

Adicione o código de inicialização a seguir ao aplicativo antes de acessar os serviços do Firebase. Será necessário enviar a chave do site do reCAPTCHA Enterprise, que você criou no Console do Cloud, para activate().

Web

Saiba mais sobre a API modular da Web que oferece suporte a tree shaking e o upgrade da API com namespace.

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";

const app = initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to initializeAppCheck().
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(/* reCAPTCHA Enterprise site key */),
  isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
});

Observação: o SDK não vai atualizar automaticamente os tokens App Check por padrão. Essa funcionalidade precisa ser ativada explicitamente definindo isTokenAutoRefreshEnabled como true nas opções transmitidas para initializeAppCheck() ou chamando setTokenAutoRefreshEnabled(appCheck, true). Para mais informações, consulte os documentos de referência do App Check.

Web

firebase.initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to activate().
const appCheck = firebase.appCheck();
appCheck.activate(
  new firebase.appCheck.ReCaptchaEnterpriseProvider(
    /* reCAPTCHA Enterprise site key */
  ),
  true // Set to true to allow auto-refresh.
);

Observação: o SDK não vai atualizar automaticamente os tokens App Check por padrão. Essa funcionalidade precisa ser ativada de maneira explícita ao fornecer true como um segundo argumento para activate() ou chamar firebase.appCheck().setTokenAutoRefreshEnabled(true). Para mais informações, consulte os documentos de referência do App Check.

Próximas etapas

Implante a biblioteca App Check depois que ela for instalada no seu app.

O app cliente atualizado vai começar a enviar tokens do App Check em todas as solicitações feitas ao Firebase, mas os produtos dessa plataforma não exigirão que os tokens sejam válidos até que você ative a aplicação obrigatória na seção App Check do Console do Firebase.

Monitorar métricas e ativar a aplicação obrigatória

Antes de ativar a aplicação obrigatória, verifique se isso não vai afetar seus usuários legítimos. Por outro lado, se você perceber um uso suspeito dos recursos do seu app, convém ativar a aplicação obrigatória antes do previsto.

Para tomar essa decisão, analise as métricas do App Check nos serviços usados:

• Monitore as métricas de solicitação App Check para Firebase AI Logic, Data Connect, Realtime Database, Cloud Firestore, Cloud Storage, Authentication, Google Identity para iOS, API Maps JavaScript e API Places (novo).
• Monitore as métricas de solicitação do App Check para Cloud Functions.

Ativar a aplicação App Check

Assim que você entender como o App Check vai afetar seus usuários e estiver tudo pronto para prosseguir, ative a aplicação obrigatória do App Check:

• Ativar a aplicação de App Check para Firebase AI Logic, Data Connect, Realtime Database, Cloud Firestore, Cloud Storage, Authentication, Google Identity para iOS, API Maps JavaScript e API Places (novo).
• Ative a aplicação de App Check para Cloud Functions.

Usar App Check em ambientes de depuração

Se, depois de registrar seu aplicativo no App Check, você quiser executá-lo em um ambiente em que o App Check normalmente não seria classificado como válido, como localmente, durante o desenvolvimento ou em uma integração contínua (CI), crie um build de depuração do seu app que use o provedor de depuração do App Check em vez de um provedor de atestado real.

Consulte Usar App Check com o provedor de depuração em apps da Web.

Observação sobre o custo

O App Check cria uma avaliação em seu nome para validar o token de resposta do usuário sempre que um navegador que executa seu app da Web atualiza o token App Check. Seu projeto será cobrado por cada avaliação criada acima da cota sem custo. Consulte os preços do reCAPTCHA para mais detalhes.

Por padrão, seu app da Web atualizará esse token duas vezes a cada uma hora. Para controlar a frequência com que o app atualiza os tokens do App Check (e, com isso, a frequência com que novas avaliações são criadas), configure o TTL deles.