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

En este documento, se explica cómo puedes usar la función reCAPTCHA SMS defense para proteger tus flujos basados en SMS de Identity Platform, como la autenticación telefónica y la autenticación de varios factores, 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 negativamente 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. Una vez que se habilita, Firebase Authentication y Identity Platform invocan automáticamente la función de defensa contra SMS de reCAPTCHA cada vez que un usuario final solicita un mensaje SMS de verificación desde tu app o sitio con las siguientes operaciones de phoneProvider:

Luego, reCAPTCHA proporciona a Firebase Authentication o Identity Platform una puntuación de riesgo que indica la probabilidad de fraude de peaje por SMS para el número de teléfono del usuario. Luego, esta puntuación se compara con el límite configurado. Si la puntuación de riesgo supera este umbral, no se envía el mensaje SMS, lo que bloquea de manera eficaz los intentos fraudulentos.

Para comprender cómo funcionan las puntuaciones de defensa contra el fraude de cargos telefónicos por SMS de reCAPTCHA, consulta Cómo interpretar las puntuaciones.

Para obtener más información sobre la función de defensa contra SMS de reCAPTCHA, consulta Cómo detectar y prevenir el fraude por SMS.

Modos de aplicación de la autenticación telefónica de reCAPTCHA

Puedes configurar la aplicación forzosa de la autenticación telefónica para la función reCAPTCHA SMS defense de modo que use el modo de auditoría o de aplicación.

Modo de auditoría

Cuando configuras la aplicación forzosa de la autenticación telefónica en modo de auditoría, Identity Platform usa la defensa contra SMS de reCAPTCHA para la verificación de la app. 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 solicitud de un usuario no pasa la evaluación de fraude de cargos telefónicos y usas el SDK de cliente, Identity Platform activa métodos de verificación alternativos para completar el flujo de autenticación telefónica. Los métodos de resguardo aceptados dependen de la plataforma de tu app.

El SDK de cliente activa los métodos de verificación alternativos en las siguientes situaciones:

• Falta el token de reCAPTCHA.
• El token de reCAPTCHA no es válido o venció.
• El token de reCAPTCHA no supera el umbral de puntuación.
• reCAPTCHA no está configurado correctamente.

Asegúrate de que los métodos de verificación alternativos para la plataforma de tu app estén configurados y listos para que el SDK de cliente los active si es necesario.

Modo de aplicación

Cuando configuras la aplicación forzosa de la autenticación telefónica en el modo de aplicación forzosa, Identity Platform usa la defensa por SMS de reCAPTCHA para la verificación de la app. 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 solicitud de un usuario no pasa la evaluación de fraude de cargos telefónicos, Identity Platform la bloquea y no envía un mensaje SMS con un código de verificación.

No se requiere ninguna verificación alternativa en el modo de aplicación, por lo que no es necesario que configures ningún método de verificación adicional para tu app. Sin embargo, te recomendamos que configures el verificador de reCAPTCHA para las apps web y te asegures de que reCAPTCHA v2 esté habilitado si decides cambiar el modo de reCAPTCHA de tu app a AUDIT o OFF.

Antes de comenzar

Antes de habilitar la función reCAPTCHA SMS defense para Identity Platform, completa las siguientes tareas:

• Configura lo siguiente para tu app o sitio, según corresponda:

  • Acceso telefónico para usuarios.
  • Autenticación de varios factores para tu app para Web, Android o iOS

• Configura Firebase Authentication para tu app o sitio según corresponda:

  • Web: Configuración de Phone Auth
  • iOS: Configuración de la autenticación por teléfono
  • Android: Configuración de la autenticación por teléfono

Habilita la función reCAPTCHA SMS defense

1. Configura la autenticación:

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

      Activate 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: 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 settingsConfiguración.

   4. En el panel Defensa contra SMS, haz clic en Configurar.

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

   Cuando habilitas la función 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 función reCAPTCHA SMS defense como parte de las evaluaciones.

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

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

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

      • PROJECT_ID: Es el identificador del proyecto con la plataforma de identidad habilitada.

      • Recaptcha_MODE: Es el modo que deseas establecer para la aplicación de la autenticación telefónica de reCAPTCHA. Los valores válidos son OFF, AUDIT y ENFORCE. Para habilitar la función reCAPTCHA SMS defense, este parámetro debe establecerse en AUDIT o ENFORCE, y useSmsTollFraudProtection debe establecerse en true.

        Cuando habilites reCAPTCHA SMS defense por primera vez, usa el modo AUDIT para asegurarte de que la configuración de reCAPTCHA SMS defense funcione correctamente. El modo AUDIT es estrictamente para fines de verificación. Este modo no evitará el tráfico de SMS no autorizado. Verifica que no aparezcan errores en el panel de Métricas. Después de la verificación, habilita el modo ENFORCE de inmediato. Para obtener más información sobre cómo funcionan los modos, consulta Modos de aplicación de la autenticación telefónica de reCAPTCHA.

      • START_SCORE: Es la puntuación más alta de evaluación de fraude de peaje que puede tener una solicitud antes de que falle. Puedes establecer esta puntuación entre 0.1 y 0.9. Te recomendamos que comiences con un umbral más alto, por ejemplo, 0.8, y, luego, reduzcas la puntuación de forma iterativa. Las puntuaciones superiores al umbral que establezcas se considerarán como fraude de SMS. Si se establece una puntuación de 1.0, se inhabilita la protección contra fraude, mientras que si se establece una puntuación de 0.0, se bloquean todos los mensajes SMS. Cuanto más baja sea la puntuación que establezcas, más estrictas serán las reglas. Por ejemplo, si estableces un umbral de 0.3, reCAPTCHA rechazará cualquier solicitud con una puntuación de 0.4 o superior.

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

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

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

   • En el caso de 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 Add domain.

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

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

