Esta página foi traduzida pela API Cloud Translation.

Ative a defesa por SMS do reCAPTCHA para a autenticação baseada em SMS

Este documento explica como pode usar a defesa por SMS do reCAPTCHA para ajudar a proteger os seus fluxos baseados em SMS da Identity Platform, como a autenticação por telemóvel e multifator, contra a fraude de custos por SMS (também conhecida como ataques de bombeamento de SMS). Esta integração ajuda a impedir que o tráfego de SMS não autorizado afete negativamente os seus utilizadores e recursos.

Vista geral

Se a sua app depender de SMS para autenticação, recomendamos que ative a integração da defesa por SMS do reCAPTCHA. Depois de ativada, a Firebase Authentication e a Identity Platform invocam automaticamente a funcionalidade de defesa de SMS do reCAPTCHA sempre que um utilizador final solicitar uma mensagem SMS de validação da sua app ou site através das seguintes operações phoneProvider:

Operação	Método
Inscrição ou início de sessão com número de telefone	`sendVerificationCode`
Inscrição do número de telefone para MFA	`mfaSmsEnrollment`
Início de sessão com número de telefone da 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 cobrança por SMS para o número de telefone do utilizador. Em seguida, esta pontuação é comparada com o limite configurado. Se a pontuação de risco exceder este limite, a mensagem SMS não é enviada, o que bloqueia efetivamente as tentativas fraudulentas.

Para compreender como funcionam as pontuações de defesa de SMS do reCAPTCHA, consulte o artigo Interpretar pontuações.

Para mais informações acerca da funcionalidade de defesa por SMS do reCAPTCHA, consulte o artigo Detete e evite fraudes por SMS.

Modos de aplicação da autenticação telefónica do reCAPTCHA

Pode configurar a aplicação da autenticação por telefone para a defesa por SMS do reCAPTCHA para usar o modo de auditoria ou de aplicação.

Modo de auditoria

Quando define a aplicação da autenticação por telefone para o modo de auditoria, a Identity Platform usa a defesa por SMS do reCAPTCHA para a validação de apps. Se o pedido de um utilizador passar na avaliação de fraude de custos, é enviado um código de validação por SMS. Se o pedido de um utilizador falhar na avaliação de fraude de tarifação e estiver a usar o SDK do cliente, o Identity Platform aciona métodos de validação alternativos para concluir o fluxo de autenticação por telefone. Os métodos alternativos aceites dependem da plataforma da sua app.

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

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

Certifique-se de que os métodos de validação alternativos para a plataforma da sua 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 custos falhar, o modo de auditoria baseia-se no reCAPTCHA v2 para validação. Por conseguinte, tem de configurar o validador do reCAPTCHA (RecaptchaVerifier) e transmiti-lo às seguintes operações de autenticação por telemóvel:

verifyPhoneNumber
signInWithPhoneNumber
linkWithPhoneNumber
reauthenticateWithPhoneNumber

Sem o validador do reCAPTCHA, o Identity Platform não pode iniciar o reCAPTCHA v2 e devolve auth/argument-error. Para mais informações sobre como configurar o verificador do reCAPTCHA, consulte o artigo Configure o verificador do reCAPTCHA na documentação do Firebase.

Android

Se a avaliação inicial de fraude de tarifação falhar, o modo de auditoria valida a sua app com base na API Play Integrity. Se esta validação falhar, o reCAPTCHA v2 é acionado. O reCAPTCHA v2 pode ser acionado nos seguintes cenários:

Se o dispositivo do utilizador final não tiver os Serviços do Google Play instalados.
Se a app não for distribuída através da Google Play Store (no SDK de autenticação v21.2.0 e posterior).
Se o token do SafetyNet obtido não for válido (em versões do SDK de autenticação anteriores à v21.2.0).

Para mais informações sobre a configuração da validação de apps Android, consulte o artigo Ative a validação de apps na documentação do Firebase.

iOS

Se a avaliação inicial de fraude de portagens falhar, o modo de auditoria baseia-se em notificações push silenciosas para validação. Este método de validação envolve o envio de um token para a sua app no dispositivo que está a fazer o pedido com uma notificação push silenciosa. Se a sua app receber com êxito a notificação, o fluxo de autenticação por telemóvel continua. Se a sua app não receber a notificação push, o reCAPTCHA v2 é acionado. O reCAPTCHA v2 pode ser acionado se as notificações push silenciosas não estiverem configuradas corretamente.

