Esta página se ha traducido con Cloud Translation API.

Habilitar 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 telefónica y la autenticación multifactor, frente al fraude telefónico 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.

Información general

Si tu aplicación usa SMS para la autenticación, te recomendamos que habilites la integración de reCAPTCHA SMS defense. Una vez habilitada, Firebase Authentication e Identity Platform invocan automáticamente la función de defensa por SMS de reCAPTCHA cada vez que un usuario final solicita un mensaje SMS de verificación desde tu aplicación o sitio mediante las siguientes operaciones de phoneProvider:

Operación	Método
Registrarse o iniciar sesión con un número de teléfono	`sendVerificationCode`
Registro del número de teléfono para la MFA	`mfaSmsEnrollment`
Inicio de sesión con número de teléfono y MFA	`mfaSmsSignIn`

A continuación, reCAPTCHA proporciona a Firebase Authentication o Identity Platform una puntuación de riesgo que indica la probabilidad de que el número de teléfono del usuario se vea afectado por un fraude de servicios telefónicos por SMS. Esta puntuación se compara con el umbral que hayas configurado. Si la puntuación de riesgo supera este umbral, el mensaje SMS no se envía, lo que bloquea los intentos fraudulentos.

Para saber cómo funcionan las puntuaciones de reCAPTCHA SMS defense, consulta Interpretar puntuaciones.

Para obtener más información sobre la función de defensa por SMS de reCAPTCHA, consulta Detectar y evitar el fraude por SMS.

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

Puedes configurar la aplicación de la autenticación telefónica para la defensa por SMS de reCAPTCHA de modo que use el modo de auditoría o el modo obligatorio.

Modo de auditoría

Cuando configuras la autenticación por teléfono en modo de auditoría, Identity Platform usa la defensa por SMS de reCAPTCHA para verificar la aplicación. Si la solicitud de un usuario supera la evaluación de fraude de peaje, se envía un código de verificación por SMS. Si la solicitud de un usuario no supera la evaluación de fraude de peaje y estás usando 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 alternativos aceptados dependen de la plataforma de tu aplicación.

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

Falta el token de reCAPTCHA.
El token de reCAPTCHA no es válido o ha caducado.
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 de la plataforma de tu aplicación estén configurados y listos para que el SDK del cliente los active si es necesario.

Web

Si la evaluación inicial del fraude de peaje falla, 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 devolverá auth/argument-error. Para obtener más información sobre cómo configurar el verificador de reCAPTCHA, consulta el artículo Configurar el verificador de reCAPTCHA en la documentación de Firebase.

Android

Si no se supera la evaluación inicial del fraude de peaje, el modo de auditoría verifica tu aplicación con la API Play Integrity. Si esta verificación falla, se activa reCAPTCHA v2. reCAPTCHA v2 puede activarse en los siguientes casos:

Si el dispositivo del usuario final no tiene instalados los servicios de Google Play.
Si la aplicación no se distribuye a través de Google Play Store (en el SDK de autenticación v21.2.0 y versiones posteriores).
Si el token de SafetyNet obtenido no era válido (en versiones del SDK de autenticación anteriores a la 21.2.0).

Para obtener más información sobre cómo configurar la verificación de aplicaciones Android, consulta el artículo Habilitar la verificación de aplicaciones en la documentación de Firebase.

iOS

Si la evaluación inicial del fraude de peaje falla, el modo de auditoría se basa en notificaciones push silenciosas para la verificación. Este método de verificación consiste en enviar un token a tu aplicación en el dispositivo que realiza la solicitud mediante una notificación push silenciosa. Si tu aplicación recibe la notificación correctamente, se iniciará el flujo de autenticación del teléfono. Si tu aplicación no recibe la notificación push, se activará reCAPTCHA v2. reCAPTCHA v2 puede activarse si las notificaciones push silenciosas no están configuradas correctamente.

Para obtener más información sobre cómo configurar la verificación de aplicaciones iOS, consulta el artículo Habilitar la verificación de aplicaciones en la documentación de Firebase.

Modo obligatorio

Cuando configuras la autenticación telefónica en modo obligatorio, Identity Platform usa la defensa por SMS de reCAPTCHA para verificar la aplicación. Si la solicitud de un usuario supera la evaluación de fraude de peaje, se envía un código de verificación por SMS. Si la solicitud de un usuario no supera la evaluación de fraude de peaje, Identity Platform la bloquea y no envía un mensaje SMS con un código de verificación.

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

Antes de empezar

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

Configure lo siguiente en su aplicación o sitio, según corresponda:
- Inicio de sesión con el teléfono para los usuarios.
- Autenticación multifactor para tu aplicación web, Android o iOS.
Configura Firebase Authentication en tu aplicación o sitio, según corresponda:
- Web: Configuración de la autenticación por teléfono
- iOS: Configuración de autenticación telefónica
- Android: Configuración de la autenticación telefónica

Habilitar reCAPTCHA SMS defense

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
```
  Sustituye PROJECT_ID por el ID del proyecto.
3. Asigna el rol roles/identitytoolkit.serviceAgent a la identidad de servicio que has creado.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
    --role=roles/identitytoolkit.serviceAgent
```
  Haz los cambios siguientes:
  - PROJECT_ID: el ID del proyecto
  - PROJECT_NUMBER: el número de cuenta del proyecto
