Detecta y evita actividades fraudulentas relacionadas con cuentas en aplicaciones para dispositivos móviles

En este documento, se muestra cómo usar la Defensa de la cuenta para detectar y prevenir actividades fraudulentas relacionadas con la cuenta en aplicaciones para dispositivos móviles.

Fraud Defense te ayuda a proteger acciones críticas, como el inicio de sesión y la confirmación de compra. Sin embargo, existen muchas formas sutiles de abuso de cuentas que se pueden detectar observando el comportamiento de un usuario específico en una aplicación para dispositivos móviles durante un período. Account defense, una función de Fraud Defense, ayuda a identificar este tipo de abusos sutiles creando un modelo específico del sitio para tu aplicación para dispositivos móviles que detecte una tendencia de comportamiento sospechoso o un cambio en la actividad. Con el modelo específico del sitio, la Protección de cuentas te ayuda a detectar lo siguiente:

  • Actividades sospechosas
  • Cuentas con comportamientos similares
  • Solicitudes provenientes de dispositivos que se marcaron como de confianza para usuarios específicos

Según el análisis de la defensa de la cuenta y el modelo específico del sitio, puedes realizar las siguientes acciones:

  • Restringir o inhabilitar las cuentas fraudulentas
  • Evita los intentos de apropiación de cuentas.
  • Mitigar las apropiaciones de cuentas exitosas
  • Otorga acceso solo a las solicitudes provenientes de cuentas de usuario legítimas.
  • Reducir los obstáculos para los usuarios que acceden desde uno de sus dispositivos de confianza

Antes de comenzar

  1. Podrás acceder a la protección de cuentas para aplicaciones para dispositivos móviles después de activar una revisión de seguridad automática agregando una cuenta de facturación a tu proyecto. Agrega una cuenta de facturación a tu proyecto para incorporar tu aplicación para dispositivos móviles a esta función.
  2. Prepara tu entorno para reCAPTCHA.
  3. Crea una clave basada en la puntuación.

Configura tu aplicación para dispositivos móviles para Account defense

La protección de cuentas requiere una comprensión integral de las actividades de la cuenta para permitir una detección eficaz. Para comenzar a enviar actividades relacionadas con la cuenta a Account defense y crear y mejorar tu modelo específico del sitio, haz lo siguiente:

  1. Integra Fraud Defense en tu aplicación para dispositivos móviles.

  2. Genera informes sobre las acciones críticas de los usuarios.
  3. Evalúa los eventos de usuario críticos.
  4. Anota los eventos de usuarios para ajustar tu modelo específico del sitio.

Genera informes sobre las acciones críticas del usuario

Para detectar patrones de actividad sospechosos y crear un mejor modelo de los patrones de actividad típicos en tu sitio, la Defensa de la cuenta necesita información sobre las acciones críticas del usuario. Para cada acción de tu app que esté protegida con Fraud Defense, llama al método execute() con RecaptchaAction. Para obtener más información sobre execute() y RecaptchaAction, consulta los siguientes vínculos:

La biblioteca de reCAPTCHA proporciona un conjunto integrado de acciones y, si es necesario, puedes crear acciones personalizadas.

En la siguiente tabla, se enumeran los nombres de las acciones que puedes usar cuando informes las acciones críticas del usuario.

Nombre de la acción Evento o acción iniciados por el usuario
LOGIN

Accede a la aplicación para dispositivos móviles.
SIGNUP

Regístrate en la aplicación para dispositivos móviles.

Evalúa los eventos de usuario críticos

Cuando llamas a execute() en una acción del usuario, se genera un token. Para los eventos críticos del usuario, como los accesos, los registros y las acciones de los usuarios que accedieron a sus cuentas (tanto los exitosos como los fallidos), crea una evaluación para analizar los resultados de la llamada a execute(). La evaluación te proporciona un veredicto de riesgo que puedes usar para tomar una decisión sobre cómo manejar las actividades potencialmente fraudulentas. Algunas de las acciones que puedes realizar son bloquear solicitudes sospechosas, desafiar inicios de sesión riesgosos e investigar cuentas de interés.

La defensa de la cuenta requiere que proporciones un identificador de cuenta estable para realizar la evaluación y atribuir la actividad del usuario (como solicitudes de acceso, solicitudes de acceso y solicitudes de registro) a una cuenta específica. Esto ayuda a la Defensa de la cuenta a procesar los patrones de actividad del usuario para compilar un modelo de actividad para cada cuenta y detectar mejor el tráfico anómalo y abusivo.

Elige un identificador de cuenta estable accountId que el usuario no cambie con frecuencia y proporciónalo a la evaluación en el método projects.assessments.create. Este identificador de cuenta estable debe tener el mismo valor para todos los eventos relacionados con el mismo usuario. Puedes proporcionar lo siguiente como identificador de la cuenta:

