Integrar o Identity Platform à API reCAPTCHA Enterprise

Provedor de e-mail/senha

Os modos de auditoria e imposição se comportam da seguinte maneira para fluxos de autenticação de e-mail e senha.

Modo de auditoria

Quando você define a aplicação de senha de e-mail para o modo de auditoria, o Identity Platform cria uma ou mais chaves do 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ê deve ativar a aplicação do reCAPTCHA.

Modo de restrição

Quando você define a aplicação de senha por e-mail como "Modo de aplicação", o Identity Platform cria uma ou mais chaves do 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.

Provedor de serviços telefônicos

Os modos de auditoria e restrição funcionam da seguinte maneira para fluxos de autenticação por smartphone.

Modo de auditoria

Quando você define a restrição da autenticação por smartphone como modo de auditoria, 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 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.

Modo de restrição

Quando você define a restrição da autenticação por telefone como "modo restrito", o Identity Platform usa a proteção contra bots do reCAPTCHA para a 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.

Provedor de e-mail/senha

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

1. Se você ainda não tiver feito isso, ative a API reCAPTCHA Enterprise no seu projeto.

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 por e-mail e 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. Quando você ativa a proteção contra bots 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 proteção contra bots do reCAPTCHA.
   • END_SCORE: a menor pontuação de avaliação de proteção contra bots que uma solicitação pode ter antes de falhar. Você pode 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 um 0.5 ou menos. Portanto, quanto maior a pontuação, mais rígidas serão as regras.

   Você também pode 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 Android, registre o app no console do Firebase:

   • Para iOS, registre cada ID do pacote que usa o Identity Platform.
   • Para Android, registre cada nome de pacote Android que usa o Identity Platform.

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

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

Provedor de serviços telefônicos

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

1. Se você ainda não tiver feito isso, ative a API reCAPTCHA Enterprise no seu projeto.

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_MODE',
       managedRules: [{ endScore: END_SCORE, action: 'BLOCK' }],
       useSmsBotScore: 'true',
     }
   }
   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 bots em fluxos baseados em SMS, esse parâmetro precisa ser definido como AUDIT ou ENFORCE, e useSmsBotScore precisa ser definido como true.

     Ao ativar a proteção contra bots 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 proteção contra bots do reCAPTCHA.

   • END_SCORE: a menor pontuação de avaliação de proteção contra bots que uma solicitação pode ter antes de falhar. Você pode 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 um 0.5 ou menos. Portanto, quanto maior a pontuação, mais rígidas serão as regras.

   Você também pode 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 o app no Console do Firebase:

   • Para iOS, registre cada ID do pacote que usa o Identity Platform.
   • Para Android, registre cada nome de pacote Android que usa o Identity Platform.

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

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

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

2. Se necessário, force a busca do indicador do 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 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 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, force a busca do indicador do 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 do iOS ao seu app, ele busca automaticamente a 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 seu ambiente.

3. Verifique se -ObjC está listado nos seus sinalizadores do vinculador. Navegue até Destino > Configurações de build > Todos > Vinculação e verifique se Other Linker Flags mostra -ObjC.

4. Se necessário, force a busca do indicador do 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
   }];
   

Provedor de e-mail/senha

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

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

Provedor de serviços telefônicos

Para ativar a aplicação do reCAPTCHA em fluxos de autenticação por SMS em um projeto ou locatário, use o SDK Admin para executar o seguinte:

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

Provedor de e-mail/senha

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

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

Provedor de serviços telefônicos

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

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

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',
    }
  });