Habilita la API de reCAPTCHA Enterprise en tu proyecto.
Habilita reCAPTCHA SMS defense en tu proyecto:
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.
  
  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 Configuración.
4. En el panel Defensa por SMS, haz clic en Configurar.
5. Haz clic en el interruptor Habilitar y, a continuación, en Guardar.
Cuando habilitas reCAPTCHA SMS defense, también se habilita Account Defender, si aún no lo has hecho.

La habilitación de la defensa por SMS de reCAPTCHA puede tardar unos minutos en propagarse a nuestros sistemas. Una vez propagado, empezarás a recibir respuestas relacionadas con reCAPTCHA SMS defense como parte de las evaluaciones.
Para configurar los ajustes de protección por SMS de reCAPTCHA en un proyecto de Firebase Authentication o Identity Platform, sigue estos pasos:
1. En la siguiente URL, sustituye 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: el identificador del proyecto con Identity Platform habilitado.
  - Recaptcha_MODE: el modo que quieras definir para la aplicación de la autenticación telefónica de reCAPTCHA. Los valores válidos son OFF, AUDIT y ENFORCE. Para habilitar reCAPTCHA SMS defense, este parámetro debe tener el valor AUDIT o ENFORCE y useSmsTollFraudProtection debe tener el valor true.
    
    Cuando habilites reCAPTCHA SMS defense por primera vez, usa el modo AUDIT para asegurarte de que la configuración de reCAPTCHA SMS defense funciona correctamente. El modo AUDIT se usa exclusivamente para fines de verificación. Este modo no evitará el tráfico de SMS no autorizado. Comprueba que no aparezcan errores en el panel de control Métricas. Después de la verificación, habilita el modo ENFORCE inmediatamente. Para obtener más información sobre cómo funcionan los modos, consulta los modos de cumplimiento de la autenticación telefónica de reCAPTCHA.
  - START_SCORE: umbral configurable que determina la puntuación más alta que puede tener una solicitud de SMS antes de que se marque y se bloquee como fraude de marcación.
    
    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 fijas el umbral en 0.3, reCAPTCHA bloqueará las solicitudes con una puntuación de fraude de 0.4 o superior.
    
    Para aumentar el nivel de protección contra el fraude, define un umbral más bajo. Para reducir el nivel de protección contra el fraude, defina un valor más alto para el umbral. Este ajuste permitirá que se envíen más solicitudes con puntuaciones más altas.
    
    Para la implementación inicial, te recomendamos que empieces con un umbral más alto, como 0.8, y que lo vayas reduciendo de forma iterativa según tu tolerancia al riesgo específica.
    
    No recomendamos usar umbrales de 0.0 o 1.0. Si se establece el umbral en 0.0, se bloquearán todos los mensajes SMS, mientras que si se establece en 1.0, se inhabilitará por completo la protección contra el fraude, lo que puede provocar que no se entreguen los SMS en las regiones de alto riesgo.
    
    Nota: Si quieres inhabilitar la protección contra el fraude, asigna el valor Recaptcha_MODE a OFF.
2. Introduce la URL en una nueva ventana del navegador en la que hayas iniciado sesión en la Google Cloud consola.
Si usas Identity Platform en la Web o en Android, registra tu aplicación desde la consola de Firebase:
- En Android, registra cada nombre de paquete de Android que use Identity Platform.
- En el caso de los sitios web, añade un dominio autorizado por cada dominio que use reCAPTCHA:
  1. En la Google Cloud consola, ve a la página Identity Platform.
    
    Ir a Identity Platform
  2. Ve a Ajustes > Seguridad.
  3. Haz clic en Añadir dominio.
  4. Introduce el nombre del dominio y haz clic en Añadir para guardar el dominio.
  El aprovisionamiento de claves de reCAPTCHA puede tardar varios minutos en completarse.
Verifica tu configuración:
- Obtén los detalles de configuración de reCAPTCHA:
  
  {replace-your-project} con tu projectId o projectNumber. Ejecuta la API GetConfig en el panel lateral para obtener la configuración de reCAPTCHA.
- Comprueba que la defensa por SMS de reCAPTCHA esté configurada correctamente:
  1. Si la configuración de reCAPTCHA es correcta, la respuesta debe tener los siguientes campos con los valores especificados:
    - recaptchaKeys: El campo no puede estar vacío y debe configurarse para al menos una de estas plataformas: iOS, Web o Android.
    - useSmsTollFraudProtection: el valor de este campo debe ser true.
    - phoneEnforcementState: el valor debe ser ENFORCE o AUDIT.
    - 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 ejemplo
```
  {
    "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
    }
  }
  ```
