Integración con Google Cloud Armor para aplicaciones móviles

En este documento se explica cómo integrar las funciones de reCAPTCHA con Cloud Armor en aplicaciones móviles.

Para completar la integración, debes implementar una o varias funciones de reCAPTCHA y configurar políticas de seguridad de Cloud Armor. Sin embargo, solo puedes implementar tokens de acción de reCAPTCHA para integrar Cloud Armor en aplicaciones móviles.

Antes de empezar

  1. Habilita la API de reCAPTCHA Enterprise.

    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

  2. Identifica las acciones que quieras proteger.

Implementar tokens de acción de reCAPTCHA

Debes tener reCAPTCHA en tu aplicación móvil para generar tokens de acción. Una vez que reCAPTCHA genera un token de acción, lo adjuntas a un encabezado de solicitud predefinido en cualquier lugar en el que necesites proteger una acción del usuario, como checkout. De forma predeterminada, los tokens de acción son válidos durante 30 minutos, pero pueden variar en función del tráfico. Debes adjuntar el token de acción a un encabezado de solicitud predefinido antes de que caduque para que Cloud Armor pueda evaluar los atributos del token.

Para implementar un token de acción de reCAPTCHA, sigue estos pasos:

  1. Crea una clave action-token para tu aplicación móvil.

    Consola

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

      Ir a reCAPTCHA

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

      Si no ves el nombre de tu proyecto, haz clic en el selector de recursos y, a continuación, selecciona tu proyecto.

    3. Haz clic en Crear clave.
    4. En el campo Nombre visible, introduce el nombre visible de la clave.
    5. En función del tipo de aplicación para la que quieras crear las claves de reCAPTCHA para WAF, realiza la acción correspondiente:

      6. Crear claves de reCAPTCHA para WAF en aplicaciones iOS

      Te recomendamos que crees una clave de reCAPTCHA por cada aplicación iOS.

      1. En Tipo de aplicación, selecciona iOS.
        1. En la sección Lista de IDs de paquete de iOS, haga clic en Añadir ID de paquete de iOS.

        2. En el campo ID de paquete, introduce el nombre de tu ID de paquete de iOS.

        3. Opcional: Para añadir otro ID de paquete, haga clic en Añadir ID de paquete de iOS e introduzca el nombre del ID de paquete de iOS en el campo ID de paquete.
        4. Para proteger la clave de reCAPTCHA de tus IDs de paquete, asegúrate de que el interruptor Inhabilitar verificación de ID de paquete esté desactivado.

        5. Opcional: Proporciona la configuración de desarrollador de Apple.

          Le recomendamos que proporcione estos datos, ya que permiten que reCAPTCHA proporcione puntuaciones de riesgo más precisas para su tráfico.

          Introduce la siguiente información:

          • Clave privada (.p8): se genera en el centro para desarrolladores de Apple, en Certificates, Identifiers & Profiles (Certificados, identificadores y perfiles).
          • Identificador de clave: el identificador de clave de desarrollador de Apple (cadena de 10 caracteres).
          • ID de equipo: el ID de equipo de Apple (cadena de 10 caracteres) propietario del perfil de aprovisionamiento que se usa para compilar tu aplicación.
        6. Opcional: Haz clic en Siguiente paso (opcional).
          1. Para crear una clave de reCAPTCHA para WAF, sigue estos pasos:
            1. En Configuración adicional, activa la opción
            2. En Ajustes adicionales, activa el interruptor ¿Vas a implementar esta clave en un firewall de aplicaciones web (WAF)?.
            3. En las opciones de Servicio, selecciona Cloud Armor.
            4. En las opciones de Función, selecciona Acción.

          2. En tu entorno de no producción, si quieres especificar una puntuación que quieres que devuelva la clave cuando se creen evaluaciones, haz lo siguiente:

            1. En Configuración adicional, haz clic en el interruptor ¿Estás creando esta clave solo con fines de prueba?.
            2. Usa el control deslizante Definir puntuación para especificar una puntuación entre 0 y 1,0.
        7. Haz clic en Crear clave.

          8. La clave que has creado se muestra en la página Claves de reCAPTCHA.

      Crear claves de reCAPTCHA para WAF para aplicaciones Android

      1. En Tipo de aplicación, selecciona Android.
      2. En la sección Lista de paquetes de Android, haga clic en Añadir paquete de Android.
      3. En el campo Paquete de Android, introduzca el nombre de su paquete de Android.
      4. Opcional: Para añadir otro paquete, haz clic en Añadir paquete de Android e introduce el nombre de otro paquete de Android en el campo Paquete de Android.
      5. Para obligar a que la clave de reCAPTCHA solo se use en tu aplicación, desactiva el interruptor Inhabilitar verificación del nombre del paquete.
      6. Si quieres crear una clave para una aplicación que esté disponible en otras tiendas de aplicaciones además de Google Play Store, activa Admite aplicaciones distribuidas fuera de Google Play Store.
      7. Opcional: Haz clic en Siguiente paso (opcional).
        1. Para crear una clave de reCAPTCHA para WAF, sigue estos pasos:
          1. En Configuración adicional, activa la opción
          2. En Ajustes adicionales, activa el interruptor ¿Vas a implementar esta clave en un firewall de aplicaciones web (WAF)?.
          3. En las opciones de Servicio, selecciona Cloud Armor.
          4. En las opciones de Función, selecciona Acción.

        2. En tu entorno de no producción, si quieres especificar una puntuación que quieres que devuelva la clave cuando se creen evaluaciones, haz lo siguiente:

          1. En Configuración adicional, haz clic en el interruptor ¿Estás creando esta clave solo con fines de prueba?.
          2. Usa el control deslizante Definir puntuación para especificar una puntuación entre 0 y 1,0.
      8. Haz clic en Crear clave.

        9. La clave que has creado se muestra en la página Claves de reCAPTCHA.

    gcloud (iOS)

    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:

    • DISPLAY_NAME: nombre de la clave. Normalmente, el nombre de un sitio.
    • BUNDLE_IDs: IDs de paquete de iOS de las aplicaciones que pueden usar la clave. Especifique varios IDs de paquete en una lista separada por comas.
    • WAF_FEATURE: nombre de la función de WAF. Especifica action-token.
    • WAF_SERVICE: nombre del proveedor de servicios de WAF. Especifica CA para Cloud Armor.

    Ejecuta el comando gcloud recaptcha keys create:

    Linux, macOS o Cloud Shell

    gcloud recaptcha keys create \
