Integre o Identity Platform com a API reCAPTCHA Enterprise

Fornecedor de palavra-passe por email

Os modos de auditoria e aplicação comportam-se da seguinte forma para os fluxos de autenticação de email e palavra-passe.

Modo de auditoria

Quando define a aplicação de palavra-passe de email 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 Identity Platform sem bloquear pedidos. Use as métricas emitidas durante o modo de auditoria para determinar se deve ativar a aplicação do reCAPTCHA.

Modo de aplicação

Quando define a aplicação de palavra-passe de email para o 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 Identity Platform. Os pedidos da API que não incluam um token do reCAPTCHA são rejeitados. Ative a aplicação apenas depois de migrar todos os seus clientes para um SDK com suporte do reCAPTCHA.

Fornecedor de serviços telefónicos

Os modos de auditoria e aplicação comportam-se da seguinte forma para os fluxos de autenticação por telefone.

Modo de auditoria

Quando define a aplicação da autenticação por telefone para o modo de auditoria, o Identity Platform usa a proteção contra bots do reCAPTCHA para a validação de apps. Se o pedido de um utilizador passar na avaliação de fraude de tarifação, é 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.

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 proteção contra bots do reCAPTCHA para a validação de apps. Se o pedido de um utilizador passar na avaliação de fraude de tarifação, é enviado um código de validação por SMS. Se o pedido de um utilizador falhar na avaliação de fraude de custos, 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.

Fornecedor de palavra-passe por email

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

1. Se ainda não o fez, ative a API reCAPTCHA Enterprise no seu projeto.

2. Para ativar a proteção contra bots para um projeto, use o SDK de administrador. O suporte do reCAPTCHA está disponível nas versões 11.7.0 e posteriores do SDK de administrador do Node.js.

   Por 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 o seguinte:

   • ENFORCE_MODE: o modo que quer definir para a aplicação da autenticação por email e palavra-passe do reCAPTCHA. Os valores válidos são OFF, AUDIT e ENFORCE. Para ativar a proteção contra bots, este parâmetro tem de ser definido como AUDIT ou ENFORCE. Quando ativa a proteção contra bots 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 como funcionam os modos, consulte os modos de proteção contra bots do reCAPTCHA.
   • END_SCORE: a pontuação de avaliação de proteção contra bots mais baixa que um pedido pode ter antes de falhar. Pode definir esta pontuação entre 0.0 e 1.0. Por exemplo, se definir um limite de 0.6, o reCAPTCHA vai falhar qualquer pedido com um valor de 0.5 ou inferior. Por conseguinte, quanto mais elevada for a pontuação, mais rigorosas serão as regras.

   Também pode ativar a proteção contra bots com o mesmo método de configuração para um inquilino através do SDK de administrador. Para mais informações sobre como atualizar um inquilino, consulte o artigo Atualize um inquilino.

3. Se usar a Identity Platform no iOS ou Android, tem de registar a sua app na consola do Firebase:

   • Para iOS, registe cada ID do pacote que usa a Identity Platform
   • Para Android, registe cada nome de pacote Android que usa a Identity Platform

   Se estiver a usar a Identity Platform na Web, tem de adicionar um domínio autorizado para cada domínio que use o reCAPTCHA. Para adicionar domínios autorizados, faça o seguinte:

   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.

4. Se tiver definido a aplicação para o modo de auditoria, recomendamos que monitorize as métricas do reCAPTCHA para proteção contra bots para garantir que os seus fluxos estão a ser protegidos.

Fornecedor de serviços telefónicos

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

1. Se ainda não o fez, ative a API reCAPTCHA Enterprise no seu projeto.

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

   Por 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 o seguinte:

   • ENFORCE_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 proteção contra bots para fluxos baseados em SMS, este parâmetro tem de estar definido como AUDIT ou ENFORCE, e useSmsBotScore tem de estar definido como true.

     Quando ativa a proteção contra bots pela primeira vez, recomendamos que defina este parâmetro como AUDIT e se certifique de que os seus fluxos de autenticação estão protegidos antes de o definir como ENFORCE. Para mais informações sobre como funcionam os modos, consulte os modos de proteção contra bots do reCAPTCHA.

   • END_SCORE: a pontuação de avaliação de proteção contra bots mais baixa que um pedido pode ter antes de falhar. Pode definir esta pontuação entre 0.0 e 1.0. Por exemplo, se definir um limite de 0.6, o reCAPTCHA vai falhar qualquer pedido com um valor de 0.5 ou inferior. Por conseguinte, quanto mais elevada for a pontuação, mais rigorosas serão as regras.

   Também pode ativar a proteção contra bots com o mesmo método de configuração para um inquilino através do SDK de administrador. Para mais informações sobre como atualizar um inquilino, consulte o artigo Atualize um inquilino.

3. Se estiver a usar a Identity Platform no iOS ou Android, tem de registar a sua app na consola do Firebase:

   • Para iOS, registe cada ID do pacote que usa a Identity Platform
   • Para Android, registe cada nome de pacote Android que usa a Identity Platform

   Se estiver a usar a Identity Platform na Web, tem de adicionar um domínio autorizado para cada domínio que use o reCAPTCHA. Para adicionar domínios autorizados, faça o seguinte:

   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.

4. Se tiver definido a aplicação para o modo de auditoria, recomendamos que monitorize as métricas do reCAPTCHA para proteção contra bots para garantir que os seus fluxos estão a ser protegidos.

Web

1. Atualize para a versão mais recente do SDK Web.

   • O suporte do reCAPTCHA para autenticação por 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 a autenticação por telefone em apps Web está disponível nas versões 11 e posteriores do SDK 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.

2. Se necessário, pode forçar a obtenção do sinal reCAPTCHA da seguinte forma:

   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 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 ativa a proteção 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.

3. Se necessário, pode forçar a obtenção do sinal reCAPTCHA da seguinte forma:

   • 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 posterior do SDK para iOS. Depois de integrar o SDK iOS com a sua app, o SDK obtém automaticamente a configuração do reCAPTCHA e ativa a proteção para os fornecedores que configurou.

2. Para integrar o SDK do reCAPTCHA para iOS na sua app, consulte o artigo Prepare o seu ambiente.

3. Certifique-se de que -ObjC está listado nas suas flags do linker. Navegue para Segmento > Definições de criação > Tudo > Associação e verifique se Other Linker Flags apresenta -ObjC.

4. Se necessário, pode forçar a obtenção do sinal reCAPTCHA da seguinte forma:

   • Swift:

   // Initialize Firebase Authentication
   try await Auth.auth().initializeRecaptchaConfig()
   

   • Objective-C:

   // Initialize Firebase Authentication
   [[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
     // Firebase Authentication initialization finished
   }];
   

Fornecedor de palavra-passe de email

Para ativar a aplicação do reCAPTCHA para fluxos de autenticação por email e palavra-passe num projeto ou inquilino, use o SDK de administrador para executar o seguinte:

const enforceRequest =