Habilita la protección contra fraude de cargos telefónicos por SMS para la autenticación basada en SMS

En este documento, se explica cómo puedes usar reCAPTCHA para proteger tus flujos basados en SMS de Identity Platform, como la autenticación telefónica y de varios factores, contra el fraude de cargos telefónicos por SMS (también conocido como ataques de SMS pumping).

Descripción general

Si tu app se basa en un flujo basado en SMS para la autenticación, puedes habilitar la función de protección contra el fraude de cargos telefónicos por SMS de reCAPTCHA como parte de la integración de Identity Platform con reCAPTCHA. Cuando está habilitada, Identity Platform invoca la función de protección contra fraude de cargos telefónicos por SMS cuando un usuario solicita un SMS de verificación desde tu app o sitio con las siguientes operaciones de phoneProvider:

Operación Método
Registrarse o acceder con un número de teléfono sendVerificationCode
Inscripción de números de teléfono para la MFA mfaSmsEnrollment
Acceso con número de teléfono de MFA mfaSmsSignIn

Luego, reCAPTCHA proporciona a Identity Platform una puntuación de riesgo que indica la probabilidad de que el número de teléfono del usuario cometa un fraude de cargos telefónicos por SMS. Identity Platform compara esta puntuación con el umbral que estableciste en la configuración de protección contra fraude de cargos telefónicos por SMS y, luego, controla la solicitud según la acción que estableciste en la configuración.

Para obtener más información sobre la función de protección contra el fraude de cargos telefónicos por SMS de reCAPTCHA, consulta Cómo detectar y evitar fraudes por SMS.

Antes de comenzar

Antes de habilitar la protección contra fraude de cargos telefónicos por SMS para Identity Platform, completa las siguientes tareas:

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

La protección contra el fraude de cargos telefónicos por SMS de reCAPTCHA requiere que hayas configurado la aplicación de la autenticación telefónica de reCAPTCHA, que tiene dos modos: auditoría y aplicación.

Modo de auditoría

Cuando configuras la aplicación de la autenticación telefónica en modo de auditoría, Identity Platform usa la protección contra el fraude de cargos telefónicos por SMS de reCAPTCHA para la verificación de apps. Si la solicitud del usuario supera la evaluación de fraude de cargos telefónicos, Identity Platform envía un mensaje SMS con un código de verificación al teléfono del usuario. Si una solicitud falla en la evaluación de fraude de peaje y usas el SDK cliente, se activan los métodos de verificación de resguardo 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 de resguardo 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 de resguardo para la plataforma de tu app estén configurados y listos para que el SDK cliente los active si es necesario.

Web

Si falla la evaluación inicial de fraude de peaje, el modo de auditoría se basa en reCAPTCHA v2 para la verificación. Por lo tanto, debes configurar el verificador de reCAPTCHA (RecaptchaVerifier) y pasarlo a las siguientes operaciones de autenticación telefónica:

  • verifyPhoneNumber
  • signInWithPhoneNumber
  • linkWithPhoneNumber
  • reauthenticateWithPhoneNumber
Sin el verificador de reCAPTCHA, Identity Platform no puede iniciar reCAPTCHA v2 y mostrará auth/argument-error. Para obtener más información sobre cómo configurar el verificador de reCAPTCHA, consulta Cómo configurar el verificador de reCAPTCHA en la documentación de Firebase.

Android

Si falla la evaluación inicial de fraude de peaje, el modo de auditoría verifica tu app en función de la API de Play Integrity. Si esta verificación falla, se activa reCAPTCHA v2. reCAPTCHA v2 puede activarse en las siguientes situaciones:

  • Si el dispositivo del usuario final no tiene instalados los Servicios de Google Play.
  • Si la app no se distribuye en Google Play Store (en el SDK de Authentication v21.2.0 y versiones posteriores).
  • Si el token de SafetyNet no es válido (en versiones del SDK de Authentication anteriores a la v21.2.0).
Para obtener más información sobre cómo configurar la verificación de apps para Android, consulta Cómo habilitar la verificación de apps en la documentación de Firebase.

iOS

Si falla la evaluación inicial de fraude de peaje, el modo de auditoría se basa en notificaciones push silenciosas para la verificación. Este método de verificación implica enviar un token a tu app en el dispositivo solicitante con una notificación push silenciosa. Si la app recibe correctamente la notificación, el flujo de autenticación telefónica continúa. Si tu app no recibe la notificación push, se activa reCAPTCHA v2. Es posible que se active reCAPTCHA v2 si las notificaciones push silenciosas no están configuradas correctamente.