Identificadores de usuario

Si cada cuenta se puede asociar de forma única con un nombre de usuario, una dirección de correo electrónico o un número de teléfono estables, puedes usarlo como accountId. Cuando proporcionas esos identificadores entre sitios (identificadores que se pueden reutilizar en diferentes sitios), reCAPTCHA utiliza esta información para mejorar la protección de tus cuentas de usuario en función de los modelos entre sitios, ya que marca los identificadores de cuentas abusivas y utiliza el conocimiento de los patrones de abuso entre sitios relacionados con estos identificadores.

Como alternativa, si tienes un ID de usuario interno asociado de forma única a cada cuenta, puedes proporcionarlo como accountId.

Con hash o encriptado

Si no tienes un ID de usuario interno asociado de forma única a cada cuenta, puedes convertir cualquier identificador estable en un identificador de cuenta opaco y específico del sitio. Este identificador sigue siendo necesario para la protección de cuentas de reCAPTCHA para comprender los patrones de actividad del usuario y detectar comportamientos anómalos, pero no se comparte en otros sitios.

Elige cualquier identificador de cuenta estable y hazlo opaco antes de enviarlo a reCAPTCHA con encriptación o hash:

  • Encriptación (recomendada): Encripta el identificador de la cuenta con un método de encriptación determinístico que produzca un texto cifrado estable. Para obtener instrucciones detalladas, consulta cómo encriptar datos de forma determinística. Cuando eliges el cifrado simétrico en lugar del hash, no necesitas mantener una asignación entre tus identificadores de usuario y los identificadores de usuario opacos correspondientes. Descifrar los identificadores opacos que devuelve reCAPTCHA para convertirlos en el identificador del usuario

  • Codificación hash: Recomendamos codificar el identificador de la cuenta con el método SHA256-HMAC y una sal personalizada de tu elección. Dado que los hashes son unidireccionales, debes mantener una asignación entre los hashes generados y tus identificadores de usuario para poder asignar el identificador de cuenta con hash que se devuelve a las cuentas originales.

Además de proporcionar un identificador de cuenta estable para todas las solicitudes relacionadas con la cuenta, puedes proporcionar identificadores de cuenta adicionales, posiblemente no estables, para algunas solicitudes específicas. Los identificadores de cuenta específicos del contexto que se proporcionan además de accountId ayudan a Account defense a analizar mejor la actividad del usuario y detectar intentos de apropiación de cuentas para mantener seguras las cuentas de los usuarios. Cuando proporcionas identificadores adicionales, Google Cloud Fraud Defense usa esta información para mejorar la protección de tus cuentas de usuario en función de los modelos entre sitios, ya que marca los identificadores de cuentas abusivas y usa el conocimiento de los patrones de abuso entre sitios relacionados con estos identificadores. Por ejemplo, puedes proporcionar lo siguiente:

  • El nombre de usuario, la dirección de correo electrónico o el número de teléfono que se usó como identificador de acceso para las solicitudes de acceso

  • La dirección de correo electrónico o el número de teléfono que se verificó para una solicitud de autenticación de varios factores

  • Una dirección de correo electrónico o un número de teléfono (principal o secundario) que proporcionó el usuario durante una solicitud de actualización de la cuenta

  • Las direcciones de correo electrónico y los números de teléfono que proporciona el usuario durante una solicitud de registro

Agrega el identificador de cuenta estable elegido al parámetro accountId en el método projects.assessments.create para todas las solicitudes relacionadas con la cuenta. De manera opcional, proporciona identificadores de cuenta adicionales para las solicitudes pertinentes con el campo userIds en la evaluación.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto de Google Cloud
  • TOKEN: Token que se muestra a partir de la llamada execute()
  • KEY_ID: Clave de reCAPTCHA asociada con la app
  • ACCOUNT_ID: Es el identificador asociado de forma única con la cuenta de usuario de tu app.
  • EMAIL_ADDRESS: Opcional Una dirección de correo electrónico asociada a esta solicitud, si hay alguna
  • PHONE_NUMBER: Opcional Un número de teléfono asociado a esta solicitud, si hay alguno
  • USERNAME: Opcional Nombre de usuario asociado a esta solicitud, si corresponde

Método HTTP y URL: 

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

Cuerpo JSON de la solicitud:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userInfo": {
      "accountId": "ACCOUNT_ID",
      "userIds": [
        {
          "email": "EMAIL_ADDRESS"
        },
        {
          "phoneNumber": "PHONE_NUMBER"
        },
        {
          "username": "USERNAME"
        }
      ]
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

