Se usó la API de Cloud Translation para traducir esta página.

Integra Identity Platform con la API de reCAPTCHA Enterprise

En este documento, se muestra cómo usar la integración de Identity Platform con la API de reCAPTCHA Enterprise para mejorar la seguridad de tus usuarios. Esta función hace que tu app sea más resistente al spam, el abuso y otras actividades fraudulentas.

La integración crea una evaluación de reCAPTCHA Enterprise en tu nombre para validar las solicitudes de los usuarios. Para obtener información sobre los precios, consulta los precios de reCAPTCHA.

Descripción general

Cuando configuras la integración de Identity Platform con la API de reCAPTCHA Enterprise, habilitas la función de protección predeterminada de reCAPTCHA: la protección contra bots de reCAPTCHA. Con la protección contra bots, Identity Platform aprovisiona claves de reCAPTCHA basadas en puntuaciones en tu proyecto en tu nombre. Cuando un usuario accede a tu app o sitio con cualquiera de las siguientes operaciones, el SDK de cliente carga reCAPTCHA cuando el proveedor correspondiente está habilitado.

Proveedor	Operación	Método
`passwordProvider`	Acceso con correo electrónico y contraseña	`signInWithPassword`
	Registro con correo electrónico y contraseña	`signUpPassword`
	Acceso con vínculo de correo electrónico	`getOobCode`
	Restablecimiento de contraseña	`getOobCode`
`phoneProvider`	Registro o acceso con 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 puntuaciones que evalúan el riesgo de la solicitud según tu configuración y tolerancia al riesgo.

Para obtener más información, consulta la descripción general de reCAPTCHA.

Antes de comenzar

Según el tipo de flujo de autenticación que deseas proteger con reCAPTCHA, asegúrate de haber configurado lo siguiente:

Para los flujos de autenticación con correo electrónico y contraseña, asegúrate de haber configurado el acceso con correo electrónico para los usuarios.
Para los flujos de autenticación basados en SMS, asegúrate de haber integrado al menos una de las siguientes opciones:
- Acceso con teléfono para los usuarios.
- Autenticación de varios factores para tu app para Web, Android o iOS

Cree una cuenta de servicio

La integración de Identity Platform con la API de reCAPTCHA Enterprise requiere una cuenta de servicio de Identity Platform para cada proyecto que usará reCAPTCHA. Esto permite que Identity Platform administre las claves de reCAPTCHA en tu nombre. Si ya creaste una cuenta de servicio, otórgale acceso a reCAPTCHA.

Si aún no creaste una cuenta de servicio o tienes proyectos adicionales que deseas proteger con reCAPTCHA, haz lo siguiente:

Usa Google Cloud CLI para crear una cuenta de servicio:

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

Reemplaza PROJECT_ID por el ID del proyecto.

Otorga a la cuenta de servicio acceso a reCAPTCHA:

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.

Modos de protección contra bots de reCAPTCHA

La protección contra bots de reCAPTCHA tiene dos modos que te ayudan a proteger a los usuarios: auditoría y aplicación. Estos modos difieren en su comportamiento según el proveedor de identidad.

Proveedor de correo electrónico y contraseña

Los modos de auditoría y aplicación se comportan de la siguiente manera para los flujos de autenticación de correo electrónico y contraseña.

Modo de auditoría

Cuando configuras la aplicación forzosa de correo electrónico y contraseña en el modo de auditoría, Identity Platform crea una o más claves de reCAPTCHA en tu proyecto que se usan para evaluar el tráfico a las APIs de Identity Platform sin bloquear ninguna solicitud. Usa las métricas que se emiten durante el modo de auditoría para determinar si debes habilitar la aplicación de reCAPTCHA.

Modo de aplicación forzosa

Cuando configuras la aplicación forzosa de correo electrónico y contraseña en el modo de aplicación forzosa, Identity Platform crea una o más claves de reCAPTCHA en tu proyecto que se usan para evaluar el tráfico a las APIs de Identity Platform. Se rechazan las solicitudes a la API que no incluyen un token de reCAPTCHA. Habilita la aplicación forzosa solo después de que hayas migrado todos tus clientes a un SDK con compatibilidad con reCAPTCHA.

Proveedor de telefonía

Los modos de auditoría y aplicación se comportan de la siguiente manera en los flujos de autenticación telefónica.

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 bots de reCAPTCHA para la verificación de apps. Si la solicitud del usuario supera la evaluación de protección contra bots, 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 protección contra bots y usas el SDK de 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 protección contra bots, 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 protección contra bots, 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 protección contra bots, 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 para aplicar el modo forzoso, Identity Platform usa la protección contra bots de reCAPTCHA para la verificación de apps. Si la solicitud del usuario pasa la evaluación de protección contra bots, 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 evaluación de protección contra bots, 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.

