Integre o Identity Platform com a API reCAPTCHA Enterprise

Este documento mostra como usar a integração da Identity Platform com a API reCAPTCHA Enterprise para melhorar a segurança dos seus utilizadores. Esta funcionalidade torna a sua app mais resiliente contra spam, abuso e outras atividades fraudulentas.

A integração cria uma avaliação do reCAPTCHA Enterprise em seu nome para validar os pedidos dos utilizadores. Para informações de preços, consulte os preços do reCAPTCHA.

Vista geral

Quando configura a integração da Identity Platform com a API reCAPTCHA Enterprise, ativa a funcionalidade de proteção predefinida do reCAPTCHA: a proteção contra bots do reCAPTCHA. Com a proteção contra bots, a Identity Platform aprova chaves do reCAPTCHA baseadas em pontuação no seu projeto em seu nome. Quando um utilizador acede à sua app ou site através de qualquer uma das seguintes operações, o SDK do cliente carrega o reCAPTCHA quando o fornecedor correspondente está ativado.

Fornecedor Operação Método
passwordProvider Início de sessão com email e palavra-passe signInWithPassword
Inscrição com email e palavra-passe signUpPassword
Início de sessão com link por email getOobCode
Redefinição de palavra-passe getOobCode
phoneProvider 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 para MFA mfaSmsSignIn

Em seguida, o reCAPTCHA fornece à Identity Platform pontuações que avaliam o risco do pedido com base na sua configuração e tolerância ao risco.

Para mais informações, consulte o artigo Vista geral do reCAPTCHA.

Antes de começar

Com base no tipo de fluxo de autenticação que quer proteger com o reCAPTCHA, certifique-se de que configurou o seguinte:

Criar uma conta de serviço

A integração da Identity Platform com a API reCAPTCHA Enterprise requer uma conta de serviço da Identity Platform para cada projeto que vai usar o reCAPTCHA. Isto permite que a Identity Platform gere as chaves do reCAPTCHA em seu nome. Se já tiver criado uma conta de serviço, conceda-lhe acesso ao reCAPTCHA.

Se ainda não tiver criado uma conta de serviço ou tiver projetos adicionais que queira proteger com o reCAPTCHA, faça o seguinte:

  1. Use a CLI Google Cloud para criar uma conta de serviço:

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

    Substitua PROJECT_ID pelo ID do projeto.

  2. Conceda à conta de serviço acesso ao reCAPTCHA:

    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

Modos de proteção contra bots do reCAPTCHA

A proteção contra bots do reCAPTCHA tem dois modos que ajudam a proteger os utilizadores: auditoria e aplicação. Estes modos diferem no comportamento com base no fornecedor de identidade.

Fornecedor de email e palavra-passe

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 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 proteção contra bots 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 proteção contra bots falhar, o modo de auditoria valida a sua app em relação à 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 proteção contra bots 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, a 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 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.

Configure a integração da Identity Platform com a API reCAPTCHA Enterprise

Para configurar a integração da Identity Platform com a API reCAPTCHA Enterprise, realiza as seguintes tarefas:

  • Use o SDK de administração para definir o estado de aplicação do reCAPTCHA e ativar a proteção contra bots.
  • Configure o SDK do cliente para a plataforma da sua app.

Recomendamos que ative primeiro a aplicação do reCAPTCHA no modo de auditoria e monitorize as métricas do reCAPTCHA que o seu projeto emite para garantir que os fluxos de autenticação estão protegidos adequadamente. Isto é feito para não interromper o tráfego de utilizadores enquanto audita a respetiva utilização do reCAPTCHA. Depois de verificar se os fluxos de autenticação estão protegidos, defina a proteção contra bots como ENFORCE.

Ative a proteção contra bots do reCAPTCHA

Fornecedor de email e palavra-passe

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 rejeitar qualquer pedido com uma pontuação 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:

    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 rejeitar qualquer pedido com uma pontuação 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:

    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.

Configure o SDK do cliente

Configure o SDK do cliente de acordo com a plataforma da sua app.

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

  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
}];

Monitorize as métricas do reCAPTCHA para proteção contra bots

Antes de definir a aplicação do reCAPTCHA para o modo de aplicação, recomendamos que use o modo de auditoria e monitorize as métricas do reCAPTCHA que o seu projeto emite para garantir que os fluxos de autenticação 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 ajustar o limite da pontuação para o tráfego de utilizadores. Se o aprovisionamento da chave do reCAPTCHA falhar ou se as contas de serviço necessárias não forem criadas, as tentativas de autenticação do reCAPTCHA continuam a ter êxito normalmente.

Certifique-se de que a autenticação reCAPTCHA está a funcionar examinando 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 proteção contra bots do reCAPTCHA

Depois de verificar que a sua app está a receber tráfego de utilizadores aceitável, pode ativar a aplicação do reCAPTCHA para proteger os seus utilizadores. Certifique-se de que não interrompe os utilizadores existentes, incluindo os que podem estar a usar uma versão mais antiga da sua app.

Fornecedor de email e palavra-passe

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 = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    }]
  }
};

Fornecedor de serviços telefónicos

Para ativar a aplicação do reCAPTCHA para fluxos de autenticação baseados em SMS num projeto ou num inquilino, use o SDK de administrador para executar o seguinte:

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

Desative a proteção contra bots do reCAPTCHA

Fornecedor de email e palavra-passe

Para desativar a proteção contra bots para fluxos de autenticação por email e palavra-passe, use o SDK de administrador para executar o seguinte comando:

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

Fornecedor de serviços telefónicos

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

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

Substitua veredictos do reCAPTCHA com funções do Cloud Run

Além de configurar os limites de pontuação, pode substituir um veredicto do reCAPTCHA para um determinado token através de funções de bloqueio para permitir ou bloquear fluxos com base em fatores personalizados. Isto é útil nos casos em que uma pontuação do reCAPTCHA para um determinado início de sessão do utilizador pode ser baixa, mas o utilizador é fidedigno ou foi validado por outros meios e, por isso, tem autorização para concluir o início de sessão.

O exemplo seguinte mostra como substituir um veredicto do reCAPTCHA através de funções de bloqueio:

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

O que se segue?