Integrar o Identity Platform à API reCAPTCHA Enterprise
Neste documento, mostramos como usar a integração do Identity Platform com a API reCAPTCHA Enterprise para aumentar a segurança dos usuários. Esse recurso torna o 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 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: a proteção contra bots do reCAPTCHA. 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 a seguir, 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 com e-mail e senha | signUpPassword |
|
| Login por 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 para MFA | mfaSmsEnrollment |
|
| Login com número de telefone de MFA | mfaSmsSignIn |
Em seguida, o reCAPTCHA fornece ao Identity Platform pontuações que avaliam o risco da solicitação com base na sua configuração e tolerância ao 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:
- Para fluxos de autenticação de e-mail/senha, verifique se você configurou o login por e-mail para os usuários.
Para fluxos de autenticação baseados em SMS, verifique se você se integrou a pelo menos um dos seguintes:
- Login por smartphone para usuários.
- Autenticação multifator para seu app da Web, Android ou iOS.
Criar uma conta de serviço
A integração do Identity Platform com a API reCAPTCHA Enterprise requer uma conta de serviço do Identity Platform para cada projeto que usará o reCAPTCHA. Isso permite que o 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:
Use a Google Cloud CLI para criar uma conta de serviço:
gcloud beta services identity create \ --service=identitytoolkit.googleapis.com \ --project=PROJECT_IDSubstitua
PROJECT_IDpelo ID do projeto.Conceda à conta de serviço acesso ao reCAPTCHA:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit. \ --role=roles/identitytoolkit.serviceAgentSubstitua:
PROJECT_ID: o ID do projeto;PROJECT_NUMBER: o número da conta do projeto
Comportamento da proteção contra bots do reCAPTCHA por provedor
O comportamento da proteção contra bots do reCAPTCHA depende do provedor de identidade que você configurar:
Provedor de e-mail/senha
Para fluxos de autenticação de e-mail e senha, a proteção contra bots do reCAPTCHA oferece dois modos: auditoria e aplicação.
Modo de auditoria
Quando você define a aplicação de e-mail/senha para o 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 restrito
Quando você define a aplicação de e-mail/senha para o modo restrito, 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 do reCAPTCHA são rejeitadas. Só ative a aplicação depois de migrar todos os clientes para um SDK com suporte ao reCAPTCHA.
Operadora de telefonia
Quando você ativa a proteção contra bots para fluxos de autenticação por telefone
definindo phoneEnforcementState como ENFORCE e useSmsBotScore como
true, 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 proteção contra bots, um código de verificação por SMS será enviado. Se a solicitação de um usuário for reprovada na
avaliação de proteção contra bots, o Identity Platform vai bloquear a solicitação e
não vai enviar uma mensagem SMS com um código de verificação.
A verificação de fallback não é necessária quando a proteção contra bots está ativada para fluxos de autenticação por telefone, e você não precisa configurar nenhum outro método de verificação para seu app. No entanto, recomendamos configurar o verificador reCAPTCHA para apps da Web para garantir que o reCAPTCHA v2 esteja disponível se você decidir desativar a proteção contra bots.
Configurar a integração do Identity Platform com a API reCAPTCHA Enterprise
Para configurar a integração do 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.
Para fluxos de autenticação de e-mail e senha, recomendamos que você primeiro ative
a aplicação do reCAPTCHA no modo de auditoria e
monitore as métricas do reCAPTCHA emitidas pelo seu projeto
para evitar a interrupção do tráfego do usuário enquanto verifica se os fluxos de autenticação estão
protegidos. Depois de verificar se os fluxos de autenticação estão
protegidos, defina a proteção contra bots como ENFORCE. Para fluxos de autenticação por telefone, ative a proteção contra bots definindo phoneEnforcementState como ENFORCE e useSmsBotScore como true e monitore as métricas do reCAPTCHA para ajustar os limites de pontuação.
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 e senha, faça o seguinte:
Ative a API reCAPTCHA Enterprise no seu projeto, caso ainda não tenha feito isso.
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 de e-mail/senha do reCAPTCHA. Os valores válidos sãoOFF,AUDITeENFORCE. Para ativar a proteção contra bots, esse parâmetro precisa ser definido comoAUDITouENFORCE. Ao ativar a proteção contra bots pela primeira vez, recomendamos definir esse parâmetro comoAUDITe garantir que os fluxos de autenticação estejam protegidos antes de definir comoENFORCE. Para mais informações sobre como os modos funcionam, consulte Comportamento da proteção contra bots do reCAPTCHA por provedor.END_SCORE: a menor pontuação de avaliação de proteção contra bots que uma solicitação pode ter antes de falhar. É possível definir essa pontuação entre0.0e1.0. Por exemplo, se você definir um limite de0.6, o reCAPTCHA vai falhar em qualquer solicitação com0.5ou menos. Portanto, quanto maior a pontuação definida, 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.
Se você usa o Identity Platform no iOS ou no Android, é necessário registrar o app no console do Firebase:
- Para iOS, registre cada ID do pacote que usa o Identity Platform.
- No 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:
No console do Google Cloud , acesse a página do Identity Platform.
Acesse Configurações > Segurança.
Clique em Adicionar domínio.
Digite o nome de domínio e clique em Adicionar para salvá-lo.
O provisionamento da chave reCAPTCHA pode levar vários minutos para ser concluído.
Se você tiver definido a aplicação como modo de auditoria, recomendamos monitorar as métricas do reCAPTCHA para proteção contra bots para garantir que seus fluxos estejam protegidos.
Operadora de telefonia
Para ativar a proteção contra bots do reCAPTCHA para fluxos de autenticação baseados em SMS, faça o seguinte:
Ative a API reCAPTCHA Enterprise no seu projeto, caso ainda não tenha feito isso.
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', managedRules: [{ endScore: END_SCORE, action: 'BLOCK' }], useSmsBotScore: true, } }; let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);Substitua
END_SCOREpela menor pontuação de avaliação de proteção contra bots que uma solicitação pode ter antes de falhar. É possível definir essa pontuação entre0.0e1.0. Por exemplo, se você definir um limite de0.6, o reCAPTCHA vai falhar em qualquer solicitação com0.5ou menos. Portanto, quanto maior a pontuação, mais rígidas serão as regras.Definir
phoneEnforcementStatecomoENFORCEeuseSmsBotScorecomotrueativa a aplicação da proteção contra bots para fluxos de autenticação baseados em SMS. Para mais informações sobre como funciona a aplicação do provedor de telefonia, consulte Comportamento da proteção contra bots do reCAPTCHA por provedor.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.
Se você estiver usando o Identity Platform no iOS ou Android, registre seu app no console do Firebase:
- Para iOS, registre cada ID do pacote que usa o Identity Platform.
- No 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:
No console do Google Cloud , acesse a página do Identity Platform.
Acesse Configurações > Segurança.
Clique em Adicionar domínio.
Digite o nome de domínio e clique em Adicionar para salvá-lo.
O provisionamento da chave reCAPTCHA pode levar vários minutos para ser concluído.
Monitore as métricas do reCAPTCHA para proteção contra bots para garantir que seus fluxos estejam protegidos.
Configurar o SDK do cliente
Configure o SDK do cliente de acordo com a plataforma do app.
Web
Atualize para a versão mais recente do SDK da Web.
- O suporte do reCAPTCHA para autenticação de 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 app, ele busca automaticamente sua configuração do reCAPTCHA e ativa a proteção para os provedores que você configurou.
Se necessário, é possível 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
Atualize para a versão mais recente do SDK do Android. O suporte do reCAPTCHA para autenticação de e-mail e senha e autenticação por telefone em apps Android está disponível na versão 23.1.0 e mais recentes do SDK do Android.
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 app, ele busca automaticamente sua configuração do reCAPTCHA e ativa a proteção para os provedores que você configurou.
Adicione a seguinte regra de build à seção de dependências do arquivo
build.gradleno 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.
Se necessário, é possível 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
Atualize para a versão 11.6.0 ou mais recente do SDK para iOS. Depois de integrar o SDK para iOS ao app, ele busca automaticamente sua configuração do reCAPTCHA e ativa a proteção para os provedores que você configurou.
Para integrar o SDK do reCAPTCHA para iOS ao seu app, consulte Preparar o ambiente.
Verifique se
-ObjCestá listado nas flags do vinculador. Acesse Target > Build Settings > All > Linking e verifique seOther Linker Flagsmostra-ObjC.Se necessário, é possível 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
Monitore as métricas do reCAPTCHA emitidas pelo projeto para garantir que os fluxos de autenticação estejam protegidos. Para fluxos de autenticação de senha de e-mail, recomendamos monitorar as métricas no modo de auditoria antes de definir a aplicação para o modo restrito. Por exemplo, essas métricas podem ajudar a determinar se você configurou corretamente a integração do Identity Platform com a API reCAPTCHA Enterprise. Eles também podem ajudar você a ajustar o limite de pontuação para o tráfego de usuários. Se o provisionamento 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 ainda serão bem-sucedidas normalmente.
Para garantir que a autenticação do reCAPTCHA esteja funcionando, examine as seguintes métricas que seu projeto emite para o Cloud Monitoring:
identitytoolkit.googleapis.com/recaptcha/verdict_count: rastreia os diferentes vereditos retornados pelo reCAPTCHA.identitytoolkit.googleapis.com/recaptcha/token_count: rastreia o número e o status dos tokens reCAPTCHA recebidos pelo back-end do Identity Platform.identitytoolkit.googleapis.com/recaptcha/risk_scores: rastreia a distribuição da pontuação de proteção contra bots.
Para mais informações, consulte Monitorar métricas do reCAPTCHA.
Aplicar a proteção contra bots do reCAPTCHA para fluxos de e-mail/senha
Para fluxos de autenticação de e-mail e senha que você configurou inicialmente no modo AUDIT, depois de verificar se o app está recebendo tráfego de usuários aceitável, mude emailPasswordEnforcementState para ENFORCE para bloquear solicitações que não passam no teste reCAPTCHA. Não
interrompa os usuários atuais, incluindo aqueles que podem estar usando uma versão
mais antiga do app.
Para ativar a aplicação do reCAPTCHA para fluxos de autenticação de e-mail e senha em um projeto ou locatário, use o SDK Admin para executar o seguinte código:
const enforceRequest = {
recaptchaConfig: {
emailPasswordEnforcementState: 'ENFORCE',
}
};
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 de e-mail e senha, use o SDK Admin para executar o seguinte comando:
const disableRequest = {
recaptchaConfig: {
emailPasswordEnforcementState: 'OFF',
}
};
Operadora de telefonia
Para desativar toda a proteção do reCAPTCHA para smartphones, incluindo 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,
useSmsTollFraudProtection: false
}
};
Se você também estiver usando a defesa de SMS do reCAPTCHA e quiser mantê-la ativada
ao desativar a proteção contra bots, defina useSmsBotScore como false
e deixe phoneEnforcementState definido como ENFORCE:
const disableBotScoreOnlyRequest = {
recaptchaConfig: {
phoneEnforcementState: 'ENFORCE',
useSmsBotScore: false,
useSmsTollFraudProtection: true
}
};
Substituir vereditos do reCAPTCHA com o Cloud Run functions
Além de configurar limites de pontuação, é possível substituir um veredicto do reCAPTCHA para um determinado token usando funções de bloqueio para permitir ou bloquear fluxos com base em fatores personalizados. Isso é útil nos casos em que uma 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.
O exemplo a seguir mostra como substituir um veredito do reCAPTCHA usando 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',
}
});
A seguir
- Ative a defesa de SMS do reCAPTCHA para fluxos de autenticação baseados em SMS.
- Saiba como usar sua própria chave reCAPTCHA.
- Saiba mais sobre como monitorar as métricas do reCAPTCHA.
- Saiba mais sobre o reCAPTCHA.