$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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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"]
  }
}

Muestra de código

Java

Para autenticarte en Fraud Defense, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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;
  }
}

Interpreta el veredicto de riesgo de los eventos críticos del usuario

Cuando creas una evaluación con la Protección de cuentas habilitada, esta devuelve accountDefenderAssessment como parte de la respuesta de evaluación. El valor de accountDefenderAssessment te ayuda a evaluar si la actividad del usuario es legítima o fraudulenta. También devuelve un ID de evaluación que debes usar cuando anotes eventos del usuario.

El siguiente ejemplo es una respuesta JSON de muestra:

{
  "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"]
  }
}

El campo accountDefenderAssessment puede tener cualquiera de los siguientes valores:

Valor Descripción
SUSPICIOUS_LOGIN_ACTIVITY Indica que la solicitud representa un alto riesgo de robo de credenciales o apropiación de cuentas.
SUSPICIOUS_ACCOUNT_CREATION Indica que la solicitud representa un alto riesgo de creación de cuentas abusivas.
PROFILE_MATCH

Indica que los atributos del usuario coinciden con los atributos que se vieron anteriormente para este usuario en particular. Este valor es un indicador de que el usuario se encuentra en un dispositivo de confianza que se usó anteriormente para acceder a tu aplicación para dispositivos móviles.

PROFILE_MATCH solo se devuelve en las siguientes situaciones:

Anota eventos para ajustar tu modelo específico del sitio

Para proporcionar más información a Account Defense y mejorar tu modelo de detección específico del sitio, debes anotar los eventos que evaluaste creando evaluaciones.

Para anotar una evaluación, envía una solicitud al método projects.assessments.annotate con el ID de la evaluación. En el cuerpo de esa solicitud, se incluyen etiquetas que proporcionan información adicional sobre un evento descrito en la evaluación.

Para anotar una evaluación, haz lo siguiente:

  1. Determina la información y las etiquetas que se agregarán en el cuerpo de la solicitud JSON según tu caso de uso.

    En la siguiente tabla, se enumeran las etiquetas y los valores que puedes usar para anotar eventos:

    Etiqueta Descripción Ejemplo de solicitud
    reasons Obligatorio. Una etiqueta para respaldar tus evaluaciones.

    Proporciona detalles de eventos en tiempo real en la etiqueta reasons en unos segundos o minutos después del evento, ya que influyen en la detección en tiempo real.

    Para obtener la lista de valores posibles, consulta valores de motivos.

    Ejemplo: Para detectar la apropiación de cuentas, anota si la contraseña ingresada fue correcta con los valores CORRECT_PASSWORD o INCORRECT_PASSWORD. Si implementaste tu propia MFA, puedes agregar los siguientes valores: INITIATED_TWO_FACTOR y PASSED_TWO_FACTOR o FAILED_TWO_FACTOR. 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Es opcional. Es una etiqueta para indicar la legitimidad de las evaluaciones.

    Proporciona datos sobre los eventos de registro y acceso para validar o corregir tus evaluaciones de riesgo en la etiqueta annotation.

    Los valores posibles son LEGITIMATE o FRAUDULENT.

    Puedes enviar esta información en cualquier momento o como parte de un trabajo por lotes. Sin embargo, te recomendamos que envíes esta información unos segundos o minutos después del evento, ya que influye en la detección en tiempo real.

    		 
          {
       "annotation": "LEGITIMATE"
      }
    accountId

    Es opcional. Es una etiqueta para asociar un ID de cuenta con un evento.

    Si creaste una evaluación sin un ID de cuenta, usa esta etiqueta para proporcionar el ID de cuenta de un evento siempre que esté disponible.

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

  2. Crea una solicitud de anotación con las etiquetas adecuadas.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • ASSESSMENT_ID: Es el valor del campo name que se devolvió de la llamada projects.assessments.create.
    • ANNOTATION: Opcional Es una etiqueta para indicar si la evaluación es legítima o fraudulenta.
    • REASONS: Opcional Son los motivos que respaldan tu anotación. Para obtener la lista de valores posibles, consulta valores de motivos.
    • ACCOUNT_ID: Opcional. Es el identificador asociado de forma única a la cuenta del usuario en tu app.

    Para obtener más información, consulta etiquetas para anotaciones.

    Método HTTP y URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

    Cuerpo JSON de la solicitud:

    {
  "annotation": ANNOTATION,
  "reasons": REASONS,
  "accountId": ACCOUNT_ID
}

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    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

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    $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

    Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.

Muestra de código

Java

Para autenticarte en Fraud Defense, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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);
    }
  }
}

Cómo usar e interpretar la puntuación de riesgo de la apropiación de cuentas

