Ativar a proteção contra fraudes de cobrança por SMS para a autenticação por SMS

Este documento explica como usar o reCAPTCHA para proteger seus fluxos baseados em SMS do Identity Platform, como autenticação multifator e por telefone, contra fraudes de cobrança por SMS (também conhecidas como ataques de bombeamento de SMS).

Visão geral

Se o app depender de um fluxo baseado em SMS para autenticação, será possível ativar o recurso de proteção contra fraude de cobrança por SMS do reCAPTCHA como parte da integração do Identity Platform com o reCAPTCHA. Quando ativado, o Identity Platform invoca o recurso de proteção contra fraude de SMS quando um usuário solicita um SMS de verificação do seu app ou site usando as seguintes operações phoneProvider:

Operação Método
Fazer login ou se inscrever com um número de telefone sendVerificationCode
Registro de número de telefone do MFA mfaSmsEnrollment
Login com número de telefone de MFA mfaSmsSignIn

O reCAPTCHA fornece à Identity Platform uma pontuação de risco que indica a probabilidade de o número de telefone do usuário cometer fraude de cobrança por SMS. O Identity Platform compara essa pontuação com o limite definido na configuração de proteção contra fraudes de cobrança por SMS e processa a solicitação com base na ação definida na configuração.

Para mais informações sobre o recurso de proteção contra fraudes de cobrança por SMS do reCAPTCHA, consulte Detectar e evitar fraudes de SMS.

Antes de começar

Antes de ativar a proteção contra fraudes de pedágio por SMS no Identity Platform, conclua as seguintes tarefas:

Modos de aplicação da autenticação por smartphone do reCAPTCHA

A proteção contra fraudes de cobrança por SMS do reCAPTCHA exige que você tenha configurado a aplicação de autenticação de telefone do reCAPTCHA, que tem dois modos: auditoria e aplicação.

Modo de auditoria

Quando você define a aplicação de autenticação de smartphone no modo de auditoria, o Identity Platform usa a proteção contra fraudes de cobrança por SMS do reCAPTCHA para a verificação de apps. Se a solicitação do usuário passar pela avaliação de fraude de cobrança, o Identity Platform vai enviar uma mensagem SMS com um código de verificação para o smartphone do usuário. Se uma solicitação falhar na avaliação de fraude de pedágio e você estiver usando o SDK do cliente, os métodos de verificação alternativos serão acionados para concluir o fluxo de autenticação por telefone. Os métodos alternativos aceitos dependem da plataforma do app.

O SDK do cliente aciona os métodos de verificação de fallback nos seguintes cenários:

  • O token reCAPTCHA está ausente.
  • O token reCAPTCHA é inválido ou expirou.
  • O token reCAPTCHA não passa do limite de pontuação.
  • O reCAPTCHA não está configurado corretamente.

Verifique se os métodos de verificação substitutos para a plataforma do app estão configurados e prontos para serem acionados pelo SDK do cliente, se necessário.

Web

Se a avaliação inicial de fraude de pedágio falhar, o modo de auditoria vai usar o reCAPTCHA v2 para verificação. Portanto, é necessário configurar o verificador reCAPTCHA (RecaptchaVerifier) e transmiti-lo para as seguintes operações de autenticação por telefone:

  • verifyPhoneNumber
  • signInWithPhoneNumber
  • linkWithPhoneNumber
  • reauthenticateWithPhoneNumber
Sem o verificador reCAPTCHA, o Identity Platform não pode iniciar o reCAPTCHA v2 e vai retornar auth/argument-error. Para mais informações sobre a configuração do verificador reCAPTCHA, consulte Configurar o verificador reCAPTCHA na documentação do Firebase.

Android

Se a avaliação inicial de fraude de pedágio falhar, o modo de auditoria vai verificar seu app em relação à API Play Integrity. Se essa verificação falhar, o reCAPTCHA v2 será acionado. O reCAPTCHA v2 pode ser acionado nos seguintes cenários:

  • Se o dispositivo do usuário final não tiver o Google Play Services instalado.
  • Se o app não for distribuído pela Google Play Store (no SDK do Authentication v21.2.0 e versões mais recentes).
  • Se o token SafetyNet recebido não for válido (em versões do SDK do Authentication anteriores à v21.2.0).
Para mais informações sobre como configurar a verificação de apps Android, consulte Ativar a verificação de apps na documentação do Firebase.

iOS

