Ativar o reCAPTCHA Enterprise

Este documento mostra como usar a integração do Identity Platform com o reCAPTCHA para melhorar a segurança dos seus 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 avaliação reCAPTCHA em seu nome para validar as solicitações do usuário. Para informações sobre preços, consulte os preços do reCAPTCHA.

Visão geral

Quando você configura a integração do Identity Platform com o reCAPTCHA, o Identity Platform provisiona as chaves de site reCAPTCHA com base 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:

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

O reCAPTCHA fornece sinais de risco ao Identity Platform que avaliam o risco da solicitação com base na sua configuração e na sua tolerância a riscos.

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

Antes de começar

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

Crie uma conta de serviço

Antes de ativar o reCAPTCHA, você precisa criar uma conta de serviço para cada projeto que vai usar o reCAPTCHA e conceder acesso a cada conta de serviço. Isso permite que o Identity Platform gerencie as chaves do reCAPTCHA em seu nome.

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

  1. Use a 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: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 reCAPTCHA

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

  • Auditoria: quando ativada, o Identity Platform cria uma ou mais chaves reCAPTCHA no seu 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 você precisa ativar a aplicação do reCAPTCHA.
  • Aplicação: quando ativada, o Identity Platform cria um ou mais reCAPTCHA chaves 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 com suporte ao reCAPTCHA.

Para ativar o reCAPTCHA, faça o seguinte:

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

  2. Ativar a integração do Identity Platform com o reCAPTCHA para um projeto usando o SDK Admin. reCAPTCHA o suporte está disponível para as versões 11.7.0 e posteriores 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

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

  5. Se você estiver usando o Identity Platform na Web, adicione 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.

      Acesse 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 seus fluxos estejam sendo protegidos, verifique as métricas.

Configurar o SDK do cliente

Configure o SDK do cliente de acordo com a plataforma do app.

Web

  1. Atualize para a versão mais recente do SDK da Web. O suporte a reCAPTCHA está disponível nas versões 9.20.0 e mais recentes do SDK do JavaScript. Depois de integrar o SDK da Web ao seu app, ele vai buscar automaticamente sua 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 do reCAPTCHA, recomendamos configurá-lo 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. O suporte a 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 seu app, ele buscará automaticamente sua configuração reCAPTCHA e protege os provedores configurados.

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

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

    Use o SDK reCAPTCHA 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 do reCAPTCHA mais eficaz, recomendamos a configuração explícita 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 a versão 10.14.0 ou mais recente do SDK do iOS. Depois de integrar o SDK do iOS ao seu aplicativo, ele busca automaticamente sua configuração reCAPTCHA e protege os provedores configurados.

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

  3. Verifique se -ObjC está listado nas flags do vinculador. Acesse Target > Configurações do build > Todos > Vinculando e verificando 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 do reCAPTCHA mais eficaz, recomendamos que você o 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 do reCAPTCHA que seu projeto emite para garantir que os fluxos de autenticação estejam protegidos. Se o provisionamento da chave do site reCAPTCHA falhar ou se as contas de serviço necessárias não forem criadas, a autenticação do reCAPTCHA vai falhar.

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. Um veredito será gerado se um token estiver presente. É possível filtrar pelos 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 do reCAPTCHA está ativado.
  • FAILED_ENFORCE: indica que uma determinada solicitação é negada quando 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 se uma solicitação foi enviada usando uma versão desatualizada do SDK do cliente que não tem suporte para reCAPTCHA.
  • KEYS_MISSING: indica que determinada solicitação não pode ser verificada devido ao incapacidade de recuperar ou gerar chaves reCAPTCHA válidas quando A aplicação do reCAPTCHA está ativada.

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

identitytoolkit.googleapis.com/recaptcha/token_count

Monitora 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 do cliente ou abuso.
  • DUPLICATE: indica que o token reCAPTCHA transmitido é um duplicado. 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 especificada. Tokens ausentes podem indicar um app cliente desatualizado.
  • UNCHECKED: indica que o token reCAPTCHA não foi verificado devido a vereditos CLIENT_TYPE_MISSING ou KEYS_MISSING.

Se o aplicativo for lançado para os usuários, você 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 seu aplicativo atualizado.

identitytoolkit.googleapis.com/recaptcha/risk_scores

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

Use essas métricas para determinar se é possível 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 sua empresa, ative a aplicação.
  • Se a maioria das solicitações recentes for de clientes desatualizados, considere aguardando que mais usuários atualizem o aplicativo antes de ativar a aplicação obrigatória. Aplicar a integração do Identity Platform com o reCAPTCHA interrompe as versões anteriores do app que não estão integrados ao reCAPTCHA.

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

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

    Acessar o Metrics Explorer

  2. Em Selecionar uma métrica, insira Tenant do Identity Toolkit. Se você estiver usando a multilocação, poderá ver as métricas de cada locatário, bem como o projeto pai, deixando tenant_name em branco.

Ativar aplicação

Depois de verificar se o app está recebendo tráfego aceitável de usuários, faça o seguinte: ative a aplicação reCAPTCHA para proteger seus usuários. Não interrompa os usuários atuais, incluindo aqueles que utilizam um mais antiga do seu 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 funções do Cloud Run

Além de configurar limites de pontuação, é possível modificar uma veredito do reCAPTCHA para um determinado token usando uma função de bloqueio das funções personalizadas do Cloud Run. Isso é útil nos casos em que uma pontuação reCAPTCHA para um determinado usuário o login pode estar baixo, mas o usuário é confiável ou foi verificado por meio de outro significa 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, se inscrever ou redefinir a senha

Os usuários podem estar usando uma versão desatualizada do app. Se você não ofereceu 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.

Os usuários também podem ser bloqueados com base na sua configuração atual. Tente o seguinte:

  • Ajuste-a e considere uma configuração mais abrangente. Pontuações da chave reCAPTCHA.
  • Peça para o usuário tentar usar um dispositivo, navegador ou rede diferente.
  • Retorne ao modo de auditoria e monitore as métricas antes de reativar o modo de aplicação.