Habilita reCAPTCHA Enterprise

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

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

Importante: Esta función solo admite accesos y registros con correo electrónico y contraseña. el restablecimiento de contraseñas y los accesos a vínculos de correo electrónico. Si se bloquea un usuario legítimo, consulta Solución de problemas para conocer los pasos de resolución.

Descripción general

Cuando configuras la integración de Identity Platform con reCAPTCHA, Identity Platform aprovisiona claves de sitio de reCAPTCHA basadas en la puntuación en tu proyecto en tu nombre. Cuando un usuario accede a su aplicación o sitio mediante alguna de las siguientes operaciones: el SDK cliente carga reCAPTCHA:

Operación	Método
Acceso con correo electrónico y contraseña	signInWithPassword
Registro con correo electrónico y contraseña	signUpPassword
Acceso mediante vínculo de correo electrónico	getOobCode
Restablecimiento de contraseña	getOobCode

Luego, reCAPTCHA proporciona a Identity Platform indicadores de riesgo 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 Enterprise.

Importante: En este documento, usarás los siguientes componentes facturables de Google Cloud:

• reCAPTCHA Enterprise
• Identity Platform

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Antes de comenzar

Configura el acceso por correo electrónico para los usuarios.

Crea una cuenta de servicio

Antes de habilitar reCAPTCHA, debes crear una cuenta de servicio para cada proyecto que usará reCAPTCHA y otorgarle acceso a reCAPTCHA. Esto permite que Identity Platform administre las claves reCAPTCHA en tu nombre.

Para crear una cuenta de servicio, haz lo siguiente:

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

2. Otorga a la cuenta de servicio acceso a reCAPTCHA:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/identitytoolkit.serviceAgent
   

   Reemplaza lo siguiente:

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

Habilita reCAPTCHA

reCAPTCHA tiene dos modos que te ayudan a proteger a los usuarios:

• Auditoría: Cuando se habilita, Identity Platform crea uno o más reCAPTCHA claves 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 emitidas durante el modo de auditoría para determinar si debes habilitar la aplicación de reCAPTCHA.
• Aplicación: Cuando se habilita, Identity Platform crea uno o más 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. Solo habilita la aplicación forzosa después de haber migrado todos tus clientes a un SDK con Compatibilidad con reCAPTCHA.

Importante: No edites ni borres las claves de reCAPTCHA que se llamen "Clave para la integración de Identity Platform con reCAPTCHA", a menos que reCAPTCHA esté inhabilitado. Esto evita que Identity Platform aplicar la protección de reCAPTCHA. Además, los SDKs de Identity Platform no pueden generar tokens a partir de las claves de reCAPTCHA que generas por tu cuenta.

Para habilitar reCAPTCHA, haz lo siguiente:

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

2. Habilita la integración de Identity Platform con reCAPTCHA para un proyecto que use 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:

   // Get project config
   const getProjectConfig = () => {
     getAuth().projectConfigManager().getProjectConfig()
     .then((response) => {
       console.log('Project reCAPTCHA config: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error getting project config:', error);
     });
   }
   
   // Update project config with reCAPTCHA config
   const updateConfigRequest = {
     recaptchaConfig: {
       emailPasswordEnforcementState:  'AUDIT',
       managedRules: [{
         endScore: 0.3,
         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);
     });
   }
   

3. Habilita la integración de Identity Platform con reCAPTCHA para un usuario que use el SDK de Admin. Por ejemplo:

   // Update tenant with reCAPTCHA config
   const updateTenantRequest = {
     recaptchaConfig: {
       emailPasswordEnforcementState:  'AUDIT',
       managedRules: [{
         endScore: 0.3,
         action: 'BLOCK'
       }]
     }
   };
   const updateTenantWithRecaptchaConfig = () => {
     getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest)
     .then((response) => {
       console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error updating the tenant:', error);
     });
   }
   

   Reemplaza lo siguiente:

   • TENANT_ID: Es el ID de usuario.
   Nota: Identity Platform no admite la función multiusuario con reCAPTCHA. en plataformas móviles.