La función de puntuación de riesgo de apropiación de cuentas (ATO) agrega una puntuación de riesgo numérica y explicaciones legibles a la evaluación de la defensa de la cuenta. Estas estadísticas te ayudan a comprender la evaluación y fundamentar tus acciones o decisiones posteriores.

Obtén la puntuación de riesgo

Para recibir la puntuación de riesgo y los motivos de explicabilidad, envía una solicitud CreateAssessment y, luego, incluye event.userInfo.accountId en ella.

Cómo leer la puntuación de riesgo y los detalles

La puntuación de riesgo y los motivos de explicabilidad se encuentran en el objeto accountDefenderAssessment.accountTakeoverVerdict de la respuesta de la evaluación.

  • Puntuación de riesgo: accountDefenderAssessment.accountTakeoverVerdict.risk
  • Motivos de riesgo: accountDefenderAssessment.accountTakeoverVerdict.riskReasons
  • Motivos de confianza: accountDefenderAssessment.accountTakeoverVerdict.trustReasons

En el siguiente fragmento, se muestra un ejemplo de los campos en una respuesta de evaluación:

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

Cómo interpretar la puntuación de riesgo de ATO

Cuando uses la puntuación de riesgo, establece un umbral para determinar cuándo tomar medidas de protección.

Usa la puntuación de riesgo de la ATO como alternativa a la etiqueta SUSPICIOUS_LOGIN_ACTIVITY. No uses la puntuación de riesgo y la etiqueta para activar la aplicación de medidas en la misma evaluación. Puedes configurar tu lógica de aplicación en función de si la puntuación de riesgo supera el umbral o de la presencia de la etiqueta. En general, la puntuación de riesgo ofrece una evaluación más detallada.

Te recomendamos que evalúes el rendimiento de la puntuación de riesgo con un umbral adecuado en el tráfico de tu plataforma antes de usarla para aplicar medidas.

Para actuar en función de la puntuación de riesgo, implementa una verificación en tu backend, como se muestra en el siguiente fragmento:

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

Umbrales de puntuación de riesgo estándar

En la siguiente tabla, se proporcionan los umbrales de puntuación de riesgo estándares y sus tasas de falsos positivos (FPR) esperadas. Elige un umbral según el FPR aceptable. El rendimiento puede variar, por lo que es posible que debas ajustar tu umbral según el rendimiento observado.

FPR esperado Umbral de la puntuación de riesgo
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

Cómo ajustar tu límite

Si el FPR observado es demasiado alto, aumenta el umbral. Si la recuperación observada es demasiado baja y puedes tolerar una tasa de FPR más alta, disminuye el umbral.

Cómo calcular valores intermedios

Para estimar el FPR de un umbral entre los valores estándar, usa la interpolación lineal. En el siguiente ejemplo, se muestra cómo calcular el FPR para un umbral 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 un umbral para un FPR específico, interpole entre los valores estándar. En el siguiente ejemplo, se muestra cómo encontrar el umbral para un FPR del 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

Se estima que un umbral de 0.475 genera un 5% de FPR.

Interpreta los motivos de explicabilidad

Los motivos de explicabilidad proporcionan estadísticas sobre los factores que influyen en la puntuación de riesgo. Usa estos motivos para definir mejor tu toma de decisiones.

  • Motivos de riesgo: Indican factores asociados a un mayor riesgo de apropiación de cuentas.
  • Motivos de confianza: Indican factores que sugieren legitimidad.

Los motivos de riesgo y confianza pueden aparecer para cualquier puntuación de riesgo determinada.

Motivo Tipo Interpretación
PROFILE_MATCH Confianza La solicitud coincide con un perfil de confianza asociado a esta cuenta. Esto equivale a la etiqueta AccountDefenderLabel.PROFILE_MATCH.
ACCOUNT_HISTORY_REPUTABLE Confianza La actividad histórica de la cuenta es confiable. Es poco probable que la cuenta se haya visto comprometida en el pasado.
CLIENT_HISTORICAL_BOT_ACTIVITY Riesgo Se observó que el cliente envió tráfico similar al de un bot a este sitio en el pasado. Este motivo incorpora la reputación histórica y señala que se sabe que el cliente usa bots, incluso si la solicitud actual la realiza un humano.
ACCOUNT_IN_LARGE_RELATED_GROUP Riesgo La cuenta forma parte de un grupo grande de cuentas relacionadas, lo que indica que puede ser parte de una red fraudulenta. Las cuentas relacionadas se identifican en función de tener patrones de tráfico y características de solicitud similares.
CLIENT_ACCESSED_MANY_ACCOUNTS Riesgo Se observó que el cliente accedió a muchas cuentas en este sitio.

¿Qué sigue?