Detecta y evita actividades fraudulentas relacionadas con las cuentas en sitios web

En este documento, se muestra cómo usar el defensor de cuentas de reCAPTCHA para detectar y evitar actividades fraudulentas relacionadas con las cuentas en los sitios web.

reCAPTCHA te ayuda a proteger acciones fundamentales, como el acceso y la confirmación de la compra. Sin embargo, existen muchas formas sutiles de abuso de cuentas que se pueden detectar observando el comportamiento de un usuario específico en un sitio web durante un período. La protección de cuentas de reCAPTCHA ayuda a identificar estos tipos de abuso sutil creando un modelo específico del sitio para que tu sitio web detecte una tendencia de comportamiento sospechoso o un cambio en la actividad. Cuando usas el modelo específico del sitio, la protección de cuentas de reCAPTCHA 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

En función del análisis de la protección de cuentas de reCAPTCHA 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.
  • Mitiga las apropiaciones de cuentas exitosas.
  • Otorga acceso solo a las solicitudes que provienen de cuentas de usuario legítimas.
  • Reduce los inconvenientes para los usuarios que acceden desde uno de sus dispositivos de confianza.

Antes de comenzar

  1. Prepara tu entorno para reCAPTCHA.
  2. Crea una clave de sitio basada en la puntuación.

Configura tus páginas web para la protección de cuentas de reCAPTCHA

La protección de cuentas de reCAPTCHA 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 la protección de cuentas de reCAPTCHA y crear y mejorar tu modelo específico del sitio, haz lo siguiente:

  1. Habilita la recopilación de datos de telemetría horizontal.
  2. Informes sobre acciones clave de los usuarios
  3. Evalúa los eventos de usuario críticos.
  4. Anota los eventos de los usuarios para ajustar tu modelo específico del sitio.

Habilita la recopilación de datos de telemetría horizontal

El defensor de cuentas de reCAPTCHA requiere una vista completa de las acciones del usuario, como si accedió o está accediendo a su cuenta. Para habilitar la recopilación pasiva de datos de telemetría horizontal por parte del defensor de cuentas de reCAPTCHA, carga la secuencia de comandos de JavaScript de reCAPTCHA con la clave de sitio basada en la puntuación que creaste en segundo plano de todas las páginas web que forman parte de tu flujo de trabajo del usuario.

En el siguiente ejemplo, se muestra cómo cargar la secuencia de comandos de reCAPTCHA en JavaScript en una página web.

    <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

Genera informes sobre las acciones críticas de los usuarios

Para detectar patrones de actividad sospechosos y comprender mejor los patrones de actividad típicos en tu sitio, el defensor de cuentas de reCAPTCHA necesita información sobre las acciones críticas del usuario. Por lo tanto, informa las acciones críticas del usuario en las páginas web llamando a grecaptcha.enterprise.execute() en esas acciones críticas del usuario.

Recomendamos informar todas las acciones críticas del usuario, ya que esto ayuda a la recopilación de indicadores adicionales. Para cada acción del usuario que desees informar, reemplaza el valor del parámetro action de grecaptcha.enterprise.execute() por un nombre de acción que la describa.

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

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

Accede al sitio web.
REGISTRATION Registro en el sitio web
SECURITY_QUESTION_CHANGE Solicita cambiar la pregunta de seguridad.
PASSWORD_RESET Solicita el restablecimiento de la contraseña.
PHONE_NUMBER_UPDATE Solicitud para actualizar el número de teléfono
EMAIL_UPDATE Solicitud para actualizar la dirección de correo electrónico.
ACCOUNT_UPDATE Solicitar la actualización de la información relacionada con la cuenta, como los detalles de contacto
TRIGGER_MFA Es una acción que activa un desafío de MFA.
REDEEM_CODE Solicita canjear el código.
LIST_PAYMENT_METHODS Recupera la lista de formas de pago.

En el siguiente ejemplo, se muestra cómo llamar a grecaptcha.enterprise.execute() en una actualización de número de teléfono:

    <script>
    function onClick(e) {
      e.preventDefault();
      grecaptcha.enterprise.ready(async () => {
        const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'PHONE_NUMBER_UPDATE'});
      });
    }
    </script>

Evalúa los eventos de usuario críticos

Cuando llamas a grecaptcha.enterprise.execute() en una acción del usuario, se genera un token. Para los eventos del usuario críticos, como los accesos correctos y fallidos, los registros y las acciones de los usuarios que accedieron, crea una evaluación para evaluar los resultados de la llamada a grecaptcha.enterprise.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 accesos riesgosos e investigar cuentas de interés.

El defensor de cuentas de reCAPTCHA requiere que proporciones un identificador de cuenta estable para atribuir la actividad del usuario, como las solicitudes de acceso, las solicitudes de acceso y las solicitudes de registro, a una cuenta específica. Esto ayuda al defensor de cuentas de reCAPTCHA a comprender los patrones de actividad del usuario y a crear un modelo de actividad para cada cuenta para 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 estable, puedes usarlo como accountId. Cuando proporcionas esos identificadores entre sitios (identificadores que se pueden volver a usar en varios sitios), reCAPTCHA usa esta información para mejorar la protección de tus cuentas de usuario en función de 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.

Como alternativa, si tienes un ID de usuario interno asociado de forma exclusiva con cada cuenta, puedes proporcionarlo como accountId.

Con codificación hash o encriptado