4. Si usas Identity Platform en plataformas de Apple o Android, debes registrarte tu app desde Firebase console:

   • Para plataformas de Apple, registra cada ID de paquete que use Identity Platform.
   • Para Android, registra cada nombre de paquete de Android que use Identity Platform

5. 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 del dominio y haz clic en Agregar para guardarlo.

   El aprovisionamiento de la clave del sitio puede tardar varios minutos en completarse. Para asegurarte de que tus flujos estén protegidos, verifica las métricas.

Configura el SDK de cliente

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

Web

1. Actualiza a la versión más reciente del SDK web. La compatibilidad con reCAPTCHA está disponible en las versiones 9.20.0 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 protege a los proveedores que configuraste.

2. Para reducir la cantidad de llamadas de red que realiza el SDK y mejorar la recopilación de indicadores de reCAPTCHA, te recomendamos que lo configures de forma explícita de la siguiente manera:

   import { initializeRecaptchaConfig } from '@firebase/auth';
   
   // Initialize Firebase Auth
   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 31.5.0 del SDK de Android o una posterior. La compatibilidad con reCAPTCHA requiere el nivel de API 19 (KitKat) o una versión posterior, y Android 4.4 o una versión posterior. Después de integrar el SDK de Android en la app, esta recupera automáticamente la configuración de reCAPTCHA y protege a los proveedores que configuraste.

2. Agrega la siguiente regla de compilación a la sección de dependencias de tu archivo Archivo build.gradle:

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

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

3. Para reducir la cantidad de llamadas de red que realiza el SDK y realizar reCAPTCHA la recopilación de indicadores sea más eficaz, recomendamos configurarlo explícitamente de la siguiente manera:

   • Kotlin:

   // Initialize Firebase Auth
   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 Auth
   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 10.14.0 o una posterior del SDK de iOS. Después de integrar el SDK de iOS con la app, esta recupera automáticamente la configuración de reCAPTCHA y protege a los proveedores que configuraste.

2. Si quieres 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 vinculadores. Navega a Objetivo > Configuración de compilación > Todas > Vinculación y verifica que Other Linker Flags muestre -ObjC.

4. Para reducir la cantidad de llamadas de red que realiza el SDK y hacer que la recopilación de indicadores de reCAPTCHA sea más eficaz, te recomendamos que lo configures de forma explícita de la siguiente manera:

   • Swift:

   // Initialize Firebase Auth
   try await Auth.auth().initializeRecaptchaConfig()
   

   • Objective‐C:

   // Initialize Firebase Auth
   [[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
     // Firebase Auth initialization finished
   }];
   

Métricas de reCAPTCHA

Después de habilitar reCAPTCHA, supervisa sus métricas que emite tu proyecto para garantizar la protección de los flujos de autenticación. Si el aprovisionamiento de claves del sitio de reCAPTCHA falla o si el servicio es necesario no se crearon las cuentas, no se puede abrir el reCAPTCHA.

Asegúrate de que la autenticación de reCAPTCHA funcione examinando las siguientes métricas que tu proyecto emite a Cloud Monitoring:

identitytoolkit.googleapis.com/recaptcha/verdict_count

Hace un seguimiento de los diferentes veredictos que muestra reCAPTCHA. Se genera un veredicto si hay un token presente. Puedes filtrar los siguientes veredictos:

• PASSED: Indica que se permite una solicitud determinada cuando la aplicación forzosa está habilitada.
• FAILED_AUDIT: Indica que se rechazó una solicitud determinada cuando reCAPTCHA modo de auditoría esté habilitado.
• FAILED_ENFORCE: Indica que se rechazó una solicitud determinada cuando reCAPTCHA el modo de aplicación forzosa esté habilitado.
• CLIENT_TYPE_MISSING: Indica que falta un cliente en una solicitud determinada. cuando se habilita la aplicación de reCAPTCHA. Esto suele ocurrir si se envió una solicitud con una versión desactualizada del SDK del cliente que no tiene Compatibilidad con reCAPTCHA.
• KEYS_MISSING: Indica que no se puede verificar una solicitud determinada debido a la incapacidad de recuperar o generar claves de reCAPTCHA válidas cuando la aplicación de reCAPTCHA está habilitada.

