Ativar o reCAPTCHA SMS Defense para autenticação baseada em SMS

Este documento explica como usar o reCAPTCHA SMS Defense 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). Essa integração ajuda a evitar que o tráfego de SMS não autorizado afete negativamente seus usuários e recursos.

Visão geral

Se o app usa SMS para autenticação, recomendamos ativar a integração do reCAPTCHA SMS Defense. Depois de ativado, o Firebase Authentication e o Identity Platform invocam automaticamente o recurso de defesa por SMS do reCAPTCHA sempre que um usuário final solicita uma mensagem SMS de verificação do seu app ou site usando as seguintes operações phoneProvider:

Operação Método
Inscrição ou login com número de telefone sendVerificationCode
Registro do número de telefone para MFA mfaSmsEnrollment
Login com número de telefone para MFA mfaSmsSignIn

Em seguida, o reCAPTCHA fornece ao Firebase Authentication ou à Identity Platform uma pontuação de risco que indica a probabilidade de fraude de taxa de SMS para o número de telefone do usuário. Essa pontuação é comparada ao limite configurado. Se a pontuação de risco exceder esse limite, a mensagem SMS não será enviada, bloqueando tentativas fraudulentas.

Para entender como funcionam as pontuações de defesa por SMS do reCAPTCHA, consulte Interpretar pontuações.

Para mais informações sobre o recurso de defesa por SMS do reCAPTCHA, consulte Detectar e evitar fraudes por SMS.

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

É possível configurar a restrição da autenticação por smartphone para a defesa por SMS do reCAPTCHA usando o modo de auditoria ou de restrição.

Modo de auditoria

Quando você define a restrição da autenticação por smartphone como modo de auditoria, o Identity Platform usa a defesa por SMS do reCAPTCHA para verificação de apps. Se a solicitação de um usuário for aprovada na avaliação de fraude de cobrança, um código de verificação por SMS será enviado. Se a solicitação de um usuário não passar na avaliação de fraude de cobrança e você estiver usando o SDK de cliente, o Identity Platform vai acionar métodos de verificação alternativos para concluir o fluxo de autenticação por telefone. Os métodos de substituição aceitos dependem da plataforma do app.

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

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

Verifique se os métodos de verificação alternativos 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 tarifação falhar, o modo de auditoria vai verificar seu app com a 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 ao seu app no dispositivo solicitante com uma notificação push silenciosa. Se o app receber a notificação, o fluxo de autenticação por telefone vai continuar. 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 autenticação por smartphone como modo restrito, o Identity Platform usa a defesa por SMS do reCAPTCHA para verificação de apps. Se a solicitação de um usuário for aprovada na avaliação de fraude de cobrança, um código de verificação por SMS será enviado. Se a solicitação de um usuário não passar na avaliação de fraude de cobrança, o Identity Platform vai bloquear a solicitação e não vai enviar uma mensagem SMS com um código de verificação.

Não é necessária uma verificação de substituição no modo de aplicação. Você não precisa configurar nenhum método de verificação adicional para seu app. No entanto, recomendamos configurar o verificador do reCAPTCHA para apps da Web e garantir que o reCAPTCHA v2 esteja ativado se você decidir mudar o modo do reCAPTCHA do app para AUDIT ou OFF.

Antes de começar

Antes de ativar o reCAPTCHA SMS Defense para o Identity Platform, conclua as seguintes tarefas:

Ativar o reCAPTCHA SMS Defense

  1. Configure a autenticação:

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

    2. Crie uma identidade de serviço:

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

      Substitua PROJECT_ID pelo ID do projeto.

    3. Conceda o papel roles/identitytoolkit.serviceAgent à identidade de serviço que você criou.

    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

  2. Ative a API reCAPTCHA Enterprise no seu projeto.

  3. Ative o reCAPTCHA SMS Defense para seu projeto:

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

      Acessar o reCAPTCHA

    2. Verifique se o nome do projeto aparece no seletor de recursos.

      Se você não vir o nome do projeto, clique no seletor de recursos e selecione o projeto.

    3. Clique em Configurações.

    4. No painel Defesa por SMS, clique em Configurar.

    5. Clique no botão Ativar e em Salvar.

    Quando você ativa o reCAPTCHA SMS Defense, o defensor da conta também é ativado, se ainda não estiver.

    Pode levar alguns minutos para que a ativação do reCAPTCHA SMS Defense seja propagada nos nossos sistemas. Depois da propagação, você vai começar a receber respostas relacionadas ao reCAPTCHA SMS Defense como parte das avaliações.

  4. Para configurar as configurações de defesa por SMS do reCAPTCHA em um projeto do Firebase Authentication ou do Identity Platform, faça o seguinte:

    1. No URL a seguir, substitua PROJECT_ID, Recaptcha_MODE e START_SCORE:

      https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"emailPasswordEnforcementState":"OFF","phoneEnforcementState":"Recaptcha_MODE","useSmsTollFraudProtection":true,"tollFraudManagedRules":[{"action":"BLOCK","startScore":START_SCORE}]}}}

      • PROJECT_ID: o identificador do projeto com a plataforma de identidade ativada.

      • Recaptcha_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 o reCAPTCHA SMS Defense, esse parâmetro precisa ser definido como AUDIT ou ENFORCE e useSmsTollFraudProtection precisa ser definido como true.

        Ao ativar o reCAPTCHA SMS Defense pela primeira vez, use o modo AUDIT para garantir que a configuração do reCAPTCHA SMS Defense esteja funcionando corretamente. O modo AUDIT é estritamente para fins de verificação. Esse modo não impede o tráfego de SMS não autorizado. Verifique se não há falhas no painel Métricas. Depois da verificação, ative o modo ENFORCE imediatamente. Para mais informações sobre como os modos funcionam, consulte modos de aplicação da autenticação por telefone do reCAPTCHA.

      • START_SCORE: a maior pontuação de avaliação de fraude de tarifação que uma solicitação pode ter antes de falhar. É possível definir essa pontuação entre 0.1 e 0.9. Recomendamos começar com um limite mais alto, por exemplo, 0.8, e depois diminuir a pontuação de forma iterativa. As pontuações acima do limite definido são tratadas como fraude por SMS. Definir uma pontuação como 1,0 desativa a proteção contra fraudes, enquanto definir uma pontuação de 0,0 bloqueia todas as mensagens SMS. Quanto menor a pontuação, mais rígidas são as regras. Se você definir um limite de 0.3, por exemplo, o reCAPTCHA vai falhar em qualquer solicitação com uma pontuação de 0.4 ou mais.

    2. Insira o URL em uma nova janela do navegador em que você fez login no console Google Cloud .

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

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

  2. Verifique a configuração:

    • Extraia os detalhes da configuração do reCAPTCHA:

      {replace-your-project} com seu projectId ou projectNumber. Execute a API GetConfig no painel lateral para buscar a configuração do reCAPTCHA.

    • Verifique se o reCAPTCHA SMS Defense está configurado corretamente:

      1. Se a configuração do reCAPTCHA estiver correta, a resposta terá os seguintes campos com os valores especificados:

        • recaptchaKeys: o campo não pode estar vazio e precisa estar configurado para pelo menos uma destas plataformas: iOS, Web ou Android.
        • useSmsTollFraudProtection: o valor desse campo precisa ser definido como true.
        • phoneEnforcementState: o valor precisa ser definido como ENFORCE ou AUDIT.
        • tollFraudManagedRules: neste campo, startScore precisa ser configurado com o limite escolhido, que deve ser um valor entre 0 e 0,9.

        Caso contrário, configure o reCAPTCHA SMS Defense novamente.

        Exemplo de resposta

          {
    "recaptchaConfig": {
        "recaptchaKeys": [
          {
            "key": "projects/{your-project}/keys/{recaptcha-key}",
            "type": "WEB"
          },
          {
            "type": "IOS"
          },
          {
            "type": "ANDROID"
          }
        ],
        "phoneEnforcementState": "ENFORCE",
        "tollFraudManagedRules": [
          {
            "startScore": 0.8,
            "action": "BLOCK"
          }
        ],
        "useSmsTollFraudProtection": true
    }
  }
  ```

  3. Verifique se as versões do SDK estão corretas.

    Web

    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 de integrar o SDK da Web ao seu app, ele busca automaticamente a configuração do reCAPTCHA e ativa a proteção para os provedores que você configurou.

    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 autenticação por telefone em apps Android está disponível no SDK do Android versão 23.1.0 e mais recente.

      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 seu app, ele busca automaticamente a configuração do reCAPTCHA e aplica os limites definidos 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.

    iOS

    1. Atualize para a versão 11.6.0 ou mais recente do SDK do iOS.

    Depois de integrar o SDK do iOS ao seu app, ele busca automaticamente a configuração do reCAPTCHA e aplica os limites definidos para os provedores configurados.

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

    2. Para verificar se -ObjC está listado nas sinalizações do vinculador, navegue até Target > Build Settings > All > Linking e verifique se Other Linker Flags mostra -ObjC.

Monitorar métricas do reCAPTCHA para o reCAPTCHA SMS Defense

Monitore as métricas do reCAPTCHA emitidas pelo projeto para verificar se os fluxos de autenticação baseados em SMS estão protegidos. Por exemplo, essas métricas podem ajudar você a determinar se configurou corretamente a integração do Identity Platform com a API reCAPTCHA Enterprise. Elas também ajudam a refinar o limite de pontuação para o tráfego de usuários.

Verifique se o recurso reCAPTCHA SMS Defense está funcionando conferindo as seguintes métricas que seu projeto emite para o Cloud Monitoring:

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

Aplicar o reCAPTCHA SMS Defense

Depois de verificar se o app está recebendo um tráfego de usuários aceitável, ative o modo ENFORCE do reCAPTCHA para bloquear ativamente solicitações fraudulentas e proteger os usuários.

Para ativar o modo ENFORCE em fluxos de autenticação baseados em SMS em um projeto ou locatário, use o Google APIs Explorer para atualizar a configuração do projeto inserindo o seguinte URL HTTP em uma nova janela do navegador em que você fez login no console Google Cloud :

   https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"phoneEnforcementState":"ENFORCE","useSmsTollFraudProtection":"true"}}}

Substitua PROJECT_ID pelo ID do projeto.

Usar o reCAPTCHA SMS Defense com proteção contra bots

É possível usar o reCAPTCHA SMS Defense simultaneamente com 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 AUDIT, 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 verificar se a defesa por SMS do reCAPTCHA e a proteção contra bots estão configuradas com configurações de pontuação razoáveis.
  • Quando você define o estado de restrição da autenticação por telefone como ENFORCE, o Identity Platform só transmite uma solicitação quando ela atende às duas avaliações e a falha na solicitação é encerrada sem voltar para outro método de verificação.

Para ativar os dois recursos, use o Google APIs Explorer para atualizar a configuração do projeto:

        recaptchaConfig: {
          phoneEnforcementState:  'ENFORCE_MODE',
          useSmsTollFraudProtection: true,
          useSmsBotScore: true
        }

Substitua ENFORCE_MODE pelo modo que você quer definir para a restrição da autenticação por smartphone do reCAPTCHA. Os valores válidos são OFF, AUDIT e ENFORCE. Ao ativar a defesa por SMS do reCAPTCHA 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.

Desativar o reCAPTCHA SMS Defense ao usar a proteção contra bots

Se você estiver usando a defesa por SMS do reCAPTCHA e a proteção contra bots simultaneamente e quiser desativar a defesa por SMS do reCAPTCHA sem desativar a proteção contra bots, use o Google APIs Explorer para atualizar a configuração do projeto:

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }

Substitua ENFORCE_MODE pelo modo que você definiu anteriormente para a restriçã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.

Desativar o reCAPTCHA SMS Defense

Para desativar a defesa por SMS do reCAPTCHA, use o Google APIs Explorer para atualizar a configuração do projeto. Para isso, insira o seguinte URL HTTP em uma nova janela do navegador em que você fez login no console Google Cloud :


   https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"phoneEnforcementState":"OFF","useSmsTollFraudProtection":"false"}}}

Substitua PROJECT_ID pelo ID do projeto.

Para desativar o reCAPTCHA SMS Defense enquanto usa a proteção contra bots, consulte Desativar o reCAPTCHA SMS Defense enquanto usa a proteção contra bots.

A seguir