Para obtener más información sobre cómo configurar la verificación de apps para iOS, consulta Habilita la verificación de apps en la documentación de Firebase.

Modo de aplicación forzosa

Cuando configuras la aplicación de la autenticación telefónica en modo de aplicación forzosa, Identity Platform usa la protección contra el fraude de cargos telefónicos por SMS de reCAPTCHA para la verificación de apps. Si la solicitud del usuario pasa la evaluación de fraude de peaje, Identity Platform envía un mensaje SMS con un código de verificación al teléfono del usuario. Si la solicitud falla en la valoración de fraude de peaje, Identity Platform la bloquea y no envía un mensaje SMS con un código de verificación.

No se requiere ninguna verificación de resguardo en el modo de aplicación forzosa, por lo que 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 apps web para asegurarte de que reCAPTCHA v2 esté habilitado si decides cambiar el modo de reCAPTCHA de tu app a AUDIT o OFF.

Habilita la protección contra fraude de cargos telefónicos por SMS de reCAPTCHA

Para habilitar la protección contra fraude de cargos telefónicos por SMS, haz lo siguiente:

  1. Si aún no lo hiciste, habilita la API de reCAPTCHA Enterprise en tu proyecto.

  2. Habilita la protección contra fraude de cargos telefónicos por SMS con reCAPTCHA. Para obtener instrucciones, consulta la sección Antes de comenzar de la página Detecta y evita fraudes de SMS en la documentación de reCAPTCHA.

  3. Para habilitar la protección contra fraude de cargos telefónicos por SMS para un proyecto, usa el SDK de Admin para llamar a updateConfig de la siguiente manera:

      // Update the reCAPTCHA config to enable toll fraud protection
  const updateProjectConfigRequest = {
    recaptchaConfig: {
      phoneEnforcementState: 'ENFORCE_MODE',
      useSmsTollFraudProtection: 'true',
      tollFraudManagedRules: [{ startScore: START_SCORE,
        action: 'BLOCK' }],
    }
  }
  let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);

    Reemplaza lo siguiente:

    • ENFORCE_MODE: Es el modo que deseas configurar para la aplicación forzosa de la autenticación telefónica de reCAPTCHA. Los valores válidos son OFF, AUDIT y ENFORCE. Para habilitar la protección contra fraude de cargos telefónicos por SMS, este parámetro debe establecerse en AUDIT o ENFORCE, y useSmsTollFraudProtection debe establecerse en true.

      Cuando habilites la protección contra fraude de cargos telefónicos por SMS por primera vez, te recomendamos que configures el estado de aplicación forzosa 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 el funcionamiento de 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.0 y 1.0. Cualquier puntuación superior al umbral que establezcas se considerará un fraude de peaje por SMS. Por ejemplo, si estableces un umbral de 0.3, reCAPTCHA rechazará cualquier solicitud con un 0.4 o superior. Por lo tanto, cuanto más baja establezcas la puntuación, más estrictas serán las reglas.

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

    El aprovisionamiento de claves de reCAPTCHA puede tardar varios minutos en completarse.

  5. Si configuraste la aplicación forzosa en el modo de auditoría, te recomendamos que supervises las métricas de reCAPTCHA para la protección contra el fraude de cargos telefónicos por SMS para asegurarte de que tus flujos estén protegidos.

Configura el SDK de cliente

Configura el SDK de cliente según la plataforma de tu app.

Web

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

    • La compatibilidad de reCAPTCHA con la autenticación de 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 telefónica 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.

  2. Si es necesario, puedes forzar la recuperación del indicador de reCAPTCHA de la siguiente manera:

    import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Authentication
const auth = getAuth();
initializeRecaptchaConfig(auth)
  .then(() => {
    console.log("Recaptcha Enterprise Config Initialization successful.")
  })
  .catch((error) => {
    console.error("Recaptcha Enterprise Config Initialization failed with " + error)
  });

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 telefónica en apps para Android está disponible en la versión 23.1.0 del SDK de Android y versiones posteriores.

    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 con tu app, el SDK recupera automáticamente la configuración de reCAPTCHA y habilita la protección 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.

  3. Si es necesario, puedes forzar la recuperación del indicador de reCAPTCHA de la siguiente manera:

    • Kotlin:
    // Initialize Firebase Authentication
auth = Firebase.auth

auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
    if (task.isSuccessful) {
        Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
    } else {
        Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
    }
}
    • Java:
    // Initialize Firebase Authentication
auth = FirebaseAuth.getInstance();
auth.initializeRecaptchaConfig().addOnCompleteListener(
  this, new OnCompleteListener<void>() {
  @Override
  public void onComplete(@NonNull Task<void> task) {
    if (task.isSuccessful()) {
      Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
    } else {
      Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
    }
  }
});