--display-name=DISPLAY_NAME  \
--ios --bundle-ids=BUNDLE_IDs \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

    Windows (PowerShell)

    gcloud recaptcha keys create `
--display-name=DISPLAY_NAME  `
--ios --bundle-ids=BUNDLE_IDs `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

    Windows (cmd.exe)

    gcloud recaptcha keys create ^
--display-name=DISPLAY_NAME  ^
--ios --bundle-ids=BUNDLE_IDs ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

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

    gcloud (Android)

    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:

    • DISPLAY_NAME: nombre de la clave. Normalmente, el nombre de un sitio.
    • PACKAGE_NAMES: nombres de paquetes Android de las aplicaciones que pueden usar la clave. Especifica varios nombres de paquetes en una lista separada por comas.
    • WAF_FEATURE: nombre de la función de WAF. Especifica action-token.
    • WAF_SERVICE: nombre del proveedor de servicios de WAF. Especifica CA para Cloud Armor.

    Ejecuta el comando gcloud recaptcha keys create:

    Linux, macOS o Cloud Shell

    gcloud recaptcha keys create \
--display-name=DISPLAY_NAME  \
--android --package-names=PACKAGE_NAMES \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

    Windows (PowerShell)

    gcloud recaptcha keys create `
--display-name=DISPLAY_NAME  `
--android --package-names=PACKAGE_NAMES `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

    Windows (cmd.exe)

    gcloud recaptcha keys create ^
--display-name=DISPLAY_NAME  ^
--android --package-names=PACKAGE_NAMES ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

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

    REST (iOS)

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

    • DISPLAY_NAME: nombre de la clave. Normalmente, el nombre de una aplicación.
    • BUNDLE_IDs: IDs de paquete de iOS de las aplicaciones que pueden usar la clave. Especifique varios IDs de paquete en una lista separada por comas.
    • WAF_FEATURE: nombre de la función de WAF. Especifica action-token.
    • WAF_SERVICE: nombre del proveedor de servicios de WAF. Especifica CA para Cloud Armor.

    Método HTTP y URL: 

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

    Cuerpo JSON de la solicitud: 

    {
  "displayName": "DISPLAY_NAME",
  "iosSettings": {
 "allowedBundleIds": "BUNDLE_IDS"
 },
   'wafSettings': "  {
       "wafService": "CA",
 "wafFeature": "ACTION_TOKEN"
  }
 }

    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/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT",
  "displayName": "DISPLAY_NAME",
  "iosSettings": {
    "allowAllBundleIds": false,
    "allowedBundleIds": [
        BUNDLE_IDS
    ]
  },
  "labels": {},
  "wafSettings": {
      "wafService": "CA",
      "wafFeature": "ACTION_TOKEN"
  }
}

    REST (Android)

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

    • DISPLAY_NAME: nombre de la clave. Normalmente, el nombre de una aplicación.
    • PACKAGE_NAMES: nombres de paquetes Android de las aplicaciones que pueden usar la clave. Especifica varios nombres de paquetes en una lista separada por comas.
    • WAF_FEATURE: nombre de la función de WAF. Especifica action-token.
    • WAF_SERVICE: nombre del proveedor de servicios de WAF. Especifica CA para Cloud Armor.

    Método HTTP y URL: 

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

    Cuerpo JSON de la solicitud: 

    {
  "displayName": "DISPLAY_NAME",
  "androidSettings": {
  "allowedPackageNames":"PACKAGE_NAMES"
 },
   'wafSettings': "  {
       "wafService": "CA",
 "wafFeature": "ACTION_TOKEN"
  }
 }

    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/6LcioSknAAAAABrjlMuZv2fjIGYMqwaAFC9izhoy",
  "displayName": "DISPLAY_NAME",
  "androidSettings": {
      "allowAllPackageNames": false,
      "allowedPackageNames": [
          PACKAGE_NAMES
      ],
      "supportNonGoogleAppStoreDistribution": false
  },
  "labels": {},
  "wafSettings": {
      "wafService": "CA",
      "wafFeature": "ACTION_TOKEN"
  }
}

  2. Integra el SDK móvil de reCAPTCHA en tus aplicaciones móviles con la clave action-token que has creado. Para obtener instrucciones, consulta el documento que corresponda al tipo de tu aplicación móvil.

  3. Una vez que hayas recibido el token de reCAPTCHA, adjúntalo a un encabezado de solicitud predefinido con el siguiente formato:

    X-Recaptcha-Token: value-of-your-action-token

    En el siguiente código de ejemplo se muestra cómo adjuntar el token:

    Android

    Código de ejemplo en Java

    // This example shows how to send an HTTP request to the backend server