```
Comprueba que las versiones del SDK sean correctas.
Web
Actualiza a la versión más reciente del SDK web.
- reCAPTCHA admite la autenticación por correo electrónico y contraseña en aplicaciones web con las versiones 9.20.0 y posteriores del SDK de JavaScript.
- reCAPTCHA admite la autenticación por teléfono en aplicaciones web en las versiones 11 y posteriores del SDK de JavaScript.
Una vez que hayas integrado el SDK web con tu aplicación, el SDK obtendrá automáticamente tu configuración de reCAPTCHA y habilitará la protección de los proveedores que hayas configurado.
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 aplicaciones Android está disponible en la versión 23.1.0 del SDK de Android y versiones posteriores.
  
  Además, para usar reCAPTCHA, se necesita el nivel de API 23 (Marshmallow) o una versión posterior, así como Android 6 o una versión posterior.
  
  Una vez que hayas integrado el SDK de Android en tu aplicación, el SDK obtendrá automáticamente tu configuración de reCAPTCHA y aplicará los umbrales que hayas definido para los proveedores que hayas configurado.
2. Añade la siguiente regla de compilación a la sección de dependencias de tu archivo build.gradle a nivel de aplicación:
  implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
  Asegúrate de usar la versión 18.5.1 o una posterior del SDK de reCAPTCHA.
iOS
1. Actualiza a la versión 11.6.0 o una posterior del SDK de iOS.
Una vez que hayas integrado el SDK de iOS en tu aplicación, el SDK obtendrá automáticamente tu configuración de reCAPTCHA y aplicará los umbrales que hayas definido para los proveedores que hayas configurado.
1. Para integrar el SDK de reCAPTCHA para iOS en tu aplicación, consulta Preparar el entorno de iOS.
2. Para comprobar que -ObjC aparece en tus marcas de vinculador, ve a Target > Build Settings > All > Linking y comprueba que Other Linker Flags muestra -ObjC.

Monitorizar las métricas de reCAPTCHA para reCAPTCHA SMS defense

Monitoriza 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 has configurado correctamente la integración de Identity Platform con la API de reCAPTCHA Enterprise. También pueden ayudarte a acotar el umbral de puntuación del tráfico de tus usuarios.

Para verificar que la función de defensa por SMS de reCAPTCHA funciona correctamente, comprueba las siguientes métricas que emite tu proyecto a Cloud Monitoring:

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

Habilitar reCAPTCHA SMS defense

Una vez que hayas verificado que tu aplicación recibe tráfico de usuarios aceptable, habilita el modo ENFORCEreCAPTCHA para bloquear activamente las solicitudes fraudulentas y proteger a los usuarios.

Para habilitar el modo ENFORCE en los flujos de autenticación basados en SMS de un proyecto o un arrendatario, usa APIs Explorer de Google para actualizar la configuración del proyecto. Para ello, introduce la siguiente URL HTTP en una ventana nueva del navegador en la que hayas iniciado sesión en la consola 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"}}}

Sustituye PROJECT_ID por el ID del proyecto.

Usar reCAPTCHA SMS defense con protección frente a bots

Es posible usar reCAPTCHA SMS defense simultáneamente 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 hayas definido el estado de aplicación de la autenticación con teléfono como AUDIT, Identity Platform aprobará una solicitud si cumple al menos una de las evaluaciones. Le recomendamos que monitorice las métricas de reCAPTCHA para verificar que tanto la defensa por SMS de reCAPTCHA como la protección frente a bots estén configuradas con ajustes de puntuación razonables.
Si has definido el estado de la autenticación telefónica como ENFORCE, Identity Platform solo aceptará una solicitud si cumple ambas evaluaciones y la solicitud fallida 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_MODE',
          useSmsTollFraudProtection: true,
          useSmsBotScore: true
        }

Sustituye ENFORCE_MODE por el modo que quieras definir para aplicar la autenticación telefónica de reCAPTCHA. Los valores válidos son OFF, AUDIT y ENFORCE. Cuando habilites la defensa por SMS de reCAPTCHA por primera vez, te recomendamos que definas este parámetro como AUDIT y que te asegures de que tus flujos de autenticación estén protegidos antes de definirlo como ENFORCE. Para obtener más información sobre cómo funcionan los modos, consulta Modos de cumplimiento de la autenticación telefónica de reCAPTCHA.

Inhabilitar reCAPTCHA SMS defense al usar la protección frente a bots

Si usas simultáneamente la defensa por SMS de reCAPTCHA y la protección contra bots, y quieres inhabilitar la defensa por 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_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }

Sustituye ENFORCE_MODE por el modo que hayas configurado anteriormente para aplicar 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 cumplimiento de la autenticación telefónica de reCAPTCHA.

Inhabilitar reCAPTCHA SMS defense

Para inhabilitar la defensa por SMS de reCAPTCHA, usa APIs Explorer de Google para actualizar la configuración del proyecto. Para ello, introduce la siguiente URL HTTP en una ventana nueva del navegador en la que hayas iniciado sesión en 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"}}}

Sustituye PROJECT_ID por el ID del proyecto.

Para inhabilitar reCAPTCHA SMS defense mientras usas la protección frente a bots, consulta Inhabilitar reCAPTCHA SMS defense mientras usas la protección frente a bots.

Siguientes pasos

Consulta más información sobre la función de defensa por SMS de reCAPTCHA.