Se a avaliação inicial de fraude de pedágio falhar, o modo de auditoria vai usar notificações push silenciosas para verificação. Esse método de verificação envolve o envio de um token para o app no dispositivo solicitante com uma notificação push silenciosa. Se o app receber a notificação, o fluxo de autenticação do smartphone vai prosseguir. Se o app não receber a notificação push, o reCAPTCHA v2 será acionado. O reCAPTCHA v2 pode ser acionado se as notificações push silenciosas não estiverem configuradas corretamente.

Para mais informações sobre como configurar a verificação de apps iOS, consulte Ativar a verificação de apps na documentação do Firebase.

Modo de restrição

Quando você define a aplicação da autenticação de smartphone para o modo de aplicação, o Identity Platform usa a proteção contra fraudes de cobrança por SMS do reCAPTCHA para a verificação de apps. Se a solicitação do usuário passar pela avaliação de fraude de pedágio, o Identity Platform vai enviar uma mensagem SMS com um código de verificação para o smartphone do usuário. Se a solicitação falhar na avaliação de fraude de pedágio, o Identity Platform vai bloquear a solicitação e não enviar uma mensagem SMS com um código de verificação.

Não é necessária nenhuma verificação de fallback no modo de aplicação. Você não precisa configurar outros métodos de verificação para o app. No entanto, recomendamos configurar o verificador reCAPTCHA para apps da Web e garantir que o reCAPTCHA v2 seja ativado se você decidir mudar o modo reCAPTCHA do app para AUDIT ou OFF.

Ativar a proteção contra fraudes de cobrança por SMS do reCAPTCHA

Para ativar a proteção contra fraudes de pedágio por SMS, faça o seguinte:

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

  2. Ative a proteção contra fraudes de cobrança por SMS com o reCAPTCHA. Para instruções, consulte a seção Antes de começar da página Detect and prevent SMS fraud na documentação do reCAPTCHA.

  3. Para ativar a proteção contra fraudes de cobrança por SMS em um projeto, use o SDK Admin para chamar updateConfig da seguinte maneira:

      // Update the reCAPTCHA config to enable toll fraud protection
  const updateProjectConfigRequest = {
    recaptchaConfig: {
      phoneEnforcementState: 'ENFORCE_MODE',
      useSmsTollFraudProtection: 'true',
      tollFraudManagedRules: [{ startScore: START_SCORE,
        action: 'BLOCK' }],
    }
  }
  let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);

    Substitua:

    • ENFORCE_MODE: o modo que você quer definir para a aplicação da autenticação por telefone do reCAPTCHA. Os valores válidos são OFF, AUDIT e ENFORCE. Para ativar a proteção contra fraudes de cobrança por SMS, esse parâmetro precisa ser definido como AUDIT ou ENFORCE e useSmsTollFraudProtection precisa ser definido como true.

      Ao ativar a proteção contra fraudes de cobrança por SMS pela primeira vez, recomendamos definir o estado de aplicação como AUDIT e garantir que seus fluxos de autenticação estejam protegidos antes de definir como ENFORCE. Para mais informações sobre como os modos funcionam, consulte Modos de aplicação de autenticação por telefone do reCAPTCHA.

    • START_SCORE: a maior pontuação de avaliação de fraude de pedágio que uma solicitação pode ter antes de falhar. É possível definir essa pontuação entre 0.0 e 1.0. Qualquer pontuação acima do limite definido será considerada fraude de SMS. Por exemplo, se você definir um limite de 0.3, o reCAPTCHA vai falhar em qualquer solicitação com 0.4 ou mais. Portanto, quanto menor a pontuação, mais rígidas serão as regras.

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

    • No Android, registre cada nome de pacote que usa o Identity Platform.

    • Para a Web, adicione um domínio autorizado para cada domínio que usa reCAPTCHA. Para adicionar domínios autorizados, faça o seguinte:

      1. No console do Google Cloud, acesse a página 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 reCAPTCHA pode levar vários minutos para ser concluído.

  5. Se você tiver definido a aplicação no modo de auditoria, recomendamos monitorar as métricas do reCAPTCHA para a proteção contra fraudes de cobrança por SMS para garantir que seus fluxos estejam sendo 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 por 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 que você integrar o SDK da Web ao seu app, ele vai buscar automaticamente a configuração do reCAPTCHA e ativar a proteção para os provedores configurados.

  2. Se necessário, você pode 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 por e-mail e senha e por telefone em apps Android está disponível na versão 23.1.0 do SDK do Android e mais recentes.

    Além disso, o suporte a 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, o SDK vai buscar automaticamente a configuração do reCAPTCHA e ativar 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 o SDK do reCAPTCHA na versão 18.5.1 ou mais recente.

  3. Se necessário, você pode 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 do iOS. Depois de integrar o SDK para iOS ao seu app, o SDK vai buscar automaticamente a configuração do reCAPTCHA e ativar a proteção para 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 flags do vinculador. Navegue até Target > Build Settings > All > Linking e verifique se Other Linker Flags mostra -ObjC.

  4. Se necessário, você pode 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 a proteção contra fraudes de cobrança por SMS

