Configurar reCAPTCHA exprés en servidores de aplicaciones

reCAPTCHA Express se puede configurar en un servidor de aplicaciones cuando no es posible realizar una integración del lado del cliente con el SDK de JavaScript o para móviles de reCAPTCHA. Por ejemplo, la protección de los endpoints de las APIs.

reCAPTCHA Express es una función que te permite crear evaluaciones sin integración del lado del cliente ni señales del lado del cliente. reCAPTCHA Express solo usa señales del backend para generar una puntuación de riesgo de reCAPTCHA. Puedes usar esta puntuación de riesgo para decidir si quieres atender la solicitud, redirigir a una página de verificación o registrarla para analizarla más adelante.

Antes de empezar

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Anota el ID de tu proyecto Google Cloud para usarlo más adelante.

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the reCAPTCHA Enterprise API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  4. Crea una clave de API para la autenticación:

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

      Ir a Credenciales

    2. Haz clic en Crear credenciales y, a continuación, selecciona Clave de API.

    3. Anota la clave de API para usarla más adelante.

Crear una clave exprés de reCAPTCHA

Para implementar reCAPTCHA exprés, crea una clave de reCAPTCHA exprés.

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

  2. gcloud

    Para crear claves de reCAPTCHA, usa el comando gcloud recaptcha keys create.

    Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

    • INTEGRATION_TYPE: tipo de integración. Especifica score.
    • DISPLAY_NAME: nombre de la clave. Normalmente, el nombre de un sitio.

    Ejecuta el comando gcloud recaptcha keys create:

    Linux, macOS o Cloud Shell

    gcloud recaptcha keys create \
--express \
--display-name=DISPLAY_NAME

    Windows (PowerShell)

    gcloud recaptcha keys create `
--express `
--display-name=DISPLAY_NAME

    Windows (cmd.exe)

    gcloud recaptcha keys create ^
--express ^
--display-name=DISPLAY_NAME

    La respuesta contiene la clave de reCAPTCHA recién creada.

    REST

    Para obtener información de referencia de la API sobre los tipos de clave y los tipos de integración, consulta Clave y Tipo de integración.

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • INTEGRATION_TYPE: tipo de integración. Especifica score.
    • DISPLAY_NAME: nombre de la clave. Normalmente, el nombre de un sitio.
    • DEFAULT_SCORE_THRESHOLD: en el caso de las claves de verificación basadas en políticas, define el umbral de verificación universal de la clave cuando no se ha definido un umbral de puntuación personalizado. Esta función está en versión preliminar.
    • ACTION_SCORE_THRESHOLDS: en el caso de las claves de verificación basadas en políticas, se especifica la acción y la puntuación de umbral correspondiente, que debe estar entre 0,0 y 1,0. Por ejemplo, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. Esta función está en versión preliminar.

    Método HTTP y URL: 

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

    Cuerpo JSON de la solicitud: 

    
{
  "displayName": "DISPLAY_NAME",
  "expressSettings": {}
}

    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/keys"

    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/keys" | Select-Object -Expand Content

    Deberías recibir una respuesta JSON similar a la siguiente:

    
{
  "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
"displayName": "DISPLAY_NAME,
"expressSettings": {
}
}

    3. Graba tu llave de acceso para usarla más adelante.

    Crear una evaluación

    Para hacer una solicitud de reCAPTCHA desde el servidor de tu aplicación, crea una evaluación con el método projects.assessments.create.

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • API_KEY: la clave de API que has creado para la autenticación.
    • EXPRESS_KEY: clave express de reCAPTCHA que has creado para tu aplicación.
    • USER_IP_ADDRESS: la dirección IP de la solicitud del dispositivo del usuario relacionada con este evento.
    • HEADER_INFO: opcional. Los encabezados HTTP que el cliente ha enviado al servidor de tu aplicación. Es una matriz de cadenas que contiene encabezados de solicitud en el formato `[clave:valor]`. Por ejemplo, `[clave:valor, clave:valor,...]`. Le recomendamos que comparta tantos encabezados como sea posible en el orden requerido. Asegúrate de que el orden de los encabezados sea coherente en todas las solicitudes de la misma sesión.
    • JA3_FINGERPRINT: opcional. JA3 es una huella digital MD5 de determinados campos del paquete ClientHello de TLS. Para obtener más información, consulta JA3: un método para crear perfiles de clientes SSL/TLS.
    • URI_NAME: opcional. El URI al que accede el usuario.
    • USER_AGENT: opcional. El user-agent que está presente en la solicitud del dispositivo del usuario relacionada con este evento.
    • ACCOUNT_ID: opcional. Un identificador único y persistente de la cuenta del usuario, como un nombre de cuenta cifrado con hash.

    Método HTTP y URL: 

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

    Cuerpo JSON de la solicitud: 

    
{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "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 "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

    PowerShell

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

    $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

    Deberías recibir una respuesta JSON similar a la siguiente:

    {
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

    Interpretar las puntuaciones

    reCAPTCHA express solo devuelve dos puntuaciones: 0.3 y 0.7. 0.3 indica que la interacción del usuario supone un mayor riesgo y es probable que sea fraudulenta, mientras que 0.7 indica que la interacción del usuario supone un riesgo bajo y es probable que sea legítima.

    Si faltan señales, reCAPTCHA express devuelve 0.7 de forma predeterminada.

    Siguientes pasos