2. Verifica la configuración:

   • Recupera los detalles de configuración de reCAPTCHA:

     {replace-your-project} con 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 está configurada correctamente, la respuesta debe tener los siguientes campos con los valores especificados:

        • recaptchaKeys: El campo no debe estar vacío y debe configurarse para al menos una de estas plataformas: iOS, Web o Android.
        • useSmsTollFraudProtection: El valor de este campo debe establecerse en true.
        • phoneEnforcementState: El valor debe establecerse en ENFORCE o AUDIT.
        • tollFraudManagedRules: Dentro de 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 la función 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
            }
          }
          ```
        

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

   Web

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

   • La compatibilidad con reCAPTCHA para 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 con reCAPTCHA para la autenticación por teléfono en aplicaciones web está disponible en las versiones 11 y posteriores del SDK de JavaScript.

   Después de integrar el SDK web en tu app, este 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 con reCAPTCHA para la autenticación por correo electrónico y contraseña, y la autenticación por teléfono en 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 superior, y Android 6 o superior.

      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 de tu 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 de 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 Cómo preparar tu entorno de iOS.

   2. Para verificar que -ObjC aparezca en las marcas del vinculador, navega a Objetivo > Configuración de compilación > Todas > Vinculación y verifica que Other Linker Flags muestre -ObjC.

Supervisa las métricas de reCAPTCHA para la función 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 tu tráfico de usuarios.

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

• identitytoolkit.googleapis.com/recaptcha/verdict_count
• identitytoolkit.googleapis.com/recaptcha/token_count
• identitytoolkit.googleapis.com/recaptcha/sms_tf_risk_scores

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

Aplica la función reCAPTCHA SMS defense

Después de verificar que tu app recibe tráfico de usuarios aceptable, habilita el modo ENFORCE de reCAPTCHA para bloquear de forma activa las solicitudes fraudulentas y proteger a los usuarios.

Para habilitar el modo ENFORCE para los flujos de autenticación basados en SMS en un proyecto o un arrendatario, usa el Explorador de APIs de Google para actualizar la configuración del proyecto. Para ello, ingresa la siguiente URL HTTP en una ventana nueva 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","resource":{"recaptchaConfig":{"phoneEnforcementState":"ENFORCE","useSmsTollFraudProtection":"true"}}}

Reemplaza PROJECT_ID por el ID del proyecto.

Usa reCAPTCHA SMS defense con protección contra bots

Es posible usar reCAPTCHA SMS defense de forma simultánea con la protección contra bots. Para las configuraciones que usan ambas funciones de protección, ten en cuenta lo siguiente:

• Cuando configuras el estado de aplicación de la autenticación telefónica como AUDIT, Identity Platform pasa una solicitud cuando satisface al menos una de las evaluaciones. Te recomendamos que supervises las métricas de reCAPTCHA para verificar que tanto la defensa contra SMS de reCAPTCHA como la protección contra bots estén configuradas con parámetros de puntuación razonables.
• Cuando estableces el estado de aplicación forzosa de la autenticación telefónica en ENFORCE, Identity Platform solo pasa una solicitud cuando satisface ambas evaluaciones y el cierre de la solicitud fallida no recurre 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_MODE',
          useSmsTollFraudProtection: true,
          useSmsBotScore: true
        }

Reemplaza ENFORCE_MODE por el modo que deseas establecer para la aplicación forzosa de la autenticación telefónica de reCAPTCHA. Los valores válidos son OFF, AUDIT y ENFORCE. Cuando habilites la defensa contra SMS de reCAPTCHA por primera vez, te recomendamos que establezcas este parámetro en AUDIT y te asegures de que tus flujos de autenticación estén protegidos antes de establecerlo en ENFORCE. Para obtener más información sobre cómo funcionan los modos, consulta Modos de aplicación de la autenticación telefónica de reCAPTCHA.

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

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

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

Reemplaza ENFORCE_MODE por el modo que configuraste anteriormente para la aplicación forzosa de la autenticación telefónica de reCAPTCHA. Este valor debe ser AUDIT o ENFORCE. Para obtener más información sobre cómo funcionan los modos, consulta Modos de aplicación de la autenticación telefónica de reCAPTCHA.

Inhabilita la función reCAPTCHA SMS defense

Para inhabilitar la defensa contra 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 ventana nueva 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","resource":{"recaptchaConfig":{"phoneEnforcementState":"OFF","useSmsTollFraudProtection":"false"}}}

Reemplaza PROJECT_ID por el ID del proyecto.

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

¿Qué sigue?

• Obtén más información sobre la función de defensa contra SMS de reCAPTCHA.