Ativar o reCAPTCHA Enterprise
Este documento mostra como usar a integração do Identity Platform com o reCAPTCHA para aumentar a segurança dos usuários. Esse recurso torna seu app mais resiliente contra spam, abuso e outras atividades fraudulentas.
A integração do Identity Platform com o reCAPTCHA cria uma teste reCAPTCHA em seu nome para validar as solicitações dos usuários. Para informações sobre preços, consulte os preços do reCAPTCHA.
Visão geral
Quando você configura a integração do Identity Platform com o reCAPTCHA, o Identity Platform provisiona as chaves de site reCAPTCHA com base em pontuação no projeto em seu nome. Quando um usuário acessa seu app ou site usando uma das seguintes operações: o SDK do cliente carrega o reCAPTCHA:
Operação | Método |
---|---|
Login com e-mail e senha | signInWithPassword |
Inscrição com e-mail e senha | signUpPassword |
Login com link de e-mail | getOobCode |
Redefinição de senha | getOobCode |
O reCAPTCHA fornece sinais de risco ao Identity Platform que avaliam o risco da solicitação com base na sua configuração e tolerância a riscos.
Para mais informações, consulte Visão geral do reCAPTCHA Enterprise.
Antes de começar
Configure o login de e-mail para os usuários.
Crie uma conta de serviço
Antes de ativar o reCAPTCHA, é preciso criar uma conta de serviço para cada projeto que vai usar o reCAPTCHA e conceder a cada conta de serviço acesso ao reCAPTCHA. Isso permite que o Identity Platform gerencie as chaves reCAPTCHA em seu nome.
Para criar uma conta de serviço, 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_ID
Substitua
PROJECT_ID
pelo 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.iam.gserviceaccount.com \ --role=roles/identitytoolkit.serviceAgent
Substitua:
PROJECT_ID
: o ID do projeto;PROJECT_NUMBER
: o número da conta do projeto.
Ativar reCAPTCHA
O reCAPTCHA tem dois modos que ajudam a proteger os usuários:
- Auditoria: quando ativado, o Identity Platform cria um ou mais reCAPTCHA chaves do 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.
- Aplicação: quando ativada, o Identity Platform cria um ou mais reCAPTCHA chaves no 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 o Suporte ao reCAPTCHA.
Para ativar o reCAPTCHA, faça o seguinte:
- Ative a API reCAPTCHA no seu projeto se ainda não tiver feito isso.
Ativar a integração do Identity Platform com o reCAPTCHA para um projeto usando o SDK Admin. reCAPTCHA o suporte está disponível para as versões 11.7.0 e posteriores do SDK Admin para Node.js.
Exemplo:
// Get project config const getProjectConfig = () => { getAuth().projectConfigManager().getProjectConfig() .then((response) => { console.log('Project reCAPTCHA config: ', response.recaptchaConfig); }).catch((error) => { console.log('Error getting project config:', error); }); } // Update project config with reCAPTCHA config const updateConfigRequest = { recaptchaConfig: { emailPasswordEnforcementState: 'AUDIT', managedRules: [{ endScore: 0.3, 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); }); }
Ativar a integração do Identity Platform com o reCAPTCHA para um locatário usando o SDK Admin. Exemplo:
// Update tenant with reCAPTCHA config const updateTenantRequest = { recaptchaConfig: { emailPasswordEnforcementState: 'AUDIT', managedRules: [{ endScore: 0.3, action: 'BLOCK' }] } }; const updateTenantWithRecaptchaConfig = () => { getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest) .then((response) => { console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig); }).catch((error) => { console.log('Error updating the tenant:', error); }); }
Substitua:
TENANT_ID
: o ID do locatário.
Se você usa o Identity Platform em plataformas Apple ou Android, faça o registro seu app no Console do Firebase:
- Para plataformas da Apple, 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 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 do domínio e clique em Adicionar para salvar o domínio.
O provisionamento de chaves do site pode levar vários minutos para ser concluído. Para garantir que seus fluxos estão sendo protegidos, verifique as métricas.
Configurar o SDK do cliente
Configure o SDK do cliente de acordo com a plataforma do seu app.
Web
Atualize para a versão mais recente do SDK da Web. O suporte ao reCAPTCHA está disponível nas versões 9.20.0 e mais recentes do SDK para JavaScript. Depois de integrar o SDK da Web ao seu app, ele vai buscar automaticamente sua configuração reCAPTCHA e protege os provedores configurados.
Para reduzir o número de chamadas de rede feitas pelo SDK e melhorar coleta de indicadores reCAPTCHA, recomendamos configurá-la explicitamente da seguinte forma:
import { initializeRecaptchaConfig } from '@firebase/auth'; // Initialize Firebase Auth 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 o SDK do Android versão 31.5.0 ou mais recente. O suporte ao reCAPTCHA exige o nível 19 da API (KitKat) e o Android 4.4 ou versões mais recentes. Depois de integrar o SDK do Android ao seu app, ele vai buscar automaticamente sua configuração reCAPTCHA e protege os provedores configurados.
Adicione a seguinte regra de build à seção de dependências do nível do app Arquivo
build.gradle
:implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
Use o SDK reCAPTCHA versão 18.4.0 ou mais recente.
Para reduzir o número de chamadas de rede feitas pelo SDK e tornar o reCAPTCHA a coleta de indicadores for mais eficaz, recomendamos configurá-la explicitamente da seguinte maneira:
- O Kotlin:
// Initialize Firebase Auth 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 Auth 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 o SDK para iOS versão 10.14.0 ou mais recente. Depois de integrar o SDK do iOS ao seu aplicativo, ele busca automaticamente sua configuração reCAPTCHA e protege os provedores configurados.
Para integrar o SDK reCAPTCHA para iOS ao seu app, consulte Preparar o ambiente.
Verifique se
-ObjC
está listado nas sinalizações do vinculador. Acesse Target > Configurações do build > Todos > Vinculando e verificando seOther Linker Flags
mostra-ObjC
.Para reduzir o número de chamadas de rede feitas pelo SDK e tornar o reCAPTCHA a coleta de indicadores for mais eficaz, recomendamos que você a configure explicitamente, da seguinte maneira:
- Swift:
// Initialize Firebase Auth try await Auth.auth().initializeRecaptchaConfig()
- Objective-C:
// Initialize Firebase Auth [[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) { // Firebase Auth initialization finished }];
Métricas reCAPTCHA
Depois de ativar o reCAPTCHA, monitore as métricas dele que seu projeto emite para garantir que os fluxos de autenticação sejam protegidos. Se o provisionamento de chaves do site reCAPTCHA falhar ou se o serviço necessário não forem criadas, a autenticação reCAPTCHA falhará ao abrir.
Verifique se a autenticação reCAPTCHA está funcionando examinando as seguintes métricas que o projeto emite para o Cloud Monitoring:
identitytoolkit.googleapis.com/recaptcha/verdict_count
rastreia os diferentes vereditos retornados pelo reCAPTCHA. Um veredito será gerado se um token estiver presente. É possível filtrar os seguintes vereditos:
PASSED
: indica que uma determinada solicitação é permitida quando a aplicação está ativada.FAILED_AUDIT
: indica que uma determinada solicitação é negada quando o reCAPTCHA o modo de auditoria está ativado.FAILED_ENFORCE
: indica que uma determinada solicitação é negada quando o reCAPTCHA está ativado.CLIENT_TYPE_MISSING
: indica que uma determinada solicitação tem um cliente ausente. quando a aplicação do reCAPTCHA está ativada. Isso normalmente ocorre se uma solicitação foi enviada usando uma versão desatualizada do SDK do cliente que não tem Suporte ao reCAPTCHA.KEYS_MISSING
: indica que determinada solicitação não pode ser verificada devido ao incapacidade de recuperar ou gerar chaves reCAPTCHA válidas quando A aplicação do reCAPTCHA está ativada.
Para modificar seus intervalos de pontuação com o objetivo de mudar a proporção de vereditos passados para reprovados, consulte Ativar o reCAPTCHA Enterprise.
identitytoolkit.googleapis.com/recaptcha/token_count
Monitora o número e o status dos tokens reCAPTCHA recebidos pelo back-end do Identity Platform. É possível filtrar os seguintes status:
VALID
: indica que o token reCAPTCHA transmitido é válido.EXPIRED
: indica que o token reCAPTCHA transmitido expirou. Um token expirado pode indicar problemas de rede do cliente ou abuso.DUPLICATE
: indica que o token reCAPTCHA transmitido é um duplicar. Um token duplicado pode indicar problemas de rede do cliente ou abuso.INVALID
: indica que o token reCAPTCHA transmitido é inválido. Um token inválido pode indicar abuso.MISSING
: indica que o token reCAPTCHA não existe no a solicitação em questão. Os tokens ausentes podem indicar um app cliente desatualizado.UNCHECKED
: indica que o token reCAPTCHA não foi verificado. devido a vereditosCLIENT_TYPE_MISSING
ouKEYS_MISSING
.
Se o aplicativo for lançado para os usuários, você verá o tráfego com tokens válidos. O número de tokens válidos provavelmente é proporcional ao número de usuários que estão usando seu aplicativo atualizado.
identitytoolkit.googleapis.com/recaptcha/risk_scores
Rastreia a distribuição da pontuação do reCAPTCHA. Isso pode ajudar a definir os intervalos de pontuação ideais para sua configuração.
Use essas métricas para determinar se é possível ativar a aplicação obrigatória. Considere o seguinte antes de ativar a aplicação:
- Se a maioria das solicitações recentes tiver tokens válidos e a proporção de
PASSED
paraFAILED_AUDIT
ouFAILED_ENFORCE
é aceitável para sua empresa ative a aplicação obrigatória. - Se a maioria das solicitações recentes for de clientes desatualizados, considere aguardando que mais usuários atualizem o aplicativo antes de ativar a aplicação obrigatória. Aplicar a integração do Identity Platform com o reCAPTCHA interrompe as versões anteriores do app que não estão integrados ao reCAPTCHA.
Para ver essas métricas, faça o seguinte:
No Console do Google Cloud, acesse a página do Metrics Explorer.
Em Selecionar uma métrica, digite Identity Toolkit Tenant. Se você estiver usando a multilocação, poderá ver as métricas de cada locatário, bem como o projeto pai, deixando
tenant_name
em branco.
Ativar aplicação
Depois de verificar se o app está recebendo tráfego aceitável de usuários, faça o seguinte: ative a aplicação reCAPTCHA para proteger seus usuários. Não interrompa os usuários atuais, incluindo aqueles que utilizam um mais antiga do seu app.
Para ativar a aplicação obrigatória do reCAPTCHA em um projeto ou locatário, faça o seguinte: use o SDK Admin para executar o seguinte:
const enforceRequest = {
recaptchaConfig: {
emailPasswordEnforcementState: 'ENFORCE',
managedRules: [{
endScore: 0.3,
action: 'BLOCK'
}]
}
};
Desativar o reCAPTCHA
Para desativar o reCAPTCHA, use o SDK Admin para executar o seguinte:
const disableRequest = {
recaptchaConfig: {
emailPasswordEnforcementState: 'OFF',
}
};
Como substituir vereditos do reCAPTCHA com funções do Cloud Run
Além de configurar limites de pontuação, é possível modificar uma veredito do reCAPTCHA para um determinado token usando uma função de bloqueio das funções personalizadas do Cloud Run. Isso é útil nos casos em que uma pontuação reCAPTCHA para um determinado usuário o login pode estar baixo, mas o usuário é confiável ou foi verificado por meio de outro significa e, portanto, tem permissão para concluir o login.
Para saber mais sobre como configurar funções de bloqueio com o reCAPTCHA, consulte Estender o Firebase Authentication com o bloqueio do Cloud Functions.
Solução de problemas
Os usuários não conseguem fazer login, se inscrever ou redefinir a senha
Talvez os usuários estejam usando uma versão desatualizada do app. Se você não forneceu uma versão atualizada do seu app que use o SDK do cliente, desative o modo de aplicação imediatamente. Caso contrário, peça para os usuários atualizarem o app.
Os usuários também podem ser bloqueados com base na sua configuração atual. Tente o seguinte:
- Ajuste-a e considere uma configuração mais abrangente. Pontuações da chave reCAPTCHA.
- Peça para o usuário tentar usar outro dispositivo, navegador ou rede.
- Reverta para o modo de auditoria e monitore as métricas antes de reativar o modo de aplicação.