Integrar o Identity Platform à API reCAPTCHA Enterprise

Este documento mostra como usar a integração do Identity Platform com a API reCAPTCHA Enterprise para melhorar a segurança dos seus usuários. Esse recurso torna seu app mais resistente a spam, abuso e outras atividades fraudulentas.

A integração cria uma avaliação do reCAPTCHA Enterprise em seu nome para validar as solicitações do usuário. Para informações sobre preços, consulte Preços do reCAPTCHA.

Visão geral

Ao configurar a integração do Identity Platform com a API reCAPTCHA Enterprise, você ativa o recurso de proteção padrão do reCAPTCHA, que é a proteção contra bots. Com a proteção contra bots, o Identity Platform provisiona chaves reCAPTCHA baseadas em pontuação no seu projeto em seu nome. Quando um usuário acessa seu app ou site usando qualquer uma das operações abaixo, o SDK do cliente carrega o reCAPTCHA quando o provedor correspondente está ativado.

Provedor Operação Método
passwordProvider Login com e-mail e senha signInWithPassword
Inscrição por e-mail e senha signUpPassword
Login com link de e-mail getOobCode
Redefinição de senha getOobCode
phoneProvider Inscrição ou login com número de telefone sendVerificationCode
Registro de número de telefone do MFA mfaSmsEnrollment
Login com número de telefone de MFA mfaSmsSignIn

O reCAPTCHA fornece ao Identity Platform pontuações que avaliam o risco da solicitação com base na sua configuração e na tolerância de risco.

Para mais informações, consulte Visão geral do reCAPTCHA.

Antes de começar

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

Crie uma conta de serviço

A integração do Identity Platform com a API reCAPTCHA Enterprise exige uma conta de serviço do Identity Platform para cada projeto que vai usar o reCAPTCHA. Isso permite que a Identity Platform gerencie as chaves reCAPTCHA em seu nome. Se você já criou uma conta de serviço, conceda a ela acesso ao reCAPTCHA.

Se você ainda não criou uma conta de serviço ou tem outros projetos que quer proteger com o reCAPTCHA, faça o seguinte:

  1. Use a Google Cloud CLI 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:

    • PROJECT_ID: o ID do projeto;
    • PROJECT_NUMBER: o número da 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 usuários: auditoria e aplicação. O comportamento desses modos varia de acordo com o provedor de identidade.

Provedor de e-mail/senha

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

Modo de auditoria

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

Modo de restrição

Quando você define a aplicação de e-mail e senha para ativar o modo, o Identity Platform cria uma ou mais chaves 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 reCAPTCHA são rejeitadas. Só ative a aplicação depois de migrar todos os clientes para um SDK com suporte ao reCAPTCHA.

Provedor de telefonia

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

Modo de auditoria

Quando você define a aplicação de autenticação de smartphone no modo de auditoria, o Identity Platform usa a proteção de bot reCAPTCHA para a verificação de apps. Se a solicitação do usuário passar pela avaliação de proteção contra bots, o Identity Platform vai enviar uma mensagem SMS com um código de verificação para o smartphone do usuário. Se uma solicitação falhar na avaliação de proteção contra bots e você estiver usando o SDK do cliente, os métodos de verificação alternativos serão acionados para concluir o fluxo de autenticação por telefone. Os métodos alternativos aceitos dependem da plataforma do app.

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

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

Verifique se os métodos de verificação substitutos 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 proteção contra bots 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 proteção contra bots falhar, o modo de auditoria vai verificar seu app em relação à 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 proteção contra bots 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 para o app no dispositivo solicitante com uma notificação push silenciosa. Se o app receber a notificação, o fluxo de autenticação do smartphone vai prosseguir. 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 aplicação da autenticação de smartphone para o modo de aplicação, o Identity Platform usa a proteção contra bots do reCAPTCHA para a verificação de apps. Se a solicitação do usuário passar na avaliação de proteção contra bots, o Identity Platform vai enviar uma mensagem SMS com um código de verificação para o smartphone do usuário. Se a solicitação falhar na avaliação de proteção contra bots, o Identity Platform vai bloquear a solicitação e não enviar uma mensagem SMS com um código de verificação.

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

Configurar a integração do Identity Platform com a API reCAPTCHA Enterprise

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

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