Antes de definir a aplicação do reCAPTCHA para ativar o modo, recomendamos usar o modo de auditoria e monitorar as métricas do reCAPTCHA emitidas pelo seu projeto para garantir que os fluxos de autenticação baseados em SMS estejam protegidos. Por exemplo, essas métricas podem ajudar a determinar se você configurou a integração da Identity Platform com a API reCAPTCHA Enterprise corretamente. Eles também podem ajudar a ajustar o limite de pontuação para o tráfego de usuários.

Para verificar se o recurso de proteção contra fraudes de pedágio por SMS está funcionando, examine as seguintes métricas emitidas pelo seu projeto para o Cloud Monitoring:

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

Aplicar a proteção contra fraudes de cobrança por SMS

Depois de verificar se o app está recebendo tráfego de usuário aceitável, você pode ativar a aplicação do reCAPTCHA para proteger seus usuários. 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 por SMS em um projeto ou locatário, use o SDK Admin para executar o seguinte comando:

  const enforceRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE',
      useSmsTollFraudProtection: 'true'
    }
  };

Desativar a proteção contra fraudes de cobrança por SMS

Para desativar a proteção contra fraudes de SMS, use o SDK Admin para executar o seguinte comando:

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

Para desativar a proteção contra fraudes de cobrança por SMS enquanto você usa a proteção contra bots, consulte Desativar a proteção contra fraudes de cobrança por SMS enquanto usa a proteção contra bots.

Usar a proteção contra fraudes de cobrança por SMS com a proteção contra bots

É possível usar a proteção contra fraudes de cobrança por SMS ao mesmo tempo que a proteção contra bots. Para configurações que usam os dois recursos de proteção, considere o seguinte:

  • Quando você define o estado de aplicação da autenticação por telefone como "Auditar", o Identity Platform transmite uma solicitação quando ela atende a pelo menos uma das avaliações. Recomendamos que você monitore as métricas do reCAPTCHA para garantir que a proteção contra fraudes de cobrança por SMS e a proteção contra bots estejam configuradas com configurações de pontuação razoáveis.
  • Quando você define o estado de ativação da autenticação por smartphone, o Identity Platform só transmite uma solicitação quando ela atende às duas avaliações e a falha da solicitação é encerrada sem recorrer a outro método de verificação.

Para ativar os dois recursos, use o SDK Admin para executar o seguinte comando:

  const enableBothRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: true,
      useSmsBotScore: true
    }
  };

Substitua ENFORCE_MODE pelo modo que você quer definir para a aplicação da autenticação por telefone do reCAPTCHA. Os valores válidos são OFF, AUDIT e ENFORCE. Para ativar a proteção contra fraudes de cobrança por SMS, esse parâmetro precisa ser definido como AUDIT ou ENFORCE. Ao ativar a proteção contra fraudes de SMS pela primeira vez, recomendamos definir esse parâmetro como AUDIT e garantir que seus fluxos de autenticação estejam protegidos antes de definir como ENFORCE. Para mais informações sobre como os modos funcionam, consulte Modos de aplicação da autenticação por telefone do reCAPTCHA.

Desative a proteção contra fraudes de cobrança por SMS ao usar a proteção contra bots

Se você estiver usando a proteção contra fraudes de cobrança por SMS e a proteção contra bots simultaneamente e quiser desativar a proteção contra fraudes de cobrança por SMS sem desativar a proteção contra bots, use o SDK Admin para executar o seguinte comando:

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

Substitua ENFORCE_MODE pelo modo que você definiu anteriormente para a aplicação da autenticação por smartphone do reCAPTCHA. Esse valor precisa ser AUDIT ou ENFORCE. Para mais informações sobre como os modos funcionam, consulte Modos de aplicação da autenticação por telefone do reCAPTCHA.

A seguir