Integrar o Identity Platform à API reCAPTCHA Enterprise

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

A integração cria uma avaliação do reCAPTCHA Enterprise em seu nome para validar as solicitações do usuário. Para informações sobre preços, consulte Preços do reCAPTCHA.

Visão geral

Ao configurar a integração do Identity Platform com a API reCAPTCHA Enterprise, você ativa o recurso de proteção padrão do reCAPTCHA: a proteção contra bots do reCAPTCHA. Com a proteção contra bots, o Identity Platform provisiona chaves reCAPTCHA baseadas em pontuação no seu 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 quando o provedor correspondente está ativado.

Provedor Operação Método
passwordProvider Login com e-mail e senha signInWithPassword
Inscrição com e-mail e senha signUpPassword
Login por link de e-mail getOobCode
Redefinição de senha getOobCode
phoneProvider Inscrição ou login com número de telefone sendVerificationCode
Registro de número de telefone para MFA mfaSmsEnrollment
Login com número de telefone de MFA mfaSmsSignIn

Em seguida, o reCAPTCHA fornece ao Identity Platform pontuações que avaliam o risco da solicitação com base na sua configuração e tolerância ao risco.

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

Antes de começar

Com base no tipo de fluxo de autenticação que você quer proteger com o reCAPTCHA, verifique se você configurou o seguinte:

Criar uma conta de serviço

A integração do Identity Platform com a API reCAPTCHA Enterprise requer uma conta de serviço do Identity Platform para cada projeto que usará o reCAPTCHA. Isso permite que o Identity Platform gerencie as chaves reCAPTCHA em seu nome. Se você já criou uma conta de serviço, conceda a ela acesso ao reCAPTCHA.

Se você ainda não criou uma conta de serviço ou tem outros projetos que quer proteger com o reCAPTCHA, 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. \
        --role=roles/identitytoolkit.serviceAgent
    

    Substitua:

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

Comportamento da proteção contra bots do reCAPTCHA por provedor

O comportamento da proteção contra bots do reCAPTCHA depende do provedor de identidade que você configurar:

Provedor de e-mail/senha

Para fluxos de autenticação de e-mail e senha, a proteção contra bots do reCAPTCHA oferece dois modos: auditoria e aplicação.

Modo de auditoria

Quando você define a aplicação de e-mail/senha para o modo de auditoria, 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.

Modo restrito

Quando você define a aplicação de e-mail/senha para o modo restrito, 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. As solicitações de API que não incluem um token do reCAPTCHA são rejeitadas. Só ative a aplicação depois de migrar todos os clientes para um SDK com suporte ao reCAPTCHA.

Operadora de telefonia

Quando você ativa a proteção contra bots para fluxos de autenticação por telefone definindo phoneEnforcementState como ENFORCE e useSmsBotScore como true, o Identity Platform usa a proteção contra bots do reCAPTCHA para verificação de apps. Se a solicitação de um usuário for aprovada na avaliação de proteção contra bots, um código de verificação por SMS será enviado. Se a solicitação de um usuário for reprovada na avaliação de proteção contra bots, o Identity Platform vai bloquear a solicitação e não vai enviar uma mensagem SMS com um código de verificação.

A verificação de fallback não é necessária quando a proteção contra bots está ativada para fluxos de autenticação por telefone, e você não precisa configurar nenhum outro método de verificação para seu app. No entanto, recomendamos configurar o verificador reCAPTCHA para apps da Web para garantir que o reCAPTCHA v2 esteja disponível se você decidir desativar a proteção contra bots.

Configurar a integração do Identity Platform com a API reCAPTCHA Enterprise

Para configurar a integração do Identity Platform com a API reCAPTCHA Enterprise, realize as seguintes tarefas:

  • Use o SDK Admin para definir o estado de aplicação do reCAPTCHA e ativar a proteção contra bots.
  • Configure o SDK do cliente para a plataforma do seu app.

Para fluxos de autenticação de e-mail e senha, recomendamos que você primeiro ative a aplicação do reCAPTCHA no modo de auditoria e monitore as métricas do reCAPTCHA emitidas pelo seu projeto para evitar a interrupção do tráfego do usuário enquanto verifica se os fluxos de autenticação estão protegidos. Depois de verificar se os fluxos de autenticação estão protegidos, defina a proteção contra bots como ENFORCE. Para fluxos de autenticação por telefone, ative a proteção contra bots definindo phoneEnforcementState como ENFORCE e useSmsBotScore como true e monitore as métricas do reCAPTCHA para ajustar os limites de pontuação.

Ativar a proteção contra bots do reCAPTCHA

Provedor de e-mail/senha

