Ativar o reCAPTCHA Enterprise

Neste documento, mostramos como usar a integração do Identity Platform com o reCAPTCHA para melhorar a segurança dos usuários. Esse recurso torna seu app mais resiliente contra spam, abuso e outras atividades fraudulentas.

A integração do Identity Platform com o reCAPTCHA cria uma teste reCAPTCHA em seu nome para validar solicitações de usuários. Para informações sobre preços, consulte Preços do reCAPTCHA.

Importante :esse recurso só é compatível com logins e inscrições por e-mail e senha, redefinições de senha e logins por link de e-mail. Se um usuário legítimo for bloqueado, consulte as etapas de resolução em Solução de problemas.

Visão geral

Quando você configura a integração do Identity Platform com o reCAPTCHA, o Identity Platform provisiona chaves de site reCAPTCHA baseadas em pontuação no projeto em seu nome. Quando um usuário acessa seu app ou site usando uma das operações a seguir, o SDK do cliente carrega o reCAPTCHA:

Operação	Método
Login com e-mail e senha	signInWithPassword
Inscrição com e-mail e senha	signUpPassword
Fazer login com o link do e-mail	getOobCode
Senha redefinida	getOobCode

Em seguida, o reCAPTCHA fornece ao Identity Platform indicadores de risco que avaliam o risco da solicitação com base na configuração e na tolerância a riscos.

Para mais informações, consulte a Visão geral do reCAPTCHA Enterprise.

Importante: Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• reCAPTCHA Enterprise
• Identity Platform

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Antes de começar

Configure o login por e-mail para os usuários.

Crie uma conta de serviço

Antes de ativar o reCAPTCHA, crie uma conta de serviço para cada projeto que vai usá-lo e conceda acesso a cada uma delas. Isso permite que o Identity Platform gerencie chaves reCAPTCHA em seu nome.

Para criar uma conta de serviço, faça o seguinte:

1. Use o Google Cloud CLI para criar uma conta de serviço:

   gcloud beta services identity create \
       --service=identitytoolkit.googleapis.com \
       --project=PROJECT_ID
   

   Substitua PROJECT_ID pelo ID do projeto.

2. Conceda à conta de serviço acesso ao reCAPTCHA:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/identitytoolkit.serviceAgent
   

   Substitua:

   • PROJECT_ID: o ID do projeto
   • PROJECT_NUMBER: o número da conta do projeto

Ativar reCAPTCHA

O reCAPTCHA tem dois modos que ajudam a proteger os usuários:

• Auditoria: quando ativado, o Identity Platform cria uma ou mais chaves reCAPTCHA no projeto que são usadas para avaliar o tráfego para as APIs do Identity Platform sem bloquear nenhuma solicitação. Use as métricas emitidas durante o modo de auditoria para determinar se é preciso ativar a aplicação do reCAPTCHA.
• Aplicação: quando ativada, o Identity Platform cria uma ou mais chaves reCAPTCHA no projeto que são usadas para avaliar o tráfego para as APIs do Identity Platform. As solicitações de API que não incluem um token reCAPTCHA são rejeitadas. Só ative a aplicação depois de migrar todos os clientes para um SDK compatível com o reCAPTCHA.

Importante: não edite nem exclua chaves reCAPTCHA chamadas "Chave para integração do Identity Platform com o reCAPTCHA", a menos que o reCAPTCHA esteja desativado. Isso impede que o Identity Platform aplique a proteção reCAPTCHA. Além disso, os SDKs do Identity Platform não podem gerar tokens com base em chaves reCAPTCHA que você gera por conta própria.

Para ativar o reCAPTCHA, faça o seguinte:

1. Ative a API reCAPTCHA no seu projeto, caso ainda não tenha feito isso.