Configura la integración de Identity Platform con la API de reCAPTCHA Enterprise

Para configurar la integración de Identity Platform con la API de reCAPTCHA Enterprise, realiza las siguientes tareas:

Usa el SDK de Admin para establecer el estado de aplicación forzosa de reCAPTCHA y habilitar la protección contra bots.
Configura el SDK de cliente para la plataforma de tu app.

Te recomendamos que primero habilites la aplicación forzosa de reCAPTCHA en el modo de auditoría y supervises las métricas de reCAPTCHA que emite tu proyecto para asegurarte de que los flujos de autenticación estén protegidos de forma adecuada. Esto se hace para que no interrumpas el tráfico de los usuarios mientras auditas su uso de reCAPTCHA. Después de verificar que tus flujos de autenticación están protegidos, configura la protección contra bots en ENFORCE.

Habilita la protección de reCAPTCHA contra bots

Proveedor de correo electrónico y contraseña

Para habilitar la protección de reCAPTCHA contra bots para los flujos de autenticación con correo electrónico y contraseña, haz lo siguiente:

Si aún no lo hiciste, habilita la API de reCAPTCHA Enterprise en tu proyecto.
Para habilitar la protección contra bots en un proyecto, usa el SDK de Admin. La compatibilidad con reCAPTCHA está disponible en las versiones 11.7.0 y posteriores del SDK de Admin de Node.js.

Por ejemplo:
```
// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE_MODE',
    managedRules: [{
      endScore: END_SCORE,
      action: 'BLOCK'
    }]
  }
};
const updateProjectConfigWithRecaptcha = () => {
  getAuth().projectConfigManager().updateProjectConfig(updateConfigRequest).then((response) => {
    console.log('Updated reCAPTCHA config for project: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error updating project config:', error);
  });
}
```
Reemplaza lo siguiente:
- ENFORCE_MODE: Es el modo que deseas establecer para la aplicación forzosa de la autenticación de correo electrónico y contraseña de reCAPTCHA. Los valores válidos son OFF, AUDIT y ENFORCE. Para habilitar la protección contra bots, este parámetro debe establecerse en AUDIT o ENFORCE. Cuando habilites la protección contra bots 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 protección contra bots de reCAPTCHA.
- END_SCORE: Es la puntuación de evaluación de protección contra bots más baja que puede tener una solicitud antes de que falle. Puedes establecer esta puntuación entre 0.0 y 1.0. Por ejemplo, si estableces un umbral de 0.6, reCAPTCHA rechaza cualquier solicitud con un 0.5 o inferior. Por lo tanto, cuanto más alto establezcas la puntuación, más estrictas serán las reglas.
También puedes habilitar la protección contra bots con el mismo método de configuración para un tenant con el SDK de Admin. Para obtener más información sobre cómo actualizar un inquilino, consulta Cómo actualizar un inquilino.
Si usas Identity Platform en iOS o Android, debes registrar tu app desde Firebase console:
- Para iOS, registra cada ID de paquete que use Identity Platform.
- Para Android, registra cada nombre de paquete de Android que use Identity Platform.
Si usas Identity Platform en la Web, debes agregar un dominio autorizado para cada dominio que use reCAPTCHA. Para agregar dominios autorizados, haz lo siguiente:
1. En la consola de Google Cloud, ve a la página de 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 claves de reCAPTCHA puede tardar varios minutos en completarse.
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 bots para asegurarte de que tus flujos estén protegidos.

Proveedor de telefonía

Para habilitar la protección contra bots de reCAPTCHA para los flujos de autenticación basados en SMS, haz lo siguiente:

Si aún no lo hiciste, habilita la API de reCAPTCHA Enterprise en tu proyecto.
Para habilitar la protección contra bots en un proyecto, usa el SDK de Admin. La compatibilidad con reCAPTCHA está disponible en las versiones 12.7.0 y posteriores del SDK de Admin de Node.js.