Si no tienes un ID de usuario interno asociado de forma exclusiva con cada cuenta, puedes convertir cualquier identificador estable en un identificador de cuenta opaco y específico del sitio. Este identificador aún es necesario para que el defensor de cuentas de reCAPTCHA comprenda los patrones de actividad del usuario y detecte comportamientos anómalos, pero no se comparte con otros sitios.

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

  • encriptación (recomendado): Encripta el identificador de la cuenta con un método de encriptación determinista que genere un texto cifrado estable. Para obtener instrucciones detalladas, consulta Cómo encriptar datos de forma determinista. Cuando eliges la criptografía simétrica en lugar del hash, no es necesario que mantengas una asignación entre tus identificadores de usuario y los identificadores de usuario opacos correspondientes. Desencripta los identificadores opacos que muestra reCAPTCHA para convertirlos en el identificador del usuario.

  • codificación hash: Te recomendamos que codifiques el identificador de cuenta con el método SHA256-HMAC con una sal personalizada de tu elección. Debido a que los hash son unidireccionales, debes mantener una asignación entre los hash generados y tus identificadores de usuario para que puedas 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, que pueden no ser estables, para algunas solicitudes específicas. Los identificadores de cuenta específicos del contexto que se proporcionan además de accountId ayudan a la protección de cuentas de reCAPTCHA a comprender mejor la actividad del usuario y detectar intentos de apropiación de cuentas para mantenerlas seguras. Cuando proporcionas identificadores adicionales, reCAPTCHA usa esta información para mejorar la protección de tus cuentas de usuario en función de 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

Adjunta 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 relevantes 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: El ID del proyecto de Google Cloud.
  • TOKEN: Token que se muestra a partir de la llamada grecaptcha.enterprise.execute()
  • KEY_ID: Clave de reCAPTCHA asociada con el sitio
  • ACCOUNT_ID: Es el identificador que se asocia de forma exclusiva con la cuenta de usuario de tu sitio web.
  • EMAIL_ADDRESS: Opcional Una dirección de correo electrónico asociada con esta solicitud, si la hay
  • PHONE_NUMBER: Opcional Un número de teléfono asociado a esta solicitud, si corresponde
  • USERNAME: Opcional Un nombre de usuario asociado con 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,
    "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"]
  }
}

Muestra de código

Java

Para autenticarte en reCAPTCHA, configura las credenciales predeterminadas de la aplicación. Si deseas 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 del usuario críticos

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 muestra un ID de evaluación que debes usar cuando anotas eventos del usuario.

El siguiente ejemplo es una respuesta JSON de ejemplo:

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

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 uso excesivo de credenciales o de apropiación de cuentas.
SUSPICIOUS_ACCOUNT_CREATION Indica que la solicitud representa un riesgo alto de creación de cuentas abusivas.
PROFILE_MATCH

Indica que los atributos del usuario coinciden con los que se vieron antes para este usuario en particular. Este valor es un indicador de que el usuario se encuentra en un dispositivo de confianza que se usó antes para acceder a tu sitio web.

PROFILE_MATCH solo se muestra en las siguientes situaciones:

  • Usas la autenticación de varios factores(MFA) o de 2 factores(2FA), y el defensor de cuentas de reCAPTCHA marca los perfiles de usuario como de confianza después de que los usuarios superan el desafío de MFA o 2FA.
  • Anotas las evaluaciones como LEGITIMATE o PASSED_TWO_FACTOR, y el defensor de cuentas de reCAPTCHA marca el perfil de usuario correspondiente como de confianza.
RELATED_ACCOUNTS_NUMBER_HIGH Indica que la solicitud tiene una gran cantidad de cuentas relacionadas. No implica necesariamente que la cuenta sea mala, pero es posible que requiera una investigación más a fondo.

Anota eventos para ajustar tu modelo específico del sitio

Para proporcionar más información a la protección de cuentas de reCAPTCHA 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, incluye 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 debes agregar en el cuerpo JSON de la solicitud 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 del evento 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 apropiaciones de cuentas, anota si la contraseña ingresada era correcta con valores CORRECT_PASSWORD o INCORRECT_PASSWORD. Si implementaste tu propia MFA, puedes agregar los siguientes valores: INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR o FAILED_TWO_FACTOR. 

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

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

    Valores posibles: 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 influyen en la detección en tiempo real.

    		 
          {
       "annotation": "LEGITIMATE"
      }
    accountId

    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 muestra desde la llamada projects.assessments.create.
    • ANNOTATION: Opcional Es una etiqueta que indica si la evaluación es legítima o fraudulenta.
    • REASONS: Opcional Razones 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 exclusiva con la cuenta de usuario en tu sitio web.

    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 reCAPTCHA, configura las credenciales predeterminadas de la aplicación. Si deseas 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);
    }
  }
}

Habilita la protección de cuentas de reCAPTCHA

Después de configurar tus páginas web para la protección de cuentas de reCAPTCHA, puedes habilitarla.

  1. En la consola de Google Cloud, ve a la página reCAPTCHA.

    Ve a reCAPTCHA

  2. Verifica que el nombre de tu proyecto aparezca en el selector de recursos en la parte superior de la página.

    Si no ves el nombre de tu proyecto, haz clic en el selector de recursos y, luego, selecciona tu proyecto.

  3. Haz clic en Configuración.

  4. En el panel Defensor de cuentas, haz clic en Configurar.

  5. En el cuadro de diálogo Configurar Account Defender, haz clic en Habilitar y, luego, en Guardar.

La habilitación de la protección de cuentas de reCAPTCHA puede tardar algunas horas en propagarse a nuestros sistemas. Después de que la habilitación de la función se propague a nuestros sistemas, deberías comenzar a recibir respuestas relacionadas con el defensor de cuentas como parte de las evaluaciones.

¿Qué sigue?