Detectar e evitar atividades fraudulentas relacionadas à conta em apps para dispositivos móveis

Este documento mostra como usar a defesa da conta para detectar e evitar atividades fraudulentas relacionadas à conta em aplicativos móveis.

O Fraud Defense ajuda a proteger ações críticas, como login e finalização de compra. No entanto, há muitas formas sutis de abuso de conta que podem ser detectadas ao observar o comportamento de um usuário específico em um aplicativo móvel durante um período. A Defesa de Conta, um recurso do Fraud Defense, ajuda a identificar esses tipos de abuso sutil criando um modelo específico do site para seu aplicativo móvel e detectando uma tendência de comportamento suspeito ou uma mudança na atividade. Ao usar o modelo específico do site, a defesa da conta ajuda a detectar o seguinte:

  • Atividades suspeitas
  • Contas com comportamentos parecidos
  • Solicitações de dispositivos marcados como confiáveis para usuários específicos

Com base na análise da defesa da conta e do modelo específico do site, você pode realizar as seguintes ações:

  • Restrinja ou desative contas fraudulentas.
  • Evite tentativas de sequestro de conta.
  • Reduza os sequestros de contas.
  • Conceda acesso apenas às solicitações de contas de usuários legítimas.
  • Reduzir o atrito para usuários que fazem login em um dos dispositivos de confiança.

Antes de começar

  1. A defesa da conta para aplicativos móveis pode ser acessada depois de acionar uma análise de segurança automática ao adicionar uma conta de faturamento ao projeto. Adicione uma conta de faturamento ao projeto para integrar seu aplicativo móvel a esse recurso.
  2. Prepare seu ambiente para o reCAPTCHA.
  3. Crie uma chave baseada em pontuação.

Configurar seu aplicativo para dispositivos móveis para a Defesa de Conta

A defesa da conta exige uma compreensão abrangente das atividades da conta para permitir uma detecção eficaz. Para começar a alimentar a Defesa de Conta com atividades relacionadas à conta e criar e melhorar seu modelo específico do site, faça o seguinte:

  1. Integre o Fraud Defense ao seu aplicativo para dispositivos móveis.

  2. Gerar relatórios sobre ações críticas do usuário.
  3. Avalie eventos críticos do usuário.
  4. Anotar eventos do usuário para ajustar seu modelo específico do site.

Gerar relatórios sobre ações críticas do usuário

Para detectar padrões de atividade suspeitos e criar um modelo melhor de padrões de atividade típicos no seu site, a defesa da conta precisa das informações sobre ações críticas do usuário. Para cada ação do app protegida com a Defesa contra fraude, chame o método execute() com RecaptchaAction. Para mais informações sobre execute() e RecaptchaAction, consulte:

A biblioteca do reCAPTCHA oferece um conjunto integrado de ações, e, se necessário, você pode criar ações personalizadas.

A tabela a seguir lista os nomes de ações que você pode usar ao informar as ações críticas do usuário.

Nome da ação Evento ou ação iniciada pelo usuário
LOGIN

Faça login no app para dispositivos móveis.
SIGNUP

Inscreva-se no aplicativo para dispositivos móveis.

Avaliar eventos críticos do usuário

Quando você chama execute() em uma ação do usuário, um token é gerado. Para os eventos críticos de usuário, como logins e registros bem-sucedidos e com falha, além de ações de usuários conectados, crie uma avaliação para analisar os resultados da chamada execute(). A avaliação fornece um veredito de risco, que você pode usar para decidir 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.

Para usar a defesa de conta, você precisa fornecer um identificador de conta estável para fazer a avaliação e atribuir a atividade do usuário (como solicitações de login, solicitações de login e solicitações de inscrição) a uma conta específica. Isso ajuda a defesa da conta a processar padrões de atividade do usuário para criar um modelo de atividade para cada conta e 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 à 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 identificador da conta:

Identificadores de usuários

Se cada conta puder ser associada de forma exclusiva a um nome de usuário, endereço de e-mail ou número de telefone estável, use isso como o accountId. Quando você fornece esses identificadores entre sites (que podem ser reutilizados em vários sites), o reCAPTCHA usa essas informações para melhorar a proteção das suas contas de usuário com base em modelos entre sites. Para isso, ele sinaliza identificadores de contas abusivas e usa o conhecimento de padrões de abuso entre sites relacionados a esses identificadores.

Como alternativa, se você tiver um ID de usuário interno associado exclusivamente a cada conta, forneça-o como accountId.

Criptografadas ou transformadas em hash