2. Ativar a integração do Identity Platform com o reCAPTCHA para um projeto usando o SDK Admin. O suporte ao reCAPTCHA está disponível nas versões 11.7.0 e mais recentes do SDK Admin para Node.js.

   Exemplo:

   // Get project config
   const getProjectConfig = () => {
     getAuth().projectConfigManager().getProjectConfig()
     .then((response) => {
       console.log('Project reCAPTCHA config: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error getting project config:', error);
     });
   }
   
   // Update project config with reCAPTCHA config
   const updateConfigRequest = {
     recaptchaConfig: {
       emailPasswordEnforcementState:  'AUDIT',
       managedRules: [{
         endScore: 0.3,
         action: 'BLOCK'
       }]
     }
   };
   const updateProjectConfigWithRecaptcha = () => {
     getAuth().projectConfigManager().updateProjectConfig(updateConfigRequest).then((response) => {
       console.log('Updated reCAPTCHA config for project: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error updating project config:', error);
     });
   }
   

3. Ativar a integração do Identity Platform com o reCAPTCHA para um locatário usando o SDK Admin. Exemplo:

   // Update tenant with reCAPTCHA config
   const updateTenantRequest = {
     recaptchaConfig: {
       emailPasswordEnforcementState:  'AUDIT',
       managedRules: [{
         endScore: 0.3,
         action: 'BLOCK'
       }]
     }
   };
   const updateTenantWithRecaptchaConfig = () => {
     getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest)
     .then((response) => {
       console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error updating the tenant:', error);
     });
   }
   

   Substitua:

   • TENANT_ID: o ID do locatário
   Observação: o Identity Platform não é compatível com a multilocação com reCAPTCHA em plataformas para dispositivos móveis.

4. Se você estiver usando o Identity Platform nas plataformas Apple ou Android, registre seu app no Console do Firebase:

   • Para plataformas da Apple, registre cada ID do pacote que usa o Identity Platform.
   • No Android, registre cada nome de pacote Android que usa o Identity Platform.

5. Se você estiver usando o Identity Platform na Web, precisará adicionar um domínio autorizado para cada domínio que usa o reCAPTCHA. Para adicionar domínios autorizados, faça o seguinte:

   1. No console do Google Cloud, acesse a página do Identity Platform.

      Acessar o Identity Platform

   2. Acesse Configurações > Segurança.

   3. Clique em Adicionar domínio.

   4. Digite o nome do domínio e clique em Adicionar para salvar.

   O provisionamento da chave do site pode levar vários minutos para ser concluído. Para garantir que os fluxos estão sendo protegidos, verifique as metrics.

Configurar o SDK do cliente

Configure o SDK do cliente de acordo com a plataforma do seu aplicativo.

Web

1. Atualize para a versão mais recente do SDK da Web. A compatibilidade com o reCAPTCHA está disponível nas versões 9.20.0 e mais recentes do SDK para JavaScript. Depois de integrar o SDK da Web ao app, ele busca automaticamente a configuração reCAPTCHA e protege os provedores configurados.

2. Para reduzir o número de chamadas de rede feitas pelo SDK e melhorar a coleta de indicadores reCAPTCHA, recomendamos configurá-la explicitamente da seguinte maneira:

   import { initializeRecaptchaConfig } from '@firebase/auth';
   
   // Initialize Firebase Auth
   const auth = getAuth();
   initializeRecaptchaConfig(auth)
     .then(() => {
       console.log("Recaptcha Enterprise Config Initialization successful.")
     })
     .catch((error) => {
       console.error("Recaptcha Enterprise Config Initialization failed with " + error)
     });
   

Android

1. Atualize para a versão 31.5.0 ou mais recente do SDK do Android. A compatibilidade com o reCAPTCHA requer o nível 19 da API (KitKat) ou mais recente e o Android 4.4 ou mais recente. Depois de integrar o SDK do Android ao app, ele busca automaticamente a configuração reCAPTCHA e protege os provedores configurados.

2. Adicione a seguinte regra de build à seção de dependências do arquivo build.gradle no nível do app:

   implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
   

   Use o SDK do reCAPTCHA na versão 18.4.0 ou mais recente.