Para ativar a proteção contra bots do reCAPTCHA para fluxos de autenticação de e-mail e senha, faça o seguinte:

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

  2. Para ativar a proteção contra bots em um projeto, use 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:

    // Update project config with reCAPTCHA config
    const updateConfigRequest = {
      recaptchaConfig: {
        emailPasswordEnforcementState:  'ENFORCE_MODE',
        managedRules: [{
          endScore: END_SCORE,
          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);
      });
    }
    

    Substitua:

    • ENFORCE_MODE: o modo que você quer definir para a aplicação da autenticação de e-mail/senha do reCAPTCHA. Os valores válidos são OFF, AUDIT e ENFORCE. Para ativar a proteção contra bots, esse parâmetro precisa ser definido como AUDIT ou ENFORCE. Ao ativar a proteção contra bots pela primeira vez, recomendamos definir esse parâmetro como AUDIT e garantir que os fluxos de autenticação estejam protegidos antes de definir como ENFORCE. Para mais informações sobre como os modos funcionam, consulte Comportamento da proteção contra bots do reCAPTCHA por provedor.
    • END_SCORE: a menor pontuação de avaliação de proteção contra bots que uma solicitação pode ter antes de falhar. É possível definir essa pontuação entre 0.0 e 1.0. Por exemplo, se você definir um limite de 0.6, o reCAPTCHA vai falhar em qualquer solicitação com 0.5 ou menos. Portanto, quanto maior a pontuação definida, mais rígidas serão as regras.

    Também é possível ativar a proteção contra bots com o mesmo método de configuração para um locatário usando o SDK Admin. Para mais informações sobre como atualizar um locatário, consulte Atualizar um locatário.

  3. Se você usa o Identity Platform no iOS ou no Android, é necessário registrar o app no console do Firebase:

    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 de domínio e clique em Adicionar para salvá-lo.

    O provisionamento da chave reCAPTCHA pode levar vários minutos para ser concluído.

  4. Se você tiver definido a aplicação como modo de auditoria, recomendamos monitorar as métricas do reCAPTCHA para proteção contra bots para garantir que seus fluxos estejam protegidos.

Operadora de telefonia

Para ativar a proteção contra bots do reCAPTCHA para fluxos de autenticação baseados em SMS, faça o seguinte:

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

  2. Para ativar a proteção contra bots em um projeto, use o SDK Admin. O suporte ao reCAPTCHA está disponível nas versões 12.7.0 e mais recentes do SDK Admin para Node.js.

    Exemplo:

    // Update project config with reCAPTCHA config
    const updateProjectConfigRequest = {
      recaptchaConfig: {
        phoneEnforcementState: 'ENFORCE',
        managedRules: [{
          endScore: END_SCORE,
          action: 'BLOCK'
        }],
        useSmsBotScore: true,
      }
    };
    let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
    

    Substitua END_SCORE pela menor pontuação de avaliação de proteção contra bots que uma solicitação pode ter antes de falhar. É possível definir essa pontuação entre 0.0 e 1.0. Por exemplo, se você definir um limite de 0.6, o reCAPTCHA vai falhar em qualquer solicitação com 0.5 ou menos. Portanto, quanto maior a pontuação, mais rígidas serão as regras.

    Definir phoneEnforcementState como ENFORCE e useSmsBotScore como true ativa a aplicação da proteção contra bots para fluxos de autenticação baseados em SMS. Para mais informações sobre como funciona a aplicação do provedor de telefonia, consulte Comportamento da proteção contra bots do reCAPTCHA por provedor.

    Também é possível ativar a proteção contra bots com o mesmo método de configuração para um locatário usando o SDK Admin. Para mais informações sobre como atualizar um locatário, consulte Atualizar um locatário.

  3. Se você estiver usando o Identity Platform no iOS ou Android, registre seu app no console do Firebase:

    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 de domínio e clique em Adicionar para salvá-lo.

    O provisionamento da chave reCAPTCHA pode levar vários minutos para ser concluído.

  4. Monitore as métricas do reCAPTCHA para proteção contra bots para garantir que seus fluxos estejam protegidos.

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 do reCAPTCHA para autenticação de e-mail e senha em apps da Web está disponível nas versões 9.20.0 e mais recentes do SDK para JavaScript.
    • O suporte do reCAPTCHA para autenticação por telefone em apps da Web está disponível nas versões 11 e mais recentes do SDK para JavaScript.

    Depois de integrar o SDK da Web ao app, ele busca automaticamente sua configuração do reCAPTCHA e ativa a proteção para os provedores que você configurou.

  2. Se necessário, é possível forçar a busca do indicador reCAPTCHA da seguinte maneira:

    import { initializeRecaptchaConfig } from '@firebase/auth';
    
    // Initialize Firebase Authentication
    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 mais recente do SDK do Android. O suporte do reCAPTCHA para autenticação de e-mail e senha e autenticação por telefone em apps Android está disponível na versão 23.1.0 e mais recentes do SDK do Android.

    Além disso, o suporte ao reCAPTCHA exige o nível 23 da API (Marshmallow) ou mais recente e o Android 6 ou mais recente.

    Depois de integrar o SDK do Android ao app, ele busca automaticamente sua configuração do reCAPTCHA e ativa a proteção para os provedores que você configurou.

  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.5.1'
    

    Use a versão 18.5.1 ou mais recente do SDK do reCAPTCHA.

  3. Se necessário, é possível forçar a busca do indicador reCAPTCHA da seguinte maneira:

    • Kotlin
    // Initialize Firebase Authentication
    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 Authentication
    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 11.6.0 ou mais recente do SDK para iOS. Depois de integrar o SDK para iOS ao app, ele busca automaticamente sua configuração do reCAPTCHA e ativa a proteção para os provedores que você configurou.

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

  3. Verifique se -ObjC está listado nas flags do vinculador. Acesse Target > Build Settings > All > Linking e verifique se Other Linker Flags mostra -ObjC.

  4. Se necessário, é possível forçar a busca do indicador reCAPTCHA da seguinte maneira:

    • Swift:
    // Initialize Firebase Authentication
    try await Auth.auth().initializeRecaptchaConfig()
    
    • Objective-C:
    // Initialize Firebase Authentication
    [[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
      // Firebase Authentication initialization finished
    }];
    