Se você não tiver um ID de usuário interno associado de maneira exclusiva 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 reCAPTCHA Account Defender entenda os padrões de atividade do usuário e detecte comportamentos anômalos, mas não é compartilhado em outros sites.

Escolha um identificador de conta estável e o torne opaco antes de enviar ao reCAPTCHA usando criptografia ou hash:

  • criptografia (recomendado): criptografe o identificador da conta usando um método de criptografia determinista que produza um texto cifrado estável. Para instruções detalhadas, consulte criptografar dados de forma determinística. Ao escolher a criptografia simétrica em vez do hash, não é necessário manter um mapeamento entre seus identificadores de usuário e os identificadores opacos correspondentes. Descriptografe os identificadores opacos retornados pelo reCAPTCHA para transformá-los no identificador do usuário.

  • Geração de hash: recomendamos gerar hash do identificador da conta usando o método SHA256-HMAC com um salt personalizado de sua escolha. Como os hashes são unidirecionais, é necessário manter um mapeamento entre os hashes gerados e os identificadores de usuário para que seja possível mapear o identificador de conta com hash que é retornado para as 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 da accountId, ajudam a Defesa de Conta a analisar melhor a atividade do usuário e detectar tentativas de sequestro de conta para manter as contas de usuário seguras. Quando você fornece outros identificadores, o Google Cloud Fraud Defense usa essas informações para melhorar a proteção das suas contas de usuário com base em modelos entre sites, sinalizando identificadores de contas abusivas 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 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

Adicione o identificador de conta estável escolhido ao parâmetro accountId no método projects.assessments.create para todas as solicitações relacionadas à conta. Opcionalmente, 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 abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud
  • TOKEN: token retornado da chamada execute()
  • KEY_ID: chave reCAPTCHA associada ao app
  • ACCOUNT_ID: o identificador associado exclusivamente à conta de usuário para uma conta de usuário no seu app.
  • 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 a esta 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 abaixo: 

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 abaixo: 

$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,
    "androidPackageName": "com.example.app" or "iosBundleId": "com.example.app",
    "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 Fraud Defense, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.protobuf.ByteString;
