Crear evaluaciones de sitios web

En esta página se explica cómo crear una evaluación para que tu backend pueda verificar la autenticidad del token que envía reCAPTCHA. reCAPTCHA envía una respuesta cifrada, el token de respuesta de reCAPTCHA (también conocido como token), cuando el usuario final activa una acción HTML.

Para cualquier tipo de integración de claves de reCAPTCHA (casilla o puntuación), debes crear una evaluación para analizar los resultados de execute() en tu backend. Para ello, envía el token generado al endpoint de evaluación. reCAPTCHA procesa el token enviado e informa de su validez y puntuación.

Las primeras 10.000 evaluaciones mensuales de reCAPTCHA son gratuitas. Para seguir creando evaluaciones después de alcanzar el límite de uso mensual gratuito (10.000 evaluaciones al mes), debes habilitar la facturación en tu Google Cloud proyecto. Para obtener más información sobre la facturación de reCAPTCHA, consulta Información sobre la facturación.

Antes de empezar

1. Prepara tu entorno para reCAPTCHA.
2. Asegúrate de que tienes el siguiente rol de gestión de identidades y accesos: Agente de reCAPTCHA Enterprise (roles/recaptchaenterprise.agent).
3. Instala claves basadas en una puntuación, claves de casilla o claves de verificación basadas en políticas en tu sitio web.
4. Configura la autenticación en reCAPTCHA.

   El método de autenticación que elijas dependerá del entorno en el que se configure reCAPTCHA. La siguiente tabla te ayudará a elegir el método de autenticación adecuado y la interfaz compatible para configurar la autenticación:

   Entorno	Interfaz	Método de autenticación
   Google Cloud	REST Bibliotecas de cliente	Usa cuentas de servicio asociadas.
   On-premise u otro proveedor de servicios en la nube	REST	Usa claves de API o la federación de identidades de cargas de trabajo. Si quieres usar claves de API, te recomendamos que las protejas aplicando restricciones a las claves de API.
   	Bibliotecas de cliente	Utiliza lo siguiente: En Python o Java, usa claves de API o la federación de identidades de cargas de trabajo. Si quieres usar claves de API, te recomendamos que las protejas aplicando restricciones a las claves de API. En otros idiomas, usa Federación de identidades de cargas de trabajo.

Recuperar un token

Obtén un token de las páginas web de una de las siguientes formas:

• El valor resuelto de la promesa devuelta por la llamada a grecaptcha.enterprise.execute().
• Utilice el parámetro POST g-recaptcha-response cuando un usuario envíe un formulario en su sitio.
• Como un argumento de cadena para tu función de retrollamada si se especifica data-callback en el atributo de la etiqueta HTML g-recaptcha o en el parámetro de retrollamada del método grecaptcha.enterprise.render.

Solo puedes acceder al token de cada usuario una vez. Si necesitas evaluar una acción posterior que realice un usuario en tu sitio o si un token caduca antes de que se cree una evaluación, debes llamar a execute() de nuevo para generar un token nuevo.

Crear una evaluación

Después de configurar la autenticación, crea una evaluación enviando una solicitud a la API de reCAPTCHA Enterprise o usando las bibliotecas de cliente de reCAPTCHA.

Para mejorar la detección, le recomendamos que transmita los siguientes valores adicionales al crear evaluaciones:

• userAgent: el user-agent se incluye en la solicitud HTTP en el encabezado de la solicitud. Para obtener más información, consulta Información sobre el encabezado de solicitud User-Agent en la documentación de Mozilla Developer Network.
• userIpAddress: La dirección IP del usuario que envía una solicitud a tu backend está disponible en la solicitud HTTP. Si usas un servidor proxy, la dirección IP está disponible en el encabezado de solicitud X-Forwarded-For. Para obtener más información sobre cómo obtener la dirección IP, consulta X-Forwarded-For.
• ja4: JA4 es un método de código abierto para crear huellas digitales de clientes TLS. Para obtener más información sobre cómo crear una huella digital JA4, consulta la documentación de JA4 en GitHub.
• ja3: JA3 es un método de código abierto para crear huellas digitales de clientes TLS. Para obtener más información sobre cómo crear una huella digital JA3, consulta la documentación de JA3 en GitHub.

Esto ayuda a proteger tu sitio web y tus aplicaciones móviles frente a patrones de ataque avanzados y abusos dirigidos por personas.

El proceso para crear una evaluación es el mismo para las claves basadas en una puntuación, las claves de casilla y las claves de desafío basadas en políticas.

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

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja4": "JA4",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  }
}

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

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
  },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
 "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja4": "JA4",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  }
}

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

$headers = @{  }

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?key=API_KEY" | Select-Object -Expand Content

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
  },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userAgent": "USER_AGENT",
    "userIpAddress": "USER_IP_ADDRESS",
    "ja3": "JA3",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}

  using System;
  using Google.Api.Gax.ResourceNames;
  using Google.Cloud.RecaptchaEnterprise.V1;

  public class CreateAssessmentSample
  {
      // Create an assessment to analyze the risk of a UI action.
      // projectID: Google Cloud project ID.
      // recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use reCAPTCHA Enterprise.
      // token: The token obtained from the client on passing the recaptchaKey.
      // recaptchaAction: Action name corresponding to the token.
      public void createAssessment(string projectID = "project-id", string recaptchaKey = "recaptcha-key",
          string token = "action-token", string recaptchaAction = "action-name")
      {

          // Create the client.
          // TODO: To avoid memory issues, move this client generation outside
          // of this example, and cache it (recommended) or call client.close()
          // before exiting this method.
          RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.Create();

          ProjectName projectName = new ProjectName(projectID);

          // Build the assessment request.
          CreateAssessmentRequest createAssessmentRequest = new CreateAssessmentRequest()
          {
              Assessment = new Assessment()
              {
                  // Set the properties of the event to be tracked.
                  Event = new Event()
                  {
                      SiteKey = recaptchaKey,
                      Token = token,
                      ExpectedAction = recaptchaAction
                  },
              },
              ParentAsProjectName = projectName
          };

          Assessment response = client.CreateAssessment(createAssessmentRequest);

          // Check if the token is valid.
          if (response.TokenProperties.Valid == false)
          {
              System.Console.WriteLine("The CreateAssessment call failed because the token was: " +
                  response.TokenProperties.InvalidReason.ToString());
              return;
          }

          // Check if the expected action was executed.
          if (response.TokenProperties.Action != recaptchaAction)
          {
              System.Console.WriteLine("The action attribute in reCAPTCHA tag is: " +
                  response.TokenProperties.Action.ToString());
              System.Console.WriteLine("The action attribute in the reCAPTCHA tag does not " +
                  "match the action you are expecting to score");
              return;
          }

          // Get the risk score and the reasons.
          // For more information on interpreting the assessment,
          // see: https://cloud.google.com/recaptcha/docs/interpret-assessment
          System.Console.WriteLine("The reCAPTCHA score is: " + ((decimal)response.RiskAnalysis.Score));

          foreach (RiskAnalysis.Types.ClassificationReason reason in response.RiskAnalysis.Reasons)
          {
              System.Console.WriteLine(reason.ToString());
          }
      }

      public static void Main(string[] args)
      {
          new CreateAssessmentSample().createAssessment();
      }
  }

  import (
    "context"
    "fmt"

    recaptcha "cloud.google.com/go/recaptchaenterprise/v2/apiv1"
    recaptchapb "cloud.google.com/go/recaptchaenterprise/v2/apiv1/recaptchaenterprisepb"
  )

  func main() {
    // TODO(developer): Replace these variables before running the sample.
    projectID := "project-id"
    recaptchaKey