Habilita la función reCAPTCHA SMS defense para la autenticación basada en SMS

En este documento, se explica cómo puedes usar reCAPTCHA SMS defense para proteger tus flujos basados en SMS de Identity Platform, como la autenticación de varios factores y la autenticación telefónica, contra el fraude de cargos telefónicos por SMS (también conocido como ataques de SMS pumping). Esta integración ayuda a evitar que el tráfico de SMS no autorizado afecte de forma negativa a tus usuarios y recursos.

Descripción general

Si tu app depende de los SMS para la autenticación, te recomendamos que habilites la integración de reCAPTCHA SMS defense. Después de habilitarla, Firebase Authentication y Identity Platform invocan automáticamente la función de defensa de SMS de reCAPTCHA cada vez que un usuario final solicita un mensaje de SMS de verificación desde tu app o sitio con las siguientes operaciones de phoneProvider:

Operación Método
Registro o acceso con número de teléfono sendVerificationCode
Inscripción del número de teléfono para la MFA mfaSmsEnrollment
Acceso con número de teléfono para la MFA mfaSmsSignIn

Luego, reCAPTCHA proporciona a Firebase Authentication o Identity Platform una puntuación de riesgo que indica la probabilidad de fraude de cargos telefónicos por SMS para el número de teléfono del usuario. Luego, esta puntuación se compara con el umbral configurado. Si la solicitud de un usuario pasa la evaluación de fraude de cargos telefónicos, se envía un código de verificación por SMS. Si la puntuación de riesgo supera el umbral configurado, Identity Platform bloquea la solicitud y no envía un mensaje SMS con un código de verificación.

Cuando la función reCAPTCHA SMS defense está habilitada, no se requiere una verificación de resguardo y no tienes que configurar ningún método de verificación adicional para tu app. Sin embargo, te recomendamos configurar el verificador de reCAPTCHA para las apps web para asegurarte de que reCAPTCHA v2 esté disponible si decides inhabilitar la función reCAPTCHA SMS defense.

Para comprender cómo funcionan las puntuaciones de la defensa de SMS de reCAPTCHA, consulta Interpreta las puntuaciones.

Para obtener más información sobre la función de SMS defense de reCAPTCHA, consulta Detecta y evita el fraude de SMS.

Antes de comenzar

Antes de habilitar reCAPTCHA SMS defense para Identity Platform, completa las siguientes tareas:

Habilita la función reCAPTCHA SMS defense

  1. Configura la autenticación:

    1. En la consola de Google Cloud , activa Cloud Shell.

      Activa Cloud Shell

    2. Crea una identidad de servicio:

      gcloud beta services identity create \
    --service=identitytoolkit.googleapis.com \
    --project=PROJECT_ID

      Reemplaza PROJECT_ID por el ID del proyecto.

    3. Otorga el rol roles/identitytoolkit.serviceAgent a la identidad de servicio que creaste.

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
    --role=roles/identitytoolkit.serviceAgent

      Reemplaza lo siguiente:

      • PROJECT_ID: Es el ID del proyecto.
      • PROJECT_NUMBER: Es el número de cuenta del proyecto.

  2. Habilita la API de reCAPTCHA Enterprise en tu proyecto.

  3. Habilita la función reCAPTCHA SMS defense para tu proyecto:

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

      Ir a reCAPTCHA

    2. Verifica que el nombre de tu proyecto aparezca en el selector de recursos.

      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 SMS defense, haz clic en Configurar.

    5. Haz clic en el botón de activación Habilitar y, luego, en Guardar.

    Cuando habilitas reCAPTCHA SMS defense, también se habilita la protección de cuentas, si aún no lo está.

    La habilitación de la función reCAPTCHA SMS defense puede tardar unos minutos en propagarse a nuestros sistemas. Una vez que se propague, comenzarás a recibir respuestas relacionadas con la defensa de SMS de reCAPTCHA como parte de las evaluaciones.

  4. Para configurar los parámetros de protección de SMS de reCAPTCHA para un proyecto de Firebase Authentication o Identity Platform, haz lo siguiente:

    1. En la siguiente URL, reemplaza PROJECT_ID y START_SCORE:

      https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig.phoneEnforcementState,recaptchaConfig.useSmsTollFraudProtection,recaptchaConfig.tollFraudManagedRules","resource":{"recaptchaConfig":{"phoneEnforcementState":"ENFORCE","useSmsTollFraudProtection":true,"tollFraudManagedRules":[{"action":"BLOCK","startScore":START_SCORE}]}}}

      • PROJECT_ID: Es el identificador del proyecto con Identity Platform habilitado.

      • START_SCORE: Es un umbral configurable que determina la puntuación más alta que puede tener una solicitud de SMS antes de que se marque y bloquee como fraude de cargos telefónicos.

        El umbral mínimo es 0.0. El umbral máximo es 0.9. Cualquier solicitud con una puntuación superior al umbral se considera fraudulenta. Por ejemplo, si estableces el umbral en 0.3, reCAPTCHA bloqueará cualquier solicitud con una puntuación de fraude de 0.4 o más.

        Para aumentar el nivel de protección contra fraudes, establece el umbral en un valor más bajo. Para reducir el nivel de protección contra fraudes, establece el umbral en un valor más alto. Este parámetro de configuración permitirá que se aprueben más solicitudes con puntuaciones más altas.

        Para la implementación inicial, te recomendamos que comiences con un umbral más alto, como 0.8, y, luego, lo reduzcas de forma iterativa según tu tolerancia al riesgo específica.

        No recomendamos un umbral de 0.0 ni de 1.0. Si estableces el umbral en 0.0, se bloquearán todos los mensajes SMS, mientras que 1.0 inhabilitará por completo la protección contra fraudes, lo que puede generar errores de entrega de SMS en regiones de alto riesgo.

    2. Ingresa la URL en una nueva ventana del navegador en la que hayas accedido a la consola de Google Cloud .

  5. Si usas Identity Platform en la Web o en Android, registra tu app desde Firebase console:

    • En Android, registra cada nombre de paquete de Android que use Identity Platform.

    • En la Web, agrega un dominio autorizado para cada dominio que use reCAPTCHA:

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

        Ir a Identity Platform

      2. Ve a Configuración > Seguridad.

      3. Haz clic en Agregar dominio.

      4. Ingresa el nombre de dominio y haz clic en Agregar para guardarlo.

      El aprovisionamiento de la clave de reCAPTCHA puede tardar varios minutos en completarse.

  6. Verifica la configuración:

    • Recupera los detalles de configuración de reCAPTCHA:

      {replace-your-project} por tu projectId o projectNumber. Ejecuta la API de GetConfig en el panel lateral para recuperar la configuración de reCAPTCHA.

    • Verifica que la función reCAPTCHA SMS defense esté configurada correctamente:

      1. Si la configuración de reCAPTCHA se establece de forma correcta, la respuesta debe tener los siguientes campos con los valores especificados:

        • recaptchaKeys: El campo no debe estar vacío y se debe configurar para al menos una de estas plataformas: iOS, Web o Android.
        • useSmsTollFraudProtection: El valor de este campo debe establecerse en true.
        • phoneEnforcementState: El valor se debe establecer en ENFORCE.
        • tollFraudManagedRules: En este campo, startScore debe configurarse con el umbral que elijas, que debe ser un valor entre 0 y 0.9.

        De lo contrario, vuelve a configurar reCAPTCHA SMS defense.

        Respuesta de muestra:

          {
    "recaptchaConfig": {
        "recaptchaKeys": [
          {
            "key": "projects/{your-project}/keys/{recaptcha-key}",
            "type": "WEB"
          },
          {
            "type": "IOS"
          },
          {
            "type": "ANDROID"
          }
        ],
        "phoneEnforcementState": "ENFORCE",
        "tollFraudManagedRules": [
          {
            "startScore": 0.8,
            "action": "BLOCK"
          }
        ],
        "useSmsTollFraudProtection": true
    }
  }
  ```

  7. Asegúrate de que las versiones del SDK sean correctas.

    Web

    Actualiza a la versión más reciente del SDK web.

    • La compatibilidad de reCAPTCHA con la autenticación por correo electrónico y contraseña en apps web está disponible en las versiones 9.20.0 y posteriores del SDK de JavaScript.
    • La compatibilidad de reCAPTCHA con la autenticación por teléfono en apps web está disponible en las versiones 11 y posteriores del SDK de JavaScript.

    Después de integrar el SDK web en tu app, el SDK recupera automáticamente tu configuración de reCAPTCHA y habilita la protección para los proveedores que configuraste.

    Android

    1. Actualiza a la versión más reciente del SDK de Android. La compatibilidad de reCAPTCHA con la autenticación por correo electrónico y contraseña, y la autenticación por teléfono en las apps para Android está disponible en la versión 23.1.0 y posteriores del SDK de Android.

      Además, la compatibilidad con reCAPTCHA requiere el nivel de API 23 (Marshmallow) o una versión posterior, y Android 6 o una versión posterior.

      Después de integrar el SDK de Android en tu app, el SDK recupera automáticamente tu configuración de reCAPTCHA y aplica los umbrales que estableciste para los proveedores que configuraste.

    2. Agrega la siguiente regla de compilación a la sección de dependencias del archivo build.gradle a nivel de la app:

      implementation 'com.google.android.recaptcha:recaptcha:18.5.1'

      Asegúrate de usar la versión 18.5.1 o posterior del SDK de reCAPTCHA.

    iOS

    1. Actualiza a la versión 11.6.0 o posterior del SDK para iOS.

    Después de integrar el SDK de iOS en tu app, el SDK recupera automáticamente tu configuración de reCAPTCHA y aplica los umbrales que estableciste para los proveedores que configuraste.

    1. Para integrar el SDK de reCAPTCHA para iOS en tu app, consulta Prepara tu entorno de iOS.

    2. Para verificar que -ObjC aparezca en tus marcas de vinculador, navega a Target > Build Settings > All > Linking y verifica que Other Linker Flags muestre -ObjC.

Supervisa las métricas de reCAPTCHA para reCAPTCHA SMS defense

Supervisa las métricas de reCAPTCHA que emite tu proyecto para verificar que tus flujos de autenticación basados en SMS estén protegidos. Por ejemplo, estas métricas pueden ayudarte a determinar si configuraste correctamente la integración de Identity Platform con la API de reCAPTCHA Enterprise. También pueden ayudarte a definir mejor el umbral de puntuación para el tráfico de tus usuarios.

Para verificar que la función reCAPTCHA SMS defense esté funcionando, revisa las siguientes métricas que tu proyecto emite a Cloud Monitoring:

Para obtener más información, consulta Supervisa las métricas de reCAPTCHA.

Usa reCAPTCHA SMS defense con protección contra bots

Puedes usar reCAPTCHA SMS defense de forma simultánea con la protección contra bots. Cuando ambas están habilitadas y phoneEnforcementState se establece en ENFORCE, Identity Platform solo pasa una solicitud cuando cumple con ambas evaluaciones, y la solicitud falla y se cierra sin recurrir a otro método de verificación.

Para habilitar ambas funciones, usa el Explorador de APIs de Google para actualizar la configuración del proyecto:

        recaptchaConfig: {
          phoneEnforcementState: 'ENFORCE',
          useSmsTollFraudProtection: true,
          useSmsBotScore: true
        }

Inhabilita reCAPTCHA SMS defense mientras usas la protección contra bots

Si usas la defensa de SMS de reCAPTCHA y la protección contra bots, y quieres inhabilitar la defensa de SMS de reCAPTCHA sin inhabilitar la protección contra bots, usa el Explorador de APIs de Google para actualizar la configuración del proyecto:

    recaptchaConfig: {
      phoneEnforcementState: 'ENFORCE',
      useSmsTollFraudProtection: false,
      useSmsBotScore: true
    }

Establece phoneEnforcementState en ENFORCE y useSmsBotScore en true para mantener habilitada la protección contra bots en los flujos de autenticación por teléfono.

Inhabilitar reCAPTCHA SMS defense

Para inhabilitar toda la protección de reCAPTCHA para teléfonos, incluida la defensa de SMS de reCAPTCHA, usa el Explorador de APIs de Google para actualizar la configuración del proyecto. Para ello, ingresa la siguiente URL HTTP en una nueva ventana del navegador en la que hayas accedido a la consola de Google Cloud :


   https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig.phoneEnforcementState,recaptchaConfig.useSmsTollFraudProtection,recaptchaConfig.useSmsBotScore","resource":{"recaptchaConfig":{"phoneEnforcementState":"OFF","useSmsTollFraudProtection":false,"useSmsBotScore":false}}}

Reemplaza PROJECT_ID por el ID del proyecto.

Para inhabilitar la defensa de SMS de reCAPTCHA mientras usas la protección contra bots, consulta Inhabilita la defensa de SMS de reCAPTCHA mientras usas la protección contra bots.

¿Qué sigue?