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

Este documento mostra como usar o defensor de conta reCAPTCHA para detectar e impedir atividades fraudulentas relacionadas a contas em aplicativos para dispositivos móveis.

O reCAPTCHA ajuda a proteger ações críticas, como login e finalização de compra. No entanto, existem muitas formas sutis de abuso de conta que podem ser detectadas observando o comportamento de um usuário específico em um aplicativo para dispositivos móveis por um período de tempo. O reCAPTCHA Account Defender ajuda a identificar esses tipos de abuso sutil criando um modelo específico do site para que seu aplicativo para dispositivos móveis detecte 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 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 do defensor da conta do reCAPTCHA 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.
• Reduzir as invasões de contas.
• Conceda acesso apenas às solicitações provenientes de contas de usuários legítimas.
• Reduza o atrito para os usuários que fazem login em um dispositivo confiável.

Antes de começar

1. O defensor da conta reCAPTCHA para aplicativos para dispositivos móveis pode ser acessado após acionar uma análise de segurança automática adicionando uma conta de faturamento ao projeto. Adicione uma conta de faturamento ao seu projeto para integrar o site a esse recurso.
2. Prepare seu ambiente para o reCAPTCHA.
3. Crie uma chave baseada em pontuação.

Configurar o aplicativo para dispositivos móveis para o defensor da conta do reCAPTCHA

O defensor da conta do reCAPTCHA exige um entendimento abrangente das atividades da conta para permitir uma detecção eficaz. Para começar a enviar atividades relacionadas à conta ao defensor da conta do reCAPTCHA e criar e melhorar o modelo específico do site, faça o seguinte:

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

   • Para apps Android, consulte Integrar o reCAPTCHA a apps Android.
   • Para apps iOS, consulte Integrar o reCAPTCHA aos apps iOS.
2. Gere relatórios sobre ações críticas do usuário.
3. Avalie eventos críticos do usuário.
4. Anote eventos do usuário para ajustar o modelo específico do site.

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

Para detectar padrões de atividade suspeitos e entender melhor os padrões de atividade típicos no seu site, o reCAPTCHA Account Defender precisa das informações sobre ações importantes do usuário. Para cada ação do app protegida pelo reCAPTCHA, chame o método execute() com RecaptchaAction. Para mais informações sobre execute() e RecaptchaAction, consulte:

• Android: execute() e RecaptchaAction.
• iOS: execute() e RecaptchaAction.

O reCAPTCHA oferece um conjunto integrado de ações. Se necessário, você pode criar ações personalizadas.

A tabela a seguir lista os nomes das ações que podem ser usados ao informar as ações críticas do usuário.

Avaliar eventos críticos do usuário

Quando você chama execute() em uma ação do usuário, um token é gerado. Para os casos eventos do usuário, como logins bem-sucedidos e com falha, registros e ações da usuários, crie uma avaliação para avaliar os resultados da chamada execute(). O avaliação fornece um veredito de risco, que pode ser usado para tomar uma decisão sobre como lidar atividades potencialmente fraudulentas. Algumas das ações que você pode realizar são bloquear solicitações suspeitas, contestar logins arriscados e investigar contas de interesse.

O reCAPTCHA Account Defender exige que você forneça um identificador de conta estável para 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 o reCAPTCHA Account Defender a entender os padrões de atividade do usuário e a criar um modelo de atividade para cada conta, para detectar melhor o tráfego anormal e abusivo.

Escolha um identificador de conta estável accountId que não seja alterado com frequência pelo usuário e enviá-lo para a avaliação projects.assessments.create. Esse identificador de conta estável deve ter a o mesmo valor para todos os eventos relacionados ao mesmo usuário. Você pode fornecer o seguinte como identificador da conta:

Além de fornecer um identificador de conta estável para todas as solicitações relacionadas à conta, você pode fornecer identificadores de conta adicionais, possivelmente não estáveis, para algumas solicitações específicas. Os identificadores de conta específicos do contexto fornecidos com a ajuda do accountId Defensor da conta do reCAPTCHA entende melhor a atividade do usuário e detecta a conta tentativas de invasão para manter a segurança das suas contas de usuário. Ao fornecer identificadores adicionais, O reCAPTCHA usa essas informações para melhorar a proteção das contas de usuário com base nas modelos entre sites sinalizando identificadores de conta abusivos e usando conhecimento 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 com a autenticação multifator solicitação de autenticação

• Um endereço de e-mail ou número de telefone (principal ou secundário) fornecido pelo usuário durante um pedido de atualização da conta

• Os endereços de e-mail e números de telefone fornecidos pelo usuário durante o registro solicitação

Anexe o identificador de conta estável escolhido ao parâmetro accountId no projects.assessments.create para todas as solicitações relacionadas à conta. Opcionalmente, fornecer identificadores de conta adicionais para as solicitações relevantes usando o 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 que é associado exclusivamente à conta de usuário para um conta de usuário ao seu app
• EMAIL_ADDRESS: opcional. Um endereço de e-mail associado a essa solicitação, se nenhum
• PHONE_NUMBER: opcional. Um número de telefone associado a essa 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 -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"

$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

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 o defensor da conta ativado, retorna accountDefenderAssessment como parte da resposta da avaliação. O valor de accountDefenderAssessment ajuda você avalia 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 destes valores:

Anotar eventos para ajustar o modelo específico do site

Para fornecer mais informações ao defensor da conta reCAPTCHA e melhorar seu modelo de detecção específico do site, você precisa anotar os eventos que 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, você inclui rótulos Oferecer mais informações sobre um evento descrito na avaliação.

Para anotar uma avaliação, faça o seguinte:

1. Determinar as informações e 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 você pode usar para fazer anotações eventos:

   Rótulo	Descrição	Exemplo de solicitação
   reasons	Obrigatório. Um rótulo para apoiar avaliações. Forneça detalhes do evento em tempo real no Rótulo reasons alguns segundos ou minutos após o evento porque 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ê implantou sua própria MFA, é possível adicionar 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. É possível enviar essas informações a qualquer momento ou como parte de uma job em lote. No entanto, recomendamos enviar essas informações em alguns segundos ou minutos após o evento porque 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 da conta, use esse rótulo para fornecer o ID da 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 apropriados.

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

   • ASSESSMENT_ID: valor do campo name retornado da chamada projects.assessments.create.
   • ANNOTATION: opcional. Um rótulo que indica se a avaliação é legítima ou fraudulenta.
   • REASONS: opcional. Motivos que justificam 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 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 Content

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

Exemplo de código

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);
    }
  }
}

Ativar o defensor da conta do reCAPTCHA

Depois de configurar seu aplicativo para dispositivos móveis para o defensor da conta reCAPTCHA, ative o defensor da conta reCAPTCHA.

1. No console do Google Cloud, acesse a página do reCAPTCHA.

   Acessar o reCAPTCHA

2. Verifique se o nome do projeto aparece no seletor de recursos na parte de cima da página.

   Se você não vir o nome do seu projeto, clique no seletor de recursos e selecione o projeto.

3. Clique em settingsConfigurações.

4. No painel Defesa de conta, clique em Configurar.

   

5. Na caixa de diálogo Configurar o defensor da conta, clique em Ativar e, em seguida, clique em Salvar.

   

O defensor da conta reCAPTCHA pode levar algumas horas se propagam para nossos sistemas. Depois que a ativação do recurso for propagada para nossos sistemas, você vai começar a receber respostas relacionadas ao Account Defender como parte das avaliações.

A seguir

• Saiba mais sobre outros recursos de proteção de contas em Recursos de proteção de contas de usuário.