Ativar o reCAPTCHA Enterprise

Neste documento, mostramos como usar a integração do Identity Platform com o reCAPTCHA Enterprise 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 Enterprise cria uma avaliação do reCAPTCHA Enterprise em seu nome para validar as solicitações dos usuários. Para mais informações sobre preços, consulte Preços do reCAPTCHA Enterprise.

Visão geral

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

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.

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 Enterprise, é necessário criar uma conta de serviço para cada projeto que vai usar o reCAPTCHA e conceder acesso a cada conta de serviço ao reCAPTCHA Enterprise. 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 Enterprise:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
    --role=roles/identitytoolkit.serviceAgent

    Substitua:

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

Ativar o reCAPTCHA Enterprise

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

  • Auditoria: quando ativado, o Identity Platform cria uma ou mais chaves reCAPTCHA Enterprise no projeto que são usadas para avaliar o tráfego para as APIs 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 Enterprise no projeto para avaliar o tráfego nas 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 com suporte ao reCAPTCHA Enterprise.

Para ativar o reCAPTCHA Enterprise, faça o seguinte:

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

  2. Ative a integração do Identity Platform com o reCAPTCHA Enterprise para um projeto usando o SDK Admin. O suporte ao reCAPTCHA Enterprise 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 Enterprise 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

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

  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 Enterprise está disponível no SDK para JavaScript versões 9.20.0 e mais recentes. Depois de integrar o SDK da Web ao app, ele busca automaticamente a configuração do reCAPTCHA Enterprise 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 o SDK do Android versão 31.5.0 ou mais recente. A compatibilidade com o reCAPTCHA Enterprise 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 do reCAPTCHA Enterprise 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 do reCAPTCHA Enterprise 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 Enterprise

Depois de ativar o reCAPTCHA Enterprise, monitore as métricas do reCAPTCHA 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 Enterprise. 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 do reCAPTCHA Enterprise 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. Aplicar a integração do Identity Platform com o reCAPTCHA Enterprise interrompe as versões anteriores do app que não estão integradas ao reCAPTCHA Enterprise.

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 Enterprise

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

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

Como substituir vereditos do reCAPTCHA Enterprise com o Cloud Functions

Além de configurar os limites de pontuação, é possível substituir um veredito reCAPTCHA Enterprise 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 Enterprise, 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.