import com.google.recaptchaenterprise.v1.AccountDefenderAssessment.AccountDefenderLabel;
import com.google.recaptchaenterprise.v1.Assessment;
import com.google.recaptchaenterprise.v1.CreateAssessmentRequest;
import com.google.recaptchaenterprise.v1.Event;
import com.google.recaptchaenterprise.v1.ProjectName;
import com.google.recaptchaenterprise.v1.RiskAnalysis.ClassificationReason;
import com.google.recaptchaenterprise.v1.TokenProperties;
import com.google.recaptchaenterprise.v1.UserId;
import com.google.recaptchaenterprise.v1.UserInfo;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.List;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class AccountDefenderAssessment {

  public static void main(String[] args)
      throws IOException, NoSuchAlgorithmException, InvalidKeyException {
    // TODO(developer): Replace these variables before running the sample.
    // projectId: Google Cloud Project ID
    String projectId = "project-id";

    // recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha
    // services.
    String recaptchaSiteKey = "recaptcha-site-key";

    // token: The token obtained from the client on passing the recaptchaSiteKey.
    // To get the token, integrate the recaptchaSiteKey with frontend. See,
    // https://cloud.google.com/recaptcha-enterprise/docs/instrument-web-pages#frontend_integration_score
    String token = "recaptcha-token";

    // recaptchaAction: The action name corresponding to the token.
    String recaptchaAction = "recaptcha-action";

    // Unique ID of the user, such as email, customer ID, etc.
    String accountId = "default" + UUID.randomUUID().toString().split("-")[0];

    // User phone number
    String phoneNumber = "555-987-XXXX";

    // User email address
    String emailAddress = "john.doe@example.com";

    accountDefenderAssessment(projectId, recaptchaSiteKey, token, recaptchaAction, accountId, phoneNumber, emailAddress);
  }

  /**
   * This assessment detects account takeovers. See,
   * https://cloud.google.com/recaptcha-enterprise/docs/account-takeovers The input is the hashed
   * account id. Result tells if the action represents an account takeover. You can optionally
   * trigger a Multi-Factor Authentication based on the result.
   */
  public static void accountDefenderAssessment(
      String projectId,
      String recaptchaSiteKey,
      String token,
      String recaptchaAction,
      String accountId,
      String phoneNumber,
      String emailAddress)
      throws IOException {
    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {

      // Set the properties of the event to be tracked.
      Event.Builder eventBuilder =
          Event.newBuilder()
              .setSiteKey(recaptchaSiteKey)
              .setToken(token);

      // Set the account id, email address and phone number (of the user).
      eventBuilder.setUserInfo(
        UserInfo.newBuilder()
          .setAccountId(accountId)
          .addUserIds(UserId.newBuilder().setEmail(emailAddress))
          .addUserIds(UserId.newBuilder().setPhoneNumber(phoneNumber)));

      Event event = eventBuilder.build();

      // Build the assessment request.
      CreateAssessmentRequest createAssessmentRequest =
          CreateAssessmentRequest.newBuilder()
              .setParent(ProjectName.of(projectId).toString())
              .setAssessment(Assessment.newBuilder().setEvent(event).build())
              .build();

      Assessment response = client.createAssessment(createAssessmentRequest);

      // Check integrity of the response token.
      if (!checkTokenIntegrity(response.getTokenProperties(), recaptchaAction)) {
        return;
      }

      // Get the reason(s) and the reCAPTCHA risk score.
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
        System.out.println(reason);
      }
      float recaptchaScore = response.getRiskAnalysis().getScore();
      System.out.println("The reCAPTCHA score is: " + recaptchaScore);
      String assessmentName = response.getName();
      System.out.println(
          "Assessment name: " + assessmentName.substring(assessmentName.lastIndexOf("/") + 1));

      // Get the Account Defender result.
      com.google.recaptchaenterprise.v1.AccountDefenderAssessment accountDefenderAssessment =
          response.getAccountDefenderAssessment();
      System.out.println(accountDefenderAssessment);

      // Get Account Defender label.
      List<AccountDefenderLabel> defenderResult =
          response.getAccountDefenderAssessment().getLabelsList();
      // Based on the result, can you choose next steps.
      // If the 'defenderResult' field is empty, it indicates that Account Defender did not have
      // anything to add to the score.
      // Few result labels: ACCOUNT_DEFENDER_LABEL_UNSPECIFIED, PROFILE_MATCH,
      // SUSPICIOUS_LOGIN_ACTIVITY, SUSPICIOUS_ACCOUNT_CREATION, RELATED_ACCOUNTS_NUMBER_HIGH.
      // For more information on interpreting the assessment, see:
      // https://cloud.google.com/recaptcha-enterprise/docs/account-defender#interpret-assessment-details
      System.out.println("Account Defender Assessment Result: " + defenderResult);
    }
  }

  private static boolean checkTokenIntegrity(
      TokenProperties tokenProperties, String recaptchaAction) {
    // Check if the token is valid.
    if (!tokenProperties.getValid()) {
      System.out.println(
          "The Account Defender Assessment call failed because the token was: "
              + tokenProperties.getInvalidReason().name());
      return false;
    }

    // Check if the expected action was executed.
    if (!tokenProperties.getAction().equals(recaptchaAction)) {
      System.out.printf(
          "The action attribute in the reCAPTCHA tag '%s' does not match "
              + "the action '%s' you are expecting to score",
          tokenProperties.getAction(), recaptchaAction);
      return false;
    }
    return true;
  }
}

Interpretar o veredito de risco dos eventos críticos do usuário

Quando você cria uma avaliação com a defesa da conta ativada, ela 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. Ele também retorna um ID de avaliação que você precisa usar ao anotar eventos do usuário.

Confira a seguir um exemplo de resposta JSON:

{
  "tokenProperties": {
    "valid": true,
    "androidPackageName": "com.example.app" or "iosBundleId": "com.example.app",
    "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 ataque de preenchimento de credenciais ou sequestro de conta.
SUSPICIOUS_ACCOUNT_CREATION Indica que a solicitação representa um alto risco de criação de conta abusiva.
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 que foi usado antes para acessar seu aplicativo móvel.

PROFILE_MATCH é retornado apenas nos seguintes cenários:

  • Você usa a autenticação multifator (MFA) ou de dois fatores (2FA) e a Defesa de Conta marca os perfis de usuário como confiáveis depois que os usuários passam pelo desafio da MFA ou da 2FA.
  • Você anota as avaliações como LEGITIMATE ou PASSED_TWO_FACTOR, e a defesa da conta marca o perfil de usuário correspondente como confiável.

Anotar eventos para ajustar seu modelo específico do site

Para fornecer mais informações à defesa da conta e melhorar seu modelo de detecção específico do site, anote os eventos avaliados 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 dessa solicitação, inclua rótulos com mais informações sobre um evento descrito na avaliação.

Para fazer anotações em uma avaliação, faça o seguinte:

  1. Determine as informações e os rótulos a serem adicionados ao corpo JSON da solicitação, dependendo do seu caso de uso.

    A tabela a seguir lista os rótulos e valores que podem ser usados para anotar eventos:

    Rótulo Descrição Exemplo de solicitação
    reasons Obrigatório. Um rótulo para apoiar suas avaliações.

    Forneça detalhes de eventos em tempo real no rótulo reasons em alguns segundos ou minutos após o evento, porque eles influenciam a detecção em tempo real.

    Para conferir a lista de valores possíveis, consulte valores de motivos.

    Exemplo: para detectar aquisições de contas, anote se a senha inserida estava correta com os valores CORRECT_PASSWORD ou INCORRECT_PASSWORD. Se você tiver implantado sua própria MFA, adicione os seguintes valores: INITIATED_TWO_FACTOR e PASSED_TWO_FACTOR ou FAILED_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 ou FRAUDULENT.

    Você pode 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 da conta a um evento.

    Se você criou uma avaliação sem um ID de conta, use esse rótulo para fornecer o ID de conta de um evento sempre que ele estiver disponível.

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

  2. Crie uma solicitação de anotação com os rótulos adequados.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • ASSESSMENT_ID: valor do campo name retornado pela chamada projects.assessments.create.
    • ANNOTATION: opcional. Um rótulo para indicar se a avaliação é legítima ou fraudulenta.
    • REASONS: opcional. Motivos que embasem sua anotação. Para conferir a lista de valores possíveis, consulte valores de motivos.
    • ACCOUNT_ID: opcional. O identificador associado exclusivamente à conta de usuário no seu app.

    Para mais informações, consulte rótulos para 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 abaixo: 

    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 Content

    Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Exemplo de código

Java

Para autenticar no Fraud Defense, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.protobuf.ByteString;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest.Annotation;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest.Reason;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentResponse;
import com.google.recaptchaenterprise.v1.AssessmentName;
import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.util.UUID;

public class AnnotateAccountDefenderAssessment {

  public static void main(String[] args) throws IOException, NoSuchAlgorithmException {
    // TODO(developer): Replace these variables before running the sample.
    // projectID: GCloud Project id.
    String projectID = "project-id";

    // assessmentId: Value of the 'name' field returned from the CreateAssessment call.
    String assessmentId = "account-defender-assessment-id";

    // accountId: Set the accountId corresponding to the assessment id.
    String accountId = "default" + UUID.randomUUID().toString().split("-")[0];

    annotateAssessment(projectID, assessmentId, accountId);
  }

  /**
   * Pre-requisite: Create an assessment before annotating. Annotate an assessment to provide
   * feedback on the correctness of recaptcha prediction.
   */
  public static void annotateAssessment(
      String projectID, String assessmentId, String accountId) throws IOException {

    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {
      // Build the annotation request.
      // For more info on when/how to annotate, see:
      // https://cloud.google.com/recaptcha-enterprise/docs/annotate-assessment#when_to_annotate
      AnnotateAssessmentRequest annotateAssessmentRequest =
          AnnotateAssessmentRequest.newBuilder()
              .setName(AssessmentName.of(projectID, assessmentId).toString())
              .setAnnotation(Annotation.LEGITIMATE)
              .addReasons(Reason.PASSED_TWO_FACTOR)
              .setAccountId(accountId)
              .build();

      // Empty response is sent back.
      AnnotateAssessmentResponse response = client.annotateAssessment(annotateAssessmentRequest);
      System.out.println("Annotated response sent successfully ! " + response);
    }
  }
}

Usar e interpretar a pontuação de risco de sequestro de conta

O recurso de pontuação de risco de sequestro de contas (ATO) adiciona uma pontuação de risco numérica e explicações legíveis à avaliação da defesa da conta. Esses insights ajudam você a entender a avaliação e embasar suas ações ou decisões subsequentes.

Receber a pontuação de risco

Para receber a pontuação de risco e os motivos de explicabilidade, envie uma solicitação CreateAssessment e inclua event.userInfo.accountId.

Leia a pontuação de risco e os detalhes

A pontuação de risco e os motivos de explicabilidade estão no objeto accountDefenderAssessment.accountTakeoverVerdict da resposta da avaliação.

  • Pontuação de risco: accountDefenderAssessment.accountTakeoverVerdict.risk
  • Motivos de risco: accountDefenderAssessment.accountTakeoverVerdict.riskReasons
  • Motivos de confiança: accountDefenderAssessment.accountTakeoverVerdict.trustReasons

O snippet a seguir mostra um exemplo dos campos em uma resposta de avaliação:

  "accountDefenderAssessment": {
    "labels": ["PROFILE_MATCH"],
    "accountTakeoverVerdict": {
      "risk": 0.249,
      "riskReasons": [{"reason": "CLIENT_ACCESSED_MANY_ACCOUNTS"}],
      "trustReasons": [{"reason": "PROFILE_MATCH"}, {"reason": "ACCOUNT_HISTORY_REPUTABLE"}]
    }
  }

Interpretar a pontuação de risco de um ATO

Ao usar a pontuação de risco, estabeleça um limite para determinar quando tomar medidas de proteção.

Use a pontuação de risco de ATO como uma alternativa ao rótulo SUSPICIOUS_LOGIN_ACTIVITY. Não use a pontuação de risco e o rótulo para acionar a aplicação na mesma avaliação. Você pode configurar a lógica de aplicação com base na pontuação de risco que excede o limite ou na presença do rótulo. Em geral, a pontuação de risco oferece uma avaliação mais granular.

Recomendamos que você avalie a performance da pontuação de risco com um limite adequado no tráfego da sua plataforma antes de usá-la para aplicação.

Para agir de acordo com a pontuação de risco, implemente uma verificação no back-end, conforme mostrado no snippet a seguir:

if (assessment.accountDefenderAssessment.accountTakeoverVerdict.risk > YOUR_CHOSEN_THRESHOLD) {
  // Treat as suspicious
  // Implement protective actions
}

Limites padrão de pontuação de risco

A tabela a seguir fornece os limites padrão de pontuação de risco e as taxas de falsos positivos (FPR) esperadas. Escolha um limite com base na sua taxa de falsos positivos (FPR) aceitável. A performance pode variar, então talvez seja necessário ajustar o limite com base na performance observada.

FPR esperado Limite da pontuação de risco
0,1% 1.0
0,25% 0,9
0,5% 0,8
1% 0,7
2% 0,6
4% 0,5
8% 0,4
15% 0,3
30% 0,2
60% 0,1
100% 0,0

Ajustar o limite

Se a FPR observada for muito alta, aumente o limite. Se o recall observado for muito baixo e você puder tolerar uma taxa de FPR mais alta, diminua o limite.

Calcular valores intermediários

Para estimar a FPR de um limite entre os valores padrão, use a interpolação linear. O exemplo a seguir mostra como calcular a FPR para um limite de 0,85:

FPR(T: 0.85) = (FPR(T: 0.8) + FPR(T: 0.9)) / 2 = (0.5% + 0.25%) / 2 = 0.375%

Para encontrar um limite para uma FPR específica, faça uma interpolação entre os valores padrão. O exemplo a seguir mostra como encontrar o limite para uma FPR de 5%:

Threshold = 0.4 + (0.5 − 0.4) × (8% − 5%) / (8% − 4%)
Threshold = 0.4 + 0.1 × (3 / 4)
Threshold = 0.4 + 0.075 = 0.475

Estima-se que um limite de 0,475 gere uma FPR de 5%.

Interpretar motivos de explicabilidade

Os motivos de explicabilidade fornecem insights sobre fatores que influenciam a pontuação de risco. Use esses motivos para refinar sua tomada de decisões.

  • Motivos de risco: indicam fatores associados a um risco maior de sequestro de conta.
  • Motivos de confiança: indicam fatores que sugerem legitimidade.

Motivos de risco e confiança podem aparecer para qualquer pontuação de risco.

Motivo Tipo Interpretação
PROFILE_MATCH Confiável A solicitação corresponde a um perfil confiável associado a esta conta. Isso é equivalente ao rótulo AccountDefenderLabel.PROFILE_MATCH.
ACCOUNT_HISTORY_REPUTABLE Confiável A atividade histórica da conta é confiável. É improvável que a conta tenha sido comprometida no passado.
CLIENT_HISTORICAL_BOT_ACTIVITY Risco O cliente já enviou tráfego semelhante a bots para esse site. Esse motivo incorpora a reputação histórica e indica que o cliente é conhecido por usar bots, mesmo que a solicitação atual esteja sendo feita por um humano.
ACCOUNT_IN_LARGE_RELATED_GROUP Risco A conta faz parte de um grande grupo de contas relacionadas, o que indica que ela pode fazer parte de uma rede fraudulenta. As contas relacionadas são identificadas com base em padrões de tráfego e características de solicitação semelhantes.
CLIENT_ACCESSED_MANY_ACCOUNTS Risco O cliente acessou muitas contas neste site.

A seguir