// attached with the reCAPTCHA token in the header.
//
// @param serverUrl: the URL of the backend server.
// @param rceToken: reCAPTCHA token that is attached to the header of the
// HTTP request.

public static void sendRequestToServerWithRceToken(
    String serverUrl, String rceToken) throws JSONException, IOException {
 URL url = new URL(String.format("http://%s/decryptcaptchacookie/accesswafserver", serverUrl));
 HttpURLConnection connection = (HttpURLConnection) url.openConnection();
 connection.setRequestProperty("X-Recaptcha-Token", rceToken);

 try {
    String requestBody = "['']";
    sendRequest(connection, requestBody, "AccessWithRceToken", "GET");
 } finally {
    connection.disconnect();
 }
}

private static void sendRequest(
    HttpURLConnection connection, String requestString, String requestName, String action)
    throws IOException {
 connection.setConnectTimeout(HTTP_CONNECT_TIMEOUT_MS);
 connection.setReadTimeout(HTTP_READ_TIMEOUT_MS);
 connection.setRequestProperty("Content-type", CONTENT_TYPE);
 connection.setRequestProperty(
    "Content-Length", Integer.toString(Utf8.encodedLength(requestString)));
 connection.setRequestMethod(action);
 connection.setDoOutput(true);
 connection.connect();
 try (OutputStream postStream = connection.getOutputStream()) {
    postStream.write(requestString.getBytes(UTF_8));
 }

 int responseCode = connection.getResponseCode();
 String response = connection.getResponseMessage();
 if (responseCode != HttpURLConnection.HTTP_OK) {
    throw new IOException(
       String.format(
          "Failed to complete request.\nResponse code:%s\nError Detail:\n%s",
          responseCode, response));
 }
}

    iOS

    Código de ejemplo en Swift

    // This example shows how to send an HTTP request to the backend server
// attached with the reCAPTCHA token in the header.
// @param serverUrl: the URL of the backend server.
// @param rceToken: reCAPTCHA token that is attached to the header of
// the HTTP request.

 public static func accessWafServer(rceToken: String, serverUrl: String)
    async throws -> String
 {
    let requestURL = try HttpHelper.createRequestURL(endpoint: serverUrl)
    var request = try HttpHelper.createRequest(requestURL: requestURL, action: "GET")
    request.setValue(rceToken, forHTTPHeaderField: "X-Recaptcha-Token")

    let data = try await HttpHelper.getDataFromServer(request)

    return String(decoding: data, as: UTF8.self)
 }

Configurar políticas de seguridad de Cloud Armor

Después de implementar las funciones de reCAPTCHA para WAF, debes configurar políticas de seguridad de Cloud Armor que evalúen los tokens de reCAPTCHA para gestionar los bots.

Para saber cómo configurar políticas de seguridad de Cloud Armor y usar las claves action-token con tus políticas de seguridad, consulta Configurar reglas para la gestión de bots.

Obtener puntuaciones de reCAPTCHA

En el caso de los tokens de acción de reCAPTCHA, puedes obtener las puntuaciones de reCAPTCHA del encabezado X-Recaptcha-Wafdata. En función de estas puntuaciones, puedes configurar cualquier acción personalizada que deba llevarse a cabo para las solicitudes de los usuarios.

En el siguiente ejemplo se muestra un encabezado X-Recaptcha-Wafdata de muestra:

X-Recaptcha-Wafdata: waf_service="Google Cloud Armor", action_token;score=0.9\r\n

También puedes ver las puntuaciones de reCAPTCHA en los registros de Google Cloud Armor.

Siguientes pasos