Neste documento, mostramos como usar a defesa de conta do reCAPTCHA Enterprise para detectar e evitar atividades fraudulentas relacionadas à conta em sites.
O reCAPTCHA Enterprise ajuda a proteger ações essenciais, como login e finalização de compra. No entanto, há muitas formas sutis de abuso da conta que podem ser detectadas observando o comportamento de um usuário específico em um site durante um período. O defensor da conta do reCAPTCHA Enterprise ajuda a identificar esses tipos de abuso sutil criando um modelo específico para seu site a fim de detectar uma tendência de comportamento suspeito ou uma mudança na atividade. Ao usar o modelo específico do site, o defensor da conta do reCAPTCHA Enterprise ajuda a detectar o seguinte:
- Atividades suspeitas
- Contas com comportamentos parecidos
- Solicitações provenientes de dispositivos marcados como confiáveis para usuários específicos
Com base na análise do defensor da conta do reCAPTCHA Enterprise e no modelo específico do site, é possível realizar as seguintes ações:
- Restringir ou desativar contas fraudulentas.
- Impeça tentativas de invasão de conta.
- Reduza as invasões de contas.
- Conceda acesso somente às solicitações provenientes de contas de usuários legítimos.
- Reduza o atrito para os usuários que fazem login em um dispositivo confiável.
Antes de começar
Configurar suas páginas da Web para a proteção da conta do reCAPTCHA Enterprise
O defensor da conta do reCAPTCHA Enterprise requer uma compreensão abrangente das atividades da conta para permitir uma detecção eficaz. Para começar a alimentar atividades relacionadas à conta no defensor da conta do reCAPTCHA Enterprise e criar e melhorar o modelo específico do site, faça o seguinte:
- Ative a coleta de dados de telemetria horizontal.
- Gere relatórios sobre ações críticas do usuário.
- Avalie eventos críticos do usuário.
- Anote os eventos do usuário para ajustar o modelo específico do site.
Ativar a coleta de dados de telemetria horizontal
O defensor da conta do reCAPTCHA Enterprise requer uma visualização completa das ações do usuário, como se o usuário está conectado ou se está levando a isso. Para ativar a coleta passiva de dados de telemetria horizontal pelo defensor da conta do reCAPTCHA Enterprise, carregue o script JavaScript do reCAPTCHA Enterprise com a chave do site baseada em pontuação que você criou em segundo plano de todas as páginas da Web que fazem parte do fluxo de trabalho do usuário.
Confira no exemplo a seguir como carregar o script JavaScript do reCAPTCHA Enterprise em uma página da Web.
<head> <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script> .... </head>
Gerar relatórios sobre ações críticas do usuário
Para detectar padrões de atividade suspeita e entender melhor os padrões comuns de atividade no site, o defensor da conta do reCAPTCHA Enterprise precisa das informações sobre as ações críticas do usuário. Portanto, informe ações críticas do usuário nas páginas da Web chamando grecaptcha.enterprise.execute() nessas ações críticas do usuário.
Recomendamos informar todas as ações críticas do usuário, porque isso ajuda na coleta adicional de indicadores. Para cada ação do usuário que você queira denunciar, substitua o valor do parâmetro action
de grecaptcha.enterprise.execute()
por um nome que descreva a ação do usuário.
A tabela a seguir lista os nomes das ações que podem ser usadas ao informar as ações críticas do usuário.
Nome da ação | Evento iniciado pelo usuário ou ação do usuário |
---|---|
LOGIN |
Faça login no site. |
REGISTRATION |
Registro no site. |
SECURITY_QUESTION_CHANGE |
Solicitação para alterar a pergunta de segurança. |
PASSWORD_RESET |
Solicitação para redefinir a senha. |
PHONE_NUMBER_UPDATE |
Solicitação para atualizar o número de telefone. |
EMAIL_UPDATE |
Solicitação para atualizar o endereço de e-mail. |
ACCOUNT_UPDATE |
Solicitação para atualizar informações relacionadas à conta, como detalhes de contato. |
TRIGGER_MFA |
Uma ação que aciona um desafio de MFA. |
REDEEM_CODE |
Solicitação para resgatar um código. |
LIST_PAYMENT_METHODS |
Busque a lista de formas de pagamento. |
O exemplo a seguir mostra como chamar grecaptcha.enterprise.execute()
em uma
atualização de número de telefone:
<script> function onClick(e) { e.preventDefault(); grecaptcha.enterprise.ready(async () => { const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'PHONE_NUMBER_UPDATE'}); }); } </script>
Avaliar eventos críticos do usuário
Quando você chama grecaptcha.enterprise.execute()
em uma ação do usuário, ele gera um token. Para os eventos de usuário críticos, como logins, registros e ações bem-sucedidos e com falha dos usuários conectados, crie uma avaliação para avaliar os resultados da chamada grecaptcha.enterprise.execute()
. A
avaliação fornece um veredito de risco, que pode ser usado para tomar uma decisão sobre como lidar com
atividades potencialmente fraudulentas. Algumas das ações que você pode realizar são bloquear solicitações suspeitas, desafiar logins arriscados e investigar contas de interesse.
O defensor da conta do reCAPTCHA Enterprise exige que você forneça um identificador de conta estável para atribuir atividades do usuário, como solicitações de login, de login e de inscrição, a uma conta específica. Isso ajuda o defensor da conta do reCAPTCHA Enterprise a entender os padrões de atividade do usuário e criar um modelo de atividade para cada conta com o objetivo de detectar melhor tráfego anômalo e abusivo.
Escolha um identificador de conta estável accountId
que não seja alterado com frequência pelo usuário
e forneça-o para a avaliação no método
projects.assessments.create
. Esse identificador de conta estável precisa ter o
mesmo valor para todos os eventos relacionados ao mesmo usuário. Você pode fornecer o seguinte como o identificador da conta:
Identificadores de usuários
Se cada conta puder ser exclusivamente associada a um nome de usuário, endereço de e-mail ou número de telefone estável, você poderá usá-lo como o accountId
. Quando você fornece esses identificadores
entre sites (que podem ser reutilizados em vários sites), o reCAPTCHA Enterprise usa essas
informações para melhorar a proteção das contas de usuário com base em modelos entre sites,
sinalizando identificadores de conta abusivos e usando o conhecimento de padrões de abuso entre sites relacionados
a esses identificadores.
Como alternativa, se você tiver um ID do usuário interno associado exclusivamente a cada conta, será possível
fornecê-lo como accountId
.
Com hash ou criptografado
Se você não tiver um ID do usuário interno associado exclusivamente a cada conta, poderá transformar qualquer identificador estável em um identificador de conta opaco e específico do site. Esse identificador ainda é necessário para que o defensor da conta do reCAPTCHA Enterprise entenda os padrões de atividade do usuário e detecte comportamentos anômalos, mas ele não é compartilhado com outros sites.
Escolha qualquer identificador de conta estável e torne-o opaco antes de enviar para o reCAPTCHA Enterprise usando criptografia ou hash:
criptografia (recomendado): criptografe o identificador da conta usando um método de criptografia determinístico que produza um texto criptografado estável. Para instruções detalhadas, consulte Criptografar dados de maneira determinista. Quando você escolhe a criptografia simétrica em vez do hash, não é necessário manter um mapeamento entre os identificadores de usuário e os identificadores opacos correspondentes. Descriptografe os identificadores opacos retornados pelo reCAPTCHA Enterprise para transformá-los em identificadores de usuários.
hash: recomendamos gerar hash do identificador da conta usando o método SHA256-HMAC com um sal personalizado de sua escolha. Como os hashes são unidirecionais, você precisa manter um mapeamento entre os hashes gerados e os identificadores de usuário para mapear o identificador de conta com hash que é retornado às contas originais.
Além de fornecer um identificador de conta estável para todas as solicitações relacionadas à conta, você pode fornecer outros identificadores de conta, possivelmente não estáveis, para algumas solicitações específicas.
Os identificadores de conta específicos do contexto fornecidos, além do accountId
, ajudam
o defensor da conta do reCAPTCHA Enterprise a entender melhor a atividade do usuário e detectar tentativas
de invasão para manter as contas de usuário seguras. Quando você fornece identificadores adicionais,
o reCAPTCHA Enterprise usa essas informações para melhorar a proteção das contas de usuário com base em
modelos entre sites, sinalizando identificadores de conta abusivos e usando o conhecimento de padrões de abuso
entre sites relacionados a esses identificadores. Por exemplo, você pode fornecer o seguinte:
O nome de usuário, endereço de e-mail ou número de telefone usado como identificador de login para solicitações de login
O endereço de e-mail ou número de telefone que foi verificado para uma solicitação de autenticação multifator
Um endereço de e-mail ou número de telefone (principal ou secundário) fornecido pelo usuário durante uma solicitação de atualização da conta
Os endereços de e-mail e números de telefone fornecidos pelo usuário durante uma solicitação de registro
Anexe o identificador de conta estável escolhido ao parâmetro accountId
no método
projects.assessments.create
para todas as solicitações relacionadas à conta. Se quiser,
forneça outros identificadores de conta para as solicitações relevantes usando o campo userIds
na avaliação.
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT_ID: é o ID do projeto do Google Cloud.
- TOKEN: token retornado da chamada
grecaptcha.enterprise.execute()
- KEY_ID: chave reCAPTCHA associada ao site
- ACCOUNT_ID: identificador associado exclusivamente à conta de usuário do seu site.
- EMAIL_ADDRESS: opcional. Um endereço de e-mail associado a esta solicitação, se houver
- PHONE_NUMBER: opcional. Um número de telefone associado a esta solicitação, se houver
- USERNAME: opcional. Um nome de usuário associado à solicitação, se houver
Método HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Corpo JSON da solicitação:
{ "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userInfo": { "accountId": "ACCOUNT_ID", "userIds": [ { "email": "EMAIL_ADDRESS" }, { "phoneNumber": "PHONE_NUMBER" }, { "username": "USERNAME" } ] } } }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a esta:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "login", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.6, }, "event": { "token": "TOKEN", "siteKey": "KEY", "userInfo": { "accountId": "ACCOUNT_ID" } }, "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000", "accountDefenderAssessment": { "labels": ["SUSPICIOUS_LOGIN_ACTIVITY"] } }
Exemplo de código
Java
Para autenticar no reCAPTCHA Enterprise, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Interpretar o veredito de risco dos eventos críticos do usuário
Quando você cria uma avaliação com o defensor da conta ativado, ele
retorna accountDefenderAssessment
como parte da resposta da avaliação.
O valor de accountDefenderAssessment
ajuda
a avaliar se a atividade do usuário é legítima ou fraudulenta. Ela também retorna
um ID de avaliação que você precisa usar ao anotar eventos do usuário.
O exemplo a seguir é um exemplo de resposta JSON:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "login", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.6, }, "event": { "token": "TOKEN", "siteKey": "KEY_ID", "expectedAction": "USER_ACTION" }, "name": "projects/PROJECT_ID/assessments/b6ac310000000000X", "accountDefenderAssessment": { labels: ["SUSPICIOUS_LOGIN_ACTIVITY"] } }
O campo accountDefenderAssessment
pode ter qualquer um dos seguintes valores:
Valor | Descrição |
---|---|
SUSPICIOUS_LOGIN_ACTIVITY |
Indica que a solicitação representa um alto risco de preenchimento de credenciais ou controle de conta. |
SUSPICIOUS_ACCOUNT_CREATION |
Indica que a solicitação representa um alto risco de criação abusiva de conta. |
PROFILE_MATCH |
Indica que os atributos do usuário correspondem aos atributos vistos anteriormente para esse usuário específico. Esse valor é um indicador de que o usuário está em um dispositivo confiável usado anteriormente para acessar seu site.
|
RELATED_ACCOUNTS_NUMBER_HIGH |
Indica que a solicitação tem um grande número de contas relacionadas. Isso não indica necessariamente que a conta seja ruim, mas pode exigir uma investigação mais detalhada. |
Anotar eventos para ajustar o modelo específico do site
Para fornecer mais informações ao defensor da conta do reCAPTCHA Enterprise e melhorar seu modelo de detecção específico do site, anote os eventos que você avaliou criando avaliações.
Para anotar uma avaliação, envie uma solicitação ao método projects.assessments.annotate
com o ID da avaliação. No corpo da solicitação, inclua rótulos
que fornecem mais informações sobre um evento descrito na avaliação.
Para anotar uma avaliação, faça o seguinte:
-
Determine as informações e os rótulos a serem adicionados no corpo JSON da solicitação, dependendo do caso de uso.
A tabela a seguir lista os rótulos e valores que podem ser usados para anotar eventos:
Identificador Descrição Exemplo de solicitação reasons
Obrigatório. Um rótulo para apoiar suas avaliações. Forneça detalhes do evento em tempo real no rótulo
reasons
alguns segundos ou minutos após o evento, porque eles influenciam a detecção em tempo real.Para ver a lista de valores possíveis, consulte motivos valores.
Exemplo: para detectar invasões de conta, anote se a senha inserida estava correta com os valores
CORRECT_PASSWORD
ouINCORRECT_PASSWORD
. Se você implantou sua própria MFA, pode adicionar os seguintes valores:INITIATED_TWO_FACTOR
ePASSED_TWO_FACTOR
ouFAILED_TWO_FACTOR
.{ "reasons": ["INCORRECT_PASSWORD"] }
annotation
Opcional. Um rótulo para indicar a legitimidade das avaliações. Forneça fatos sobre eventos de login e registro para validar ou corrigir suas avaliações de risco no rótulo
annotation
.Valores possíveis:
LEGITIMATE
ouFRAUDULENT
.É possível enviar essas informações a qualquer momento ou como parte de um job em lote. No entanto, recomendamos enviar essas informações alguns segundos ou minutos após o evento, porque elas influenciam a detecção em tempo real.
{ "annotation": "LEGITIMATE" }
accountId
Opcional. Um rótulo para associar um ID de conta a um evento.
Se você criou uma avaliação sem um ID de conta, use esse rótulo para fornecer o ID da conta de um evento sempre que ele estiver disponível.
{ "accountId": "ACCOUNT_ID" }
Crie uma solicitação de anotação com os rótulos apropriados.
Antes de usar os dados da solicitação, faça as substituições a seguir:
- ASSESSMENT_ID: valor do campo
name
retornado da chamadaprojects.assessments.create
. - ANNOTATION: opcional. Um rótulo para indicar se a avaliação é legítima ou fraudulenta.
- REASONS: opcional. Motivos que dão suporte à anotação. Para ver a lista de valores possíveis, consulte motivos valores.
- ACCOUNT_ID: (opcional) o identificador associado exclusivamente à conta de usuário no seu site.
Para mais informações, consulte rótulos de anotações.
Método HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Corpo JSON da solicitação:
{ "annotation": ANNOTATION, "reasons": REASONS, "accountId": ACCOUNT_ID }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome
request.json
e execute o comando a seguir:curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"PowerShell
Salve o corpo da solicitação em um arquivo com o nome
request.json
e execute o comando a seguir:$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate" | Select-Object -Expand ContentVocê receberá um código de status de êxito (2xx) e uma resposta vazia.
- ASSESSMENT_ID: valor do campo
Exemplo de código
Java
Para autenticar no reCAPTCHA Enterprise, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ativar o defensor da conta do reCAPTCHA Enterprise
Depois de configurar suas páginas da Web para a proteção da conta do reCAPTCHA Enterprise, é possível ativá-la.
No console do Google Cloud, acesse a página do reCAPTCHA Enterprise.
Verifique se o nome do projeto aparece no seletor de recursos na parte superior da página.
Se você não encontrar o nome do seu projeto, clique no seletor de recursos e selecione o projeto.
- Clique em Configurações.
No painel Defensor da conta, clique em Ativar.
Na caixa de diálogo Configurar defensor da conta, clique em Ativar.
Pode levar algumas horas para que a ativação do defensor da conta do reCAPTCHA Enterprise seja propagada para nossos sistemas. Depois que a ativação do recurso é propagada para nossos sistemas, comece a receber respostas relacionadas ao defensor da conta como parte das avaliações.