Recomendamos que você ative primeiro a aplicação do reCAPTCHA no modo de auditoria e monitore as métricas do reCAPTCHA que seu projeto emite para garantir que os fluxos de autenticação sejam protegidos adequadamente. Isso é feito para que você não interrompa o tráfego do usuário enquanto audita o uso do reCAPTCHA. Depois de verificar se os fluxos de autenticação estão protegidos, defina a proteção contra bots como ENFORCE.

Ativar a proteção contra bots do reCAPTCHA

Provedor de e-mail/senha

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

  1. Ative a API reCAPTCHA Enterprise no seu projeto, se ainda não tiver feito isso.

  2. Para ativar a proteção contra bots em um projeto, use o SDK Admin. O suporte a 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 de 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ê 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 0.5 ou inferior. Portanto, quanto maior a pontuação, mais rígidas serão as regras.

    Também é possível ativar a proteção contra bots com o mesmo método de configuração para um inquilino 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 no Android, registre seu app no console do Firebase:

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

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

Provedor de serviços de telefonia

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

  1. Ative a API reCAPTCHA Enterprise no seu projeto, se ainda não tiver feito isso.

  2. Para ativar a proteção contra bots em um projeto, use o SDK Admin. O suporte a 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 para 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 0.5 ou inferior. Portanto, quanto maior a pontuação, mais rígidas serão as regras.

    Também é possível 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 no Android, registre seu app no Console do Firebase:

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

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

Configurar o SDK do cliente

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

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

  2. Se necessário, você pode forçar a busca do indicador 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 por telefone em apps Android está disponível na versão 23.1.0 do SDK do Android e mais recentes.

    Além disso, o suporte a 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 app, o SDK vai buscar automaticamente a configuração do reCAPTCHA e ativar 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 o SDK do reCAPTCHA na versão 18.5.1 ou mais recente.

  3. Se necessário, você pode forçar a busca do indicador 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, o SDK vai buscar automaticamente a configuração do reCAPTCHA e ativar a proteção para os provedores configurados.

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

  3. Verifique se -ObjC está listado nas flags do vinculador. Navegue até Target > Build Settings > All > Linking e verifique se Other Linker Flags mostra -ObjC.

  4. Se necessário, você pode forçar a busca do indicador 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
}];

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

Antes de definir a aplicação do reCAPTCHA para ativar o modo, recomendamos usar o modo de auditoria e monitorar as métricas do reCAPTCHA emitido pelo seu projeto para garantir que os fluxos de autenticação estejam protegidos. Por exemplo, essas métricas podem ajudar a determinar se você configurou a integração da Identity Platform com a API reCAPTCHA Enterprise corretamente. Eles também podem ajudar a ajustar o limite de pontuação para o tráfego de usuários. Se o provisionamento da chave reCAPTCHA falhar ou se as contas de serviço necessárias não forem criadas, as tentativas de autenticação do reCAPTCHA ainda vão ser bem-sucedidas.

Verifique se a autenticação reCAPTCHA está funcionando examinando as seguintes métricas que seu projeto emite para o Cloud Monitoring:

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

Aplique a proteção contra bots do reCAPTCHA

Depois de verificar se o app está recebendo tráfego de usuário aceitável, ative a aplicação do reCAPTCHA para proteger seus usuários. Não interrompa os usuários existentes, incluindo aqueles que podem estar usando uma versão mais antiga do app.

Provedor de e-mail/senha

Para ativar a aplicação do reCAPTCHA para 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 de telefonia

Para ativar a aplicação do reCAPTCHA para 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'
    }]
  }
};

Desativar a proteção contra bots do reCAPTCHA

Provedor de e-mail/senha

Para desativar a proteção contra bots para 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 telefonia

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

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

Substituir os vereditos do reCAPTCHA com as funções do Cloud Run

Além de configurar os limites de pontuação, você pode substituir um veredito do reCAPTCHA para um determinado token usando uma função de bloqueio personalizada do Cloud Run Functions. Isso é útil em casos em que a pontuação do reCAPTCHA para um determinado login de usuário pode ser baixa, mas o usuário é confiável ou foi verificado por outros meios e, portanto, tem permissão para concluir o login.

Para saber mais sobre como configurar funções de bloqueio com o reCAPTCHA, consulte Ampliar a Autenticação do Firebase com funções do Cloud de bloqueio.

A seguir