Por ejemplo:
```
// Update project config with reCAPTCHA config
const updateProjectConfigRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE_MODE',
    managedRules: [{ endScore: END_SCORE, action: 'BLOCK' }],
    useSmsBotScore: 'true',
  }
}
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 bots para flujos basados en SMS, este parámetro debe establecerse en AUDIT o ENFORCE, y useSmsBotScore debe establecerse en true.
  
  Cuando habilites la protección contra bots 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 protección contra bots de reCAPTCHA.
- END_SCORE: Es la puntuación de evaluación de protección contra bots más baja que puede tener una solicitud antes de que falle. Puedes establecer esta puntuación entre 0.0 y 1.0. Por ejemplo, si estableces un umbral de 0.6, reCAPTCHA rechaza cualquier solicitud con un 0.5 o inferior. Por lo tanto, cuanto más alto establezcas la puntuación, más estrictas serán las reglas.
También puedes habilitar la protección contra bots con el mismo método de configuración para un tenant con el SDK de Admin. Para obtener más información sobre cómo actualizar un usuario, consulta Cómo actualizar un usuario.

Nota: Identity Platform no admite el uso de la autenticación telefónica ni la autenticación de varios factores por SMS con varios usuarios en plataformas para dispositivos móviles.
Si usas Identity Platform en iOS o Android, debes registrar tu app desde Firebase console:
- Para iOS, registra cada ID de paquete que use Identity Platform.
- Para Android, registra cada nombre de paquete de Android que use Identity Platform.
Si usas Identity Platform en la Web, debes agregar un dominio autorizado para cada dominio que use reCAPTCHA. Para agregar dominios autorizados, haz lo siguiente:
1. En la consola de Google Cloud, ve a la página de 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 claves de reCAPTCHA puede tardar varios minutos en completarse.
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 bots 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

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.

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

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.
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.

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

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.
Para integrar el SDK de reCAPTCHA para iOS a tu app, consulta Prepara tu entorno.
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.

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 bots

Antes de establecer la aplicación forzosa de reCAPTCHA en el modo de aplicación forzosa, te recomendamos que uses el modo de auditoría y supervises las métricas de reCAPTCHA que emite tu proyecto para asegurarte de que los flujos de autenticación 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. Si falla el aprovisionamiento de la clave de reCAPTCHA o si no se crearon las cuentas de servicio requeridas, los intentos de autenticación de reCAPTCHA aún se realizan correctamente.

Para asegurarte de que la autenticación de reCAPTCHA funcione, examina las siguientes métricas que tu proyecto emite a Cloud Monitoring:

identitytoolkit.googleapis.com/recaptcha/verdict_count: Realiza un seguimiento de los diferentes veredictos que muestra reCAPTCHA.
identitytoolkit.googleapis.com/recaptcha/token_count: Hace un seguimiento de la cantidad y el estado de los tokens de reCAPTCHA que recibe el backend de Identity Platform.
identitytoolkit.googleapis.com/recaptcha/risk_scores: Realiza un seguimiento de la distribución de la puntuación de protección contra bots.

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

Aplica la protección de reCAPTCHA contra bots

Después de verificar que tu app recibe 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.

Proveedor de correo electrónico y contraseña

Para habilitar la aplicación forzosa de reCAPTCHA para los flujos de autenticación con correo electrónico y contraseña en un proyecto o inquilino, usa el SDK de Admin para ejecutar lo siguiente:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    }]
  }
};

Proveedor de telefonía

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 lo siguiente:

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

Cómo inhabilitar la protección de reCAPTCHA contra bots

Proveedor de correo electrónico y contraseña

Para inhabilitar la protección contra bots para los flujos de autenticación con correo electrónico y contraseña, usa el SDK de Admin para ejecutar el siguiente comando:

const disableRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'OFF',
  }
};

Proveedor de telefonía

Para inhabilitar la protección contra bots para los flujos de autenticación basados en SMS, usa el SDK de Admin para ejecutar el siguiente comando:

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

Anula los veredictos de reCAPTCHA con funciones de Cloud Run

Además de configurar umbrales de puntuación, puedes anular un veredicto de reCAPTCHA para un token determinado con una función de bloqueo personalizada de Cloud Run. Esto es útil en los casos en que la puntuación de reCAPTCHA para el acceso de un usuario determinado puede ser baja, pero el usuario es de confianza o se verificó a través de otros medios, por lo que puede completar el acceso.

Para obtener más información sobre cómo configurar funciones de bloqueo con reCAPTCHA, consulta Extiende Firebase Authentication con Cloud Functions de bloqueo.

¿Qué sigue?

Habilita la protección contra el fraude de cargos telefónicos por SMS de reCAPTCHA para los flujos de autenticación basados en SMS.
Obtén más información para usar tu propia clave de reCAPTCHA.
Obtén más información para supervisar las métricas de reCAPTCHA.
Obtén más información sobre reCAPTCHA.