Para modificar tus rangos de puntuación y cambiar la proporción de los veredictos de aprobado a reprobado, consulta Habilita reCAPTCHA Enterprise.

identitytoolkit.googleapis.com/recaptcha/token_count

Realiza un seguimiento de la cantidad y el estado de los tokens de reCAPTCHA que recibió el en el backend de Identity Platform. Puedes filtrar según los siguientes estados:

• VALID: Indica que el token de reCAPTCHA que se pasó es válido.
• EXPIRED: Indica que venció el token de reCAPTCHA que se pasó. Un token vencido puede indicar problemas de red del cliente o abuso.
• DUPLICATE: Indica que el token de reCAPTCHA que se pasó es un que está duplicado. Un token duplicado puede indicar problemas o abuso en la red del cliente.
• INVALID: Indica que el token de reCAPTCHA que se pasó no es válido. Un token no válido puede indicar un abuso.
• MISSING: Indica que el token de reCAPTCHA no existe en la solicitud dada. La falta de tokens puede indicar que la app cliente está desactualizada.
• UNCHECKED: Indica que no se verificó el token de reCAPTCHA. debido a veredictos de CLIENT_TYPE_MISSING o KEYS_MISSING.

Si tu app se lanzó correctamente a los usuarios, verás tráfico con tokens válidos. Es probable que la cantidad de tokens válidos sea proporcional a la cantidad de usuarios que usan tu app actualizada.

identitytoolkit.googleapis.com/recaptcha/risk_scores

Realiza un seguimiento de la distribución de la puntuación de reCAPTCHA. Esto puede ayudarte a definir los rangos de puntuación óptimos para tu configuración.

Usa estas métricas para determinar si puedes habilitar la aplicación forzosa. Antes de habilitar la aplicación forzosa, debes tener en cuenta lo siguiente:

• Si la mayoría de las solicitudes recientes tiene tokens válidos y la proporción es PASSED. los veredictos de FAILED_AUDIT o FAILED_ENFORCE son aceptables para tu empresa caso, considera habilitar la aplicación.
• Si es probable que la mayoría de las solicitudes recientes provengan de clientes desactualizados, considera lo siguiente: esperando que más usuarios actualicen la app antes de habilitar la aplicación forzosa. La aplicación de la integración de Identity Platform con reCAPTCHA interrumpe las versiones anteriores de la app que no están integradas con reCAPTCHA.

Para ver estas métricas, haz lo siguiente:

1. En la consola de Google Cloud, ve a la página Explorador de métricas.

   Dirígete al Explorador de métricas

2. En Selecciona una métrica, ingresa Identity Toolkit Tenant. Si usas multitenancy, puedes ver las métricas de cada inquilino, así como del proyecto superior, si dejas tenant_name vacío.

Habilita la aplicación forzosa

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úrese de no interrumpir a los usuarios existentes, incluidos aquellos que podrían estar usando una una versión anterior de la app.

Para habilitar la aplicación forzosa de reCAPTCHA para un proyecto o usuario, usa el SDK de Admin para ejecutar lo siguiente:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

Inhabilitar reCAPTCHA

Para inhabilitar reCAPTCHA, usa el SDK de Admin para ejecutar lo siguiente:

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

Cómo anular 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 una puntuación de reCAPTCHA para un usuario determinado el acceso puede ser bajo, pero el usuario es de confianza o se verificó mediante otro significa y, por lo tanto, 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.

Soluciona problemas

Los usuarios no pueden acceder, registrarse ni restablecer su contraseña

Es posible que los usuarios estén usando una versión desactualizada de la app. Si no proporcionaste una versión actualizada de tu app que use el SDK cliente, haz lo siguiente: desactivar inmediatamente el modo de aplicación. De lo contrario, pídeles a tus usuarios que actualicen la app.

Como alternativa, es posible que se bloquee a los usuarios según tu configuración actual. Pruebe lo siguiente:

• Considera una configuración más permisiva a través del ajuste. Puntuaciones clave de reCAPTCHA.
• Pídele al usuario que pruebe otro dispositivo, navegador o red.
• Vuelve al modo de auditoría y supervisa las métricas antes de volver a habilitar el modo de aplicación.