iOS

  1. Actualiza a la versión 11.6.0 del SDK de iOS o una posterior. Después de integrar el SDK de iOS a tu app, el SDK recupera automáticamente tu configuración de reCAPTCHA y habilita la protección para los proveedores que configuraste.

  2. Para integrar el SDK de reCAPTCHA para iOS a tu app, consulta Prepara tu entorno.

  3. Asegúrate de que -ObjC esté en la lista de tus marcas de vinculador. Navega a Objetivo > Configuración de compilación > Todas > Vinculación y verifica que Other Linker Flags muestre -ObjC.

  4. Si es necesario, puedes forzar la recuperación del indicador de reCAPTCHA de la siguiente manera:

    • Swift:
    // Initialize Firebase Authentication
try await Auth.auth().initializeRecaptchaConfig()
    • Objective-C:
    // Initialize Firebase Authentication
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Authentication initialization finished
}];

Supervisa las métricas de reCAPTCHA para la protección contra el fraude de cargos telefónicos por SMS

Antes de establecer la aplicación forzosa de reCAPTCHA en el modo forzoso, te recomendamos que uses el modo de auditoría y supervises las métricas de reCAPTCHA que emite tu proyecto para asegurarte de 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 ajustar el umbral de puntuación para tu tráfico de usuarios.

Para asegurarte de que la función de protección contra fraudes de peajes por SMS funcione, examina las siguientes métricas que emite tu proyecto a Cloud Monitoring:

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

Aplica la protección contra fraude de cargos telefónicos por SMS

Después de verificar que tu app recibe un tráfico de usuarios aceptable, puedes habilitar la aplicación forzosa de reCAPTCHA para proteger a tus usuarios. Asegúrate de no interrumpir a los usuarios existentes, incluidos los que pueden estar usando una versión anterior de tu app.

Para habilitar la aplicación forzosa de reCAPTCHA para los flujos de autenticación basados en SMS en un proyecto o inquilino, usa el SDK de Admin para ejecutar el siguiente comando:

  const enforceRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE',
      useSmsTollFraudProtection: 'true'
    }
  };

Inhabilita la protección contra fraude de cargos telefónicos por SMS

Para inhabilitar la protección contra fraudes de peajes por SMS, usa el SDK de Admin para ejecutar el siguiente comando:

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'OFF',
      useSmsTollFraudProtection: 'false'
    }
  };

Para inhabilitar la protección contra fraude de cargos telefónicos por SMS mientras usas la protección contra bots, consulta Cómo inhabilitar la protección contra fraude de cargos telefónicos por SMS mientras usas la protección contra bots.

Usa la protección contra fraude de cargos telefónicos por SMS con la protección contra bots

Es posible usar la protección contra fraude de cargos telefónicos por SMS de forma simultánea con la protección contra bots. En el caso de 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 para auditar, Identity Platform pasa una solicitud cuando satisface al menos una de las evaluaciones. Te recomendamos que supervises las métricas de reCAPTCHA para asegurarte de que la protección contra el fraude de cargos telefónicos por SMS y 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, Identity Platform solo pasa una solicitud cuando satisface ambas evaluaciones y la solicitud de error se cierra sin recurrir a otro método de verificación.

Para habilitar ambas funciones, usa el SDK de Admin para ejecutar el siguiente comando:

  const enableBothRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: true,
      useSmsBotScore: true
    }
  };

Reemplaza ENFORCE_MODE por el modo que deseas configurar para la aplicación forzosa de la autenticación telefónica de reCAPTCHA. Los valores válidos son OFF, AUDIT y ENFORCE. Para habilitar la protección contra fraude de cargos telefónicos por SMS, este parámetro se debe establecer en AUDIT o ENFORCE. Cuando habilites la protección contra fraudes de peajes por SMS por primera vez, te recomendamos que configures 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 el funcionamiento de los modos, consulta Modos de aplicación forzosa de la autenticación telefónica de reCAPTCHA.

Inhabilita la protección contra fraude de cargos telefónicos por SMS mientras usas la protección contra bots

Si usas la protección contra fraude de cargos telefónicos por SMS y la protección contra bots de forma simultánea, y deseas inhabilitar la protección contra fraude de cargos telefónicos por SMS sin inhabilitar la protección contra bots, usa el SDK de Admin para ejecutar el siguiente comando:

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }
  };

Reemplaza ENFORCE_MODE por el modo que estableciste 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 el funcionamiento de los modos, consulta Modos de aplicación forzosa de la autenticación telefónica de reCAPTCHA.

¿Qué sigue?