Configura reCAPTCHA Express en servidores de aplicaciones

reCAPTCHA Express se puede configurar en un servidor de aplicaciones cuando no es factible una integración del lado del cliente con el SDK de JavaScript o para dispositivos móviles de reCAPTCHA. Por ejemplo, protección para los extremos de la API.

reCAPTCHA Express es una función que te permite crear evaluaciones sin una integración del cliente ni indicadores del cliente. reCAPTCHA Express solo usa indicadores de backend para generar una puntuación de riesgo de reCAPTCHA. Puedes usar esta puntuación de riesgo para decidir si publicar la solicitud, redireccionar a una página de desafío o registrarla para su análisis posterior.

Antes de comenzar

  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

    Registra tu Google Cloud ID del proyecto 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 consola de Google Cloud , ve a la página Credenciales.

      Ir a Credenciales

    2. Haz clic en Crear credenciales y selecciona Clave de API.

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

Crea una clave de reCAPTCHA Express

Para implementar reCAPTCHA Express, crea una clave de reCAPTCHA Express.

  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 cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

    • INTEGRATION_TYPE: Tipo de integración. Especifica score.
    • DISPLAY_NAME: Nombre de la clave. Por lo general, es 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 claves y los tipos de integración, consulta Key y Integration type.

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

    • INTEGRATION_TYPE: Tipo de integración. Especifica score.
    • DISPLAY_NAME: Nombre de la clave. Por lo general, es el nombre de un sitio.
    • DEFAULT_SCORE_THRESHOLD: Para las claves de desafío basadas en políticas, este parámetro define el umbral de desafío universal para la clave cuando no se define un umbral de puntuación personalizado. Esta función está en vista previa.
    • ACTION_SCORE_THRESHOLDS: Para las claves de desafío basadas en políticas, se especifica la acción y la puntuación de umbral correspondiente entre 0.0 y 1.0. Por ejemplo, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}' Esta función está en vista previa.

    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 que se muestra a continuación:

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

    3. Registra tu clave de Express para usarla más adelante.

    Crea una evaluación

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

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

    • API_KEY: Es la clave de API que creaste para la autenticación.
    • EXPRESS_KEY: Es la clave de reCAPTCHA Express que creaste para tu aplicación.
    • USER_IP_ADDRESS: Es la dirección IP de la solicitud del dispositivo del usuario relacionada con este evento.
    • HEADER_INFO: Opcional Son los encabezados HTTP que el cliente envió al servidor de aplicaciones. Es un array de cadenas que contiene encabezados de solicitud en el formato "[clave:valor]". Por ejemplo, `[key:value, key:value,...]`. Te recomendamos que compartas la mayor cantidad posible de encabezados 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 ciertos 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 Es el URI al que accede el usuario.
    • USER_AGENT: Opcional Es el usuario-agente presente en la solicitud del dispositivo del usuario relacionado con este evento.
    • ACCOUNT_ID: Opcional Es un identificador único y persistente de la cuenta del usuario, como un nombre de cuenta hasheado.

    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 que se muestra a continuación:

    {
  "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 representa más riesgo y es probable que sea fraudulenta, y 0.7 indica que la interacción del usuario representa un riesgo bajo y es probable que sea legítima.

    Si no hay suficientes indicadores, reCAPTCHA Express devuelve 0.7 de forma predeterminada.

    ¿Qué sigue?