Monitorar as métricas do reCAPTCHA para proteção contra bots

Monitore as métricas do reCAPTCHA emitidas pelo projeto para garantir que os fluxos de autenticação estejam protegidos. Para fluxos de autenticação de senha de e-mail, recomendamos monitorar as métricas no modo de auditoria antes de definir a aplicação para o modo restrito. Por exemplo, essas métricas podem ajudar a determinar se você configurou corretamente a integração do Identity Platform com a API reCAPTCHA Enterprise. Eles também podem ajudar você a ajustar o limite de pontuação para o tráfego de usuários. Se o provisionamento da chave do reCAPTCHA falhar ou se as contas de serviço necessárias não forem criadas, as tentativas de autenticação do reCAPTCHA ainda serão bem-sucedidas normalmente.

Para garantir que a autenticação do reCAPTCHA esteja funcionando, examine as seguintes métricas que seu projeto emite para o Cloud Monitoring:

Para mais informações, consulte Monitorar métricas do reCAPTCHA.

Aplicar a proteção contra bots do reCAPTCHA para fluxos de e-mail/senha

Para fluxos de autenticação de e-mail e senha que você configurou inicialmente no modo AUDIT, depois de verificar se o app está recebendo tráfego de usuários aceitável, mude emailPasswordEnforcementState para ENFORCE para bloquear solicitações que não passam no teste reCAPTCHA. Não interrompa os usuários atuais, incluindo aqueles que podem estar usando uma versão mais antiga do app.

Para ativar a aplicação do reCAPTCHA para fluxos de autenticação de e-mail e senha em um projeto ou locatário, use o SDK Admin para executar o seguinte código:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState: 'ENFORCE',
  }
};

Desativar a proteção contra bots do reCAPTCHA

Provedor de e-mail/senha

Para desativar a proteção contra bots para fluxos de autenticação de e-mail e senha, use o SDK Admin para executar o seguinte comando:

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

Operadora de telefonia

Para desativar toda a proteção do reCAPTCHA para smartphones, incluindo a proteção contra bots, para fluxos de autenticação baseados em SMS, use o SDK Admin para executar o seguinte comando:

const disableRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'OFF',
    useSmsBotScore: false,
    useSmsTollFraudProtection: false
  }
};

Se você também estiver usando a defesa de SMS do reCAPTCHA e quiser mantê-la ativada ao desativar a proteção contra bots, defina useSmsBotScore como false e deixe phoneEnforcementState definido como ENFORCE:

const disableBotScoreOnlyRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    useSmsBotScore: false,
    useSmsTollFraudProtection: true
  }
};

Substituir vereditos do reCAPTCHA com o Cloud Run functions

Além de configurar limites de pontuação, é possível substituir um veredicto do reCAPTCHA para um determinado token usando funções de bloqueio para permitir ou bloquear fluxos com base em fatores personalizados. Isso é útil nos casos em que uma pontuação do 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.

O exemplo a seguir mostra como substituir um veredito do reCAPTCHA usando funções de bloqueio:

Node.js

  const functions = require("firebase-functions/v1");
  exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
    if (
      context.smsType === "SIGN_IN_OR_SIGN_UP" &&
      context.additionalUserInfo.phoneNumber.includes('+91')
    ) {
      return {
        recaptchaActionOverride: "ALLOW",
      };
    }

    // Allow users to sign in with recaptcha score greater than 0.5
    if (event.additionalUserInfo.recaptchaScore > 0.5) {
      return {
        recaptchaActionOverride: 'ALLOW',
      };
    }

    // Block all others.
    return  {
      recaptchaActionOverride: 'BLOCK',
    }
  });

A seguir