3. Para reduzir o número de chamadas de rede feitas pelo SDK e tornar a coleta de indicadores reCAPTCHA mais eficaz, recomendamos configurá-la explicitamente da seguinte maneira:

   • Kotlin:

   // Initialize Firebase Auth
   auth = Firebase.auth
   
   auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
       if (task.isSuccessful) {
           Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
       } else {
           Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
       }
   }
   

   • Java:

   // Initialize Firebase Auth
   auth = FirebaseAuth.getInstance();
   auth.initializeRecaptchaConfig().addOnCompleteListener(
     this, new OnCompleteListener<void>() {
     @Override
     public void onComplete(@NonNull Task<void> task) {
       if (task.isSuccessful()) {
         Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
       } else {
         Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
       }
     }
   });
   

iOS

1. Atualize para o SDK do iOS versão 10.14.0 ou mais recente. Depois de integrar o SDK para iOS ao app, ele busca automaticamente a configuração reCAPTCHA e protege os provedores configurados.

2. Para integrar o SDK do reCAPTCHA para iOS ao seu app, consulte Preparar seu ambiente.

3. Verifique se -ObjC está listado nas sinalizações do vinculador. Navegue até Target > Build Settings > All > Linking e verifique se Other Linker Flags mostra -ObjC.

4. Para reduzir o número de chamadas de rede feitas pelo SDK e tornar a coleta de indicadores reCAPTCHA mais eficaz, recomendamos que você a configure explicitamente da seguinte maneira:

   • Swift:

   // Initialize Firebase Auth
   try await Auth.auth().initializeRecaptchaConfig()
   

   • Objective-C:

   // Initialize Firebase Auth
   [[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
     // Firebase Auth initialization finished
   }];
   

Métricas do reCAPTCHA

Depois de ativar o reCAPTCHA, monitore as métricas relacionadas que seu projeto emite para garantir que os fluxos de autenticação estejam protegidos. Se o provisionamento de chave do site reCAPTCHA falhar ou se as contas de serviço necessárias não tiverem sido criadas, a autenticação reCAPTCHA falhará ao abrir.

Verifique se a autenticação reCAPTCHA está funcionando examinando as seguintes métricas que seu projeto emite para o Cloud Monitoring:

identitytoolkit.googleapis.com/recaptcha/verdict_count

Rastreia os diferentes vereditos retornados pelo reCAPTCHA. Se um token estiver presente, um veredito será gerado. É possível filtrar os seguintes vereditos:

• PASSED: indica que uma determinada solicitação é permitida quando a aplicação está ativada.
• FAILED_AUDIT: indica que uma determinada solicitação é negada quando o modo de auditoria reCAPTCHA está ativado.
• FAILED_ENFORCE: indica que uma determinada solicitação é negada quando o modo de aplicação reCAPTCHA está ativado.
• CLIENT_TYPE_MISSING: indica que uma determinada solicitação tem um tipo de cliente ausente quando a aplicação do reCAPTCHA está ativada. Isso geralmente ocorre quando uma solicitação é enviada usando uma versão desatualizada do SDK do cliente que não tem suporte ao reCAPTCHA.
• KEYS_MISSING: indica que não é possível verificar uma determinada solicitação devido à incapacidade de recuperar ou gerar chaves reCAPTCHA válidas quando a aplicação do reCAPTCHA está ativada.

Para modificar seus intervalos de pontuação e mudar a proporção de vereditos aprovados para reprovados, consulte Ativar o reCAPTCHA Enterprise.

identitytoolkit.googleapis.com/recaptcha/token_count

rastreia o número e o status dos tokens reCAPTCHA recebidos pelo back-end do Identity Platform. É possível filtrar os seguintes status:

• VALID: indica que o token reCAPTCHA transmitido é válido.
• EXPIRED: indica que o token reCAPTCHA transmitido expirou. Um token expirado pode indicar problemas de rede ou abuso do cliente.
• DUPLICATE: indica que o token reCAPTCHA transmitido é uma cópia. Um token duplicado pode indicar problemas de rede do cliente ou abuso.
• INVALID: indica que o token reCAPTCHA transmitido é inválido. Um token inválido pode indicar abuso.
• MISSING: indica que o token reCAPTCHA não existe na solicitação em questão. Os tokens ausentes podem indicar que o app cliente está desatualizado.
• UNCHECKED: indica que o token reCAPTCHA não foi verificado devido aos vereditos CLIENT_TYPE_MISSING ou KEYS_MISSING.

Se o app tiver sido lançado para os usuários, você vai ver o tráfego com tokens válidos. O número de tokens válidos provavelmente é proporcional ao número de usuários que estão usando o app atualizado.

identitytoolkit.googleapis.com/recaptcha/risk_scores

Rastreia a distribuição de pontuação do reCAPTCHA. Isso ajuda a definir os intervalos de pontuação ideais para sua configuração.

Use essas métricas para determinar se você pode ativar a aplicação. Considere o seguinte antes de ativar a aplicação:

• Se a maioria das solicitações recentes tiver tokens válidos e a proporção de vereditos PASSED para FAILED_AUDIT ou FAILED_ENFORCE for aceitável para seu caso de negócios, considere ativar a aplicação.
• Se a maioria das solicitações recentes for provavelmente de clientes desatualizados, considere esperar que mais usuários atualizem o app antes de ativar a aplicação. Exigir a integração do Identity Platform com o reCAPTCHA quebra as versões anteriores do app que não estão integradas ao reCAPTCHA.

Para visualizar essas métricas, faça o seguinte:

1. No Console do Google Cloud, acesse a página do Metrics Explorer.

   Acesse o Metrics explorer

2. Em Select a metric, insira Identity Toolkit Tenant. Se você estiver usando a multilocação, será possível visualizar as métricas de cada locatário, bem como do projeto pai, deixando tenant_name vazio.

Ativar aplicação

Depois de verificar se o app está recebendo tráfego aceitável de usuários, ative a aplicação do reCAPTCHA para proteger os usuários. Não interrompa os usuários atuais, incluindo aqueles que usam uma versão mais antiga do app.

Para ativar a aplicação do reCAPTCHA em um projeto ou locatário, use o SDK Admin para executar o seguinte:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

Desativar o reCAPTCHA

Para desativar o reCAPTCHA, use o SDK Admin para executar o seguinte:

const disableRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'OFF',
  }
};

Como substituir vereditos do reCAPTCHA com o Cloud Functions

Além de configurar limites de pontuação, é possível substituir um veredito reCAPTCHA para um determinado token usando uma função de bloqueio personalizada do Cloud Functions. Isso é útil nos casos em que uma pontuação reCAPTCHA para um determinado login de usuário pode ser baixa, mas o usuário é confiável ou foi verificado por outros meios e, portanto, tem permissão para concluir o login.

Para saber mais sobre como configurar funções de bloqueio com o reCAPTCHA, consulte Estender o Firebase Authentication com o bloqueio do Cloud Functions.

Solução de problemas

Os usuários não conseguem fazer login, inscrever-se ou redefinir a senha

Os usuários podem estar usando uma versão desatualizada do app. Se você não forneceu uma versão atualizada do app que usa o SDK do cliente, desative o modo de aplicação imediatamente. Caso contrário, peça para os usuários atualizarem o app.

Como alternativa, os usuários podem ser bloqueados com base na sua configuração atual. Tente o seguinte:

• Ajuste as pontuações de chave reCAPTCHA para considerar uma configuração mais permissiva.
• Peça para o usuário testar outro dispositivo, navegador ou rede.
• Reverta para o modo de auditoria e monitore as métricas antes de reativar o modo de aplicação.