Para mais informações sobre a configuração da validação de apps iOS, consulte o artigo Ative a validação de apps na documentação do Firebase.

Modo de aplicação

Quando define a aplicação da autenticação por telefone para o modo de aplicação, o Identity Platform usa a defesa por SMS do reCAPTCHA para a validação de apps. Se o pedido de um utilizador passar na avaliação de fraude de custos, é enviado um código de validação por SMS. Se o pedido de um utilizador falhar na avaliação de fraude de chamadas de custo elevado, o Identity Platform bloqueia o pedido e não envia uma mensagem SMS com um código de validação.

Não é necessária nenhuma validação alternativa no modo de aplicação. Não tem de configurar métodos de validação adicionais para a sua app. No entanto, recomendamos que configure o validador reCAPTCHA para apps Web para garantir que o reCAPTCHA v2 está ativado se decidir alterar o modo reCAPTCHA da sua app para AUDIT ou OFF.

Antes de começar

Antes de ativar a defesa por SMS do reCAPTCHA para a Identity Platform, conclua as seguintes tarefas:

Configure o seguinte para a sua app ou site, conforme aplicável:
- Início de sessão por telefone para utilizadores.
- Autenticação multifator para a sua app Web, Android ou iOS.
Configure o Firebase Authentication para a sua app ou site, conforme aplicável:
- Web: Configuração da autenticação por telemóvel
- iOS: configuração da autenticação por telemóvel
- Android: configuração da autenticação por telemóvel

Ative a defesa por SMS do reCAPTCHA

Configurar 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 a função roles/identitytoolkit.serviceAgent à identidade do serviço que 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 o seguinte:
  - PROJECT_ID: o ID do projeto
  - PROJECT_NUMBER: o número de conta do projeto
Ative a API reCAPTCHA Enterprise no seu projeto.
Ative a defesa por SMS do reCAPTCHA para o seu projeto:
1. Na Google Cloud consola, aceda à página do reCAPTCHA.
  
  Aceder ao reCAPTCHA
2. Verifique se o nome do seu projeto aparece no seletor de recursos.
  
  Se não vir o nome do seu projeto, clique no seletor de recursos e, de seguida, selecione o seu projeto.
3. Clique em Definições.
4. No painel Defesa contra SMS, clique em Configurar.
5. Clique no botão para ativar e clique em Guardar.
Quando ativa a defesa por SMS do reCAPTCHA, o Account Defender também é ativado, se ainda não estiver ativado.

A ativação da defesa por SMS do reCAPTCHA pode demorar alguns minutos a propagar-se aos nossos sistemas. Após a propagação, começa a receber respostas relacionadas com a defesa por SMS do reCAPTCHA como parte das avaliações.
Para configurar as definições de defesa de SMS do reCAPTCHA para um projeto do Firebase Authentication ou da Identity Platform, faça o seguinte:
1. No URL seguinte, 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 quer definir para a aplicação da autenticação telefónica do reCAPTCHA. Os valores válidos são OFF, AUDIT e ENFORCE. Para ativar a defesa por SMS do reCAPTCHA, este parâmetro tem de ser definido como AUDIT ou ENFORCE e useSmsTollFraudProtection tem de ser definido como true.
    
    Quando ativa a defesa por SMS do reCAPTCHA pela primeira vez, use o modo AUDIT para se certificar de que a configuração da defesa por SMS do reCAPTCHA está a funcionar corretamente. O modo AUDIT destina-se estritamente a fins de validação. Este modo não impede o tráfego de SMS não autorizado. Verifique se não são apresentadas falhas no painel de controlo Métricas. Após a validação, ative o modo ENFORCE imediatamente. Para mais informações sobre o funcionamento dos modos, consulte os modos de aplicação da autenticação telefónica do reCAPTCHA
  - START_SCORE: um limite configurável que determina a pontuação mais alta que um pedido de SMS pode ter antes de ser denunciado e bloqueado como fraude de custos.
    
    O limite mínimo é de 0.0. O limite máximo é 0.9. Qualquer pedido com uma pontuação superior ao limite é considerado fraudulento. Por exemplo, se definir o limite como 0.3, o reCAPTCHA bloqueia todos os pedidos com uma pontuação de fraude de 0.4 ou superior.
    
    Para aumentar o nível de proteção contra fraudes, defina o limite para um valor inferior. Para reduzir o nível de proteção contra fraudes, defina o limite para um valor mais elevado. Esta definição permite a passagem de mais pedidos com pontuações mais elevadas.
    
    Para a implementação inicial, recomendamos que comece com um limite mais elevado, como 0.8, e, em seguida, o diminua iterativamente de acordo com a sua tolerância ao risco específica.
    
    Não recomendamos um limite de 0.0 ou 1.0. A definição do limite para 0.0 bloqueia todas as mensagens SMS, enquanto 1.0 desativa completamente a proteção contra fraudes, o que pode resultar em falhas na entrega de SMS em regiões de alto risco.
    
    Nota: se quiser desativar a proteção contra fraudes, defina Recaptcha_MODE como OFF.
2. Introduza o URL numa nova janela do navegador onde tem sessão iniciada na Google Cloud consola.
Se estiver a usar a Identity Platform na Web ou no Android, registe a sua app a partir da consola do Firebase:
- Para Android, registe cada nome de pacote Android que use a Identity Platform.
- Para a Web, adicione um domínio autorizado para cada domínio que use o reCAPTCHA:
  1. Na Google Cloud consola, aceda à página Identity Platform.
    
    Aceda à Identity Platform
  2. Aceda a Definições > Segurança.
  3. Clique em Adicionar domínio.
  4. Introduza o nome do domínio e clique em Adicionar para guardar o domínio.
  O aprovisionamento da chave do reCAPTCHA pode demorar vários minutos a ser concluído.
Valide a configuração:
- Obtenha os detalhes de configuração do reCAPTCHA:
  
  {replace-your-project} com o seu projectId ou projectNumber. Execute a API GetConfig no painel lateral para obter a configuração do reCAPTCHA.
- Verifique se a defesa por SMS do reCAPTCHA está configurada corretamente:
  1. Se a configuração do reCAPTCHA estiver configurada corretamente, a resposta tem de ter os seguintes campos com os valores especificados:
    - recaptchaKeys: O campo não pode estar vazio e está configurado para, pelo menos, uma destas plataformas: iOS, Web ou Android.
    - useSmsTollFraudProtection: o valor deste campo tem de ser definido como true.
    - phoneEnforcementState: o valor tem de ser definido como ENFORCE ou AUDIT.
    - tollFraudManagedRules: neste campo, tem de configurar startScore com o limite escolhido, que tem de ser um valor entre 0 e 0.9.
    Caso contrário, configure novamente a defesa por SMS do reCAPTCHA.
    
    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
    }
  }
  ```
```
Certifique-se de que as versões do SDK estão corretas.
Web
Atualize para a versão mais recente do SDK Web.
- O suporte do reCAPTCHA para autenticação de email e palavra-passe em apps Web está disponível nas versões 9.20.0 e posteriores do SDK JavaScript.
- O suporte do reCAPTCHA para autenticação por telefone em apps Web está disponível nas versões 11 e posteriores do SDK de JavaScript.
Depois de integrar o SDK Web com a sua app, o SDK obtém automaticamente a configuração do reCAPTCHA e ativa a proteção para os fornecedores que configurou.
Android
1. Atualize para a versão mais recente do SDK do Android. O suporte do reCAPTCHA para autenticação por email e palavra-passe e autenticação por telefone em apps Android está disponível na versão 23.1.0 e posterior do SDK do Android.
  
  Além disso, o suporte do reCAPTCHA requer o nível da API 23 (Marshmallow) ou superior e o Android 6 ou superior.
  
  Depois de integrar o SDK Android na sua app, o SDK obtém automaticamente a configuração do reCAPTCHA e aplica os limites definidos para os fornecedores que configurou.
2. Adicione a seguinte regra de compilação à secção de dependências do ficheiro build.gradle ao nível da app:
  implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
  Certifique-se de que usa a versão 18.5.1 ou posterior do SDK do reCAPTCHA.
iOS
1. Atualize para a versão 11.6.0 ou posterior do SDK para iOS.
Depois de integrar o SDK iOS na sua app, o SDK obtém automaticamente a configuração do reCAPTCHA e aplica os limites definidos para os fornecedores que configurou.
1. Para integrar o SDK do reCAPTCHA para iOS na sua app, consulte o artigo Prepare o seu ambiente iOS.
2. Para verificar se -ObjC está listado nas flags do linker, navegue para Target > Build Settings > All > Linking e verifique se Other Linker Flags apresenta -ObjC.

Monitorize as métricas do reCAPTCHA para a defesa por SMS do reCAPTCHA

Monitorize as métricas do reCAPTCHA que o seu projeto emite para verificar se os fluxos de autenticação baseados em SMS estão protegidos. Por exemplo, estas métricas podem ajudar a determinar se configurou corretamente a integração da Identity Platform com a API reCAPTCHA Enterprise. Também podem ajudar a refinar o limite da pontuação para o tráfego de utilizadores.

Verifique se a funcionalidade de defesa por SMS do reCAPTCHA está a funcionar consultando as seguintes métricas que o seu projeto emite para o Cloud Monitoring:

Para mais informações, consulte o artigo Monitorize as métricas do reCAPTCHA.

Aplique a defesa por SMS do reCAPTCHA

Depois de verificar que a sua app está a receber tráfego de utilizadores aceitável, ative o modo ENFORCE reCAPTCHA para bloquear ativamente pedidos fraudulentos e ajudar a proteger os utilizadores.

Para ativar o modo ENFORCE para fluxos de autenticação baseados em SMS num projeto ou inquilino, use o Google APIs Explorer para atualizar a configuração do projeto introduzindo o seguinte URL HTTP numa nova janela do navegador onde tem sessão iniciada na consola: 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.

Use a defesa por SMS do reCAPTCHA com proteção contra bots

É possível usar a defesa por SMS do reCAPTCHA em simultâneo com a proteção contra bots. Para configurações que usam ambas as funcionalidades de proteção, considere o seguinte:

Quando define o estado de aplicação da autenticação por telemóvel como AUDIT, o Identity Platform transmite um pedido quando satisfaz, pelo menos, uma das avaliações. Recomendamos que monitorize as métricas do reCAPTCHA para verificar se a defesa por SMS do reCAPTCHA e a proteção contra bots estão configuradas com definições de pontuação razoáveis.
Quando define o estado de aplicação da autenticação por telefone como ENFORCE, o Identity Platform só passa um pedido quando satisfaz ambas as avaliações e o pedido falha sem recorrer a outro método de validação.

Para ativar ambas as funcionalidades, 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 quer definir para a aplicação da autenticação telefónica do reCAPTCHA. Os valores válidos são OFF, AUDIT e ENFORCE. Quando ativa a defesa por SMS do reCAPTCHA pela primeira vez, recomendamos que defina este parâmetro como AUDIT e garanta que os seus fluxos de autenticação estão protegidos antes de o definir como ENFORCE. Para mais informações sobre o funcionamento dos modos, consulte os modos de aplicação da autenticação telefónica do reCAPTCHA.

Desative a defesa por SMS do reCAPTCHA enquanto usa a proteção contra bots

Se estiver a usar a defesa por SMS do reCAPTCHA e a proteção contra bots em simultâneo, 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 definiu anteriormente para a aplicação da autenticação por telefone do reCAPTCHA. Este valor deve ser AUDIT ou ENFORCE. Para mais informações sobre o funcionamento dos modos, consulte os modos de aplicação da autenticação telefónica do reCAPTCHA.

Desative a defesa por SMS do reCAPTCHA

Para desativar a defesa por SMS do reCAPTCHA, use o Google APIs Explorer para atualizar a configuração do projeto introduzindo o seguinte URL HTTP numa nova janela do navegador onde tem sessão iniciada na Google Cloud consola:


   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 a defesa por SMS do reCAPTCHA enquanto usa a proteção contra bots, consulte o artigo Desative a defesa por SMS do reCAPTCHA enquanto usa a proteção contra bots.

O que se segue?

Saiba mais acerca da funcionalidade de defesa por SMS do reCAPTCHA.