Habilitar reCAPTCHA Enterprise

En este documento, se muestra cómo usar la integración de Identity Platform con reCAPTCHA Enterprise 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 Enterprise 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 Enterprise.

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

Descripción general

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

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

Luego, reCAPTCHA le 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 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 con correo electrónico para los usuarios.

Crear una cuenta de servicio

Antes de habilitar reCAPTCHA Enterprise, debes crear una cuenta de servicio para cada proyecto que usará reCAPTCHA y otorgar a cada cuenta de servicio acceso a reCAPTCHA Enterprise. Esto permite que Identity Platform administre las claves de 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 Enterprise:

   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.

Habilitar reCAPTCHA Enterprise

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

• Auditoría: Cuando se habilita, Identity Platform crea una o más claves de reCAPTCHA Enterprise 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 forzosa de reCAPTCHA.
• Aplicación: Cuando se habilita, Identity Platform crea una o más claves de reCAPTCHA Enterprise en tu proyecto que se usan para evaluar el tráfico a las APIs de Identity Platform. Las solicitudes a la API que no incluyen un token de reCAPTCHA se rechazan. Habilita la aplicación forzosa solo después de migrar todos tus clientes a un SDK compatible con reCAPTCHA Enterprise.

Importante: No edites ni borres las claves de reCAPTCHA Enterprise llamadas “Clave para la integración de Identity Platform con reCAPTCHA Enterprise” a menos que reCAPTCHA esté inhabilitado. Esto evita que Identity Platform aplique la protección de reCAPTCHA. Además, los SDK de Identity Platform no pueden generar tokens a partir de claves de reCAPTCHA que generes por tu cuenta.

Para habilitar reCAPTCHA Enterprise, haz lo siguiente:

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

2. Habilita la integración de Identity Platform con reCAPTCHA Enterprise para un proyecto mediante el SDK de Admin. La asistencia de reCAPTCHA Enterprise 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. Habilitar la integración de Identity Platform con reCAPTCHA Enterprise para un usuario mediante el SDK de administrador 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 multiusuarios con reCAPTCHA Enterprise en plataformas móviles.

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

   • Para las plataformas de Apple, registra cada ID del 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 las claves de sitio puede tardar varios minutos en completarse. Para asegurarte de que tus flujos están protegidos, verifica las metrics.

Configura el SDK cliente

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

Web

1. Actualiza el SDK web a la versión más reciente. La compatibilidad con reCAPTCHA Enterprise está disponible en la versión 9.20.0 y posteriores del SDK de JavaScript. Después de integrar el SDK web en tu app, recupera automáticamente la configuración de reCAPTCHA Enterprise y protege a los proveedores que hayas configurado.

2. Para reducir la cantidad de llamadas de red que realiza el SDK y mejorar la recopilación de indicadores de reCAPTCHA, te recomendamos configurarlos 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 o posterior del SDK de Android. La compatibilidad con reCAPTCHA Enterprise 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 tu app, recupera automáticamente tu configuración de reCAPTCHA Enterprise y protege a los proveedores que hayas configurado.

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

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

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

3. Para reducir la cantidad de llamadas de red que realiza el SDK y lograr que la recopilación de indicadores de reCAPTCHA sea más eficaz, recomendamos configurarlo de forma explícita 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 posterior del SDK de iOS. Una vez que hayas integrado el SDK para iOS en tu app, recuperará automáticamente la configuración de reCAPTCHA Enterprise y protegerá a los proveedores que hayas configurado.

2. Si deseas integrar el SDK de reCAPTCHA para iOS en tu app, consulta Prepara tu entorno.

3. Asegúrate de que -ObjC aparezca en las marcas del vinculador. Ve a Target > Build Settings > All > Linking y verifica que Other Linker Flags muestre -ObjC.

4. Para reducir la cantidad de llamadas de red que realiza el SDK y lograr 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 Enterprise

Después de habilitar reCAPTCHA Enterprise, supervisa las métricas de reCAPTCHA que emite tu proyecto para asegurarte de que los flujos de autenticación estén protegidos. Si el aprovisionamiento de claves del sitio de reCAPTCHA falla o si no se crearon las cuentas de servicio necesarias, la autenticación de reCAPTCHA falla.

Examina las siguientes métricas que emite tu proyecto en Cloud Monitoring para asegurarte de que la autenticación de reCAPTCHA esté funcionando:

identitytoolkit.googleapis.com/recaptcha/verdict_count

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

• PASSED: Indica que una solicitud determinada está permitida cuando la aplicación forzosa está habilitada.
• FAILED_AUDIT: Indica que se rechaza una solicitud determinada cuando se habilita el modo de auditoría de reCAPTCHA.
• FAILED_ENFORCE: Indica que se rechaza una solicitud determinada cuando el modo de aplicación de reCAPTCHA está habilitado.
• CLIENT_TYPE_MISSING: Indica que a una solicitud determinada le falta un tipo de cliente cuando está habilitada la aplicación forzosa de reCAPTCHA. Esto suele ocurrir si se envió una solicitud con una versión desactualizada del SDK cliente que no es compatible con reCAPTCHA.
• KEYS_MISSING: Indica que no se puede verificar una solicitud determinada debido a la imposibilidad de recuperar o generar claves de reCAPTCHA válidas cuando está habilitada la aplicación forzosa de reCAPTCHA.

Para modificar los rangos de puntuación a fin de cambiar la proporción de veredictos aprobados y con errores, consulta Habilita reCAPTCHA Enterprise.

identitytoolkit.googleapis.com/recaptcha/token_count

Realiza un seguimiento de la cantidad y el estado de los tokens de reCAPTCHA Enterprise que recibe el backend de Identity Platform. Puedes filtrar 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 podría indicar un abuso o problemas con la red del cliente.
• DUPLICATE: Indica que el token de reCAPTCHA que se pasó es un duplicado. Un token duplicado puede indicar que hay 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. Si faltan tokens, es posible que la app cliente esté desactualizada.
• UNCHECKED: Indica que no se verificó el token de reCAPTCHA debido a los 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 usen tu app actualizada.

identitytoolkit.googleapis.com/recaptcha/risk_scores

Hace un seguimiento de la distribución de puntuaciones 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 tienen tokens válidos y la proporción de PASSED a FAILED_AUDIT o los veredictos de FAILED_ENFORCE es aceptable para tu caso empresarial, considera habilitar la aplicación forzosa.
• Si es probable que la mayoría de las solicitudes recientes provengan de clientes desactualizados, considera esperar a que más usuarios actualicen la app antes de habilitar la aplicación forzosa. La aplicación de la integración de Identity Platform a reCAPTCHA Enterprise interrumpe las versiones anteriores de la app que no están integradas en reCAPTCHA Enterprise.

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 Seleccionar una métrica, ingresa Usuario de Identity Toolkit. Si usas la función multiusuario, puedes ver las métricas de cada usuario, así como el proyecto superior, si dejas tenant_name vacío.

Habilita la aplicación forzosa

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

Si quieres 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 Enterprise

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

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

Anula veredictos de reCAPTCHA Enterprise con Cloud Functions

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

Para obtener más información sobre la configuración de funciones de bloqueo con reCAPTCHA Enterprise, consulta Extiende Firebase Authentication con Cloud Functions de bloqueo.

Soluciona problemas

Los usuarios no pueden acceder, registrarse o 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, desactiva el modo de aplicación de inmediato. De lo contrario, solicita a los usuarios que actualicen la app.

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

• Considera una configuración más permisiva ajustando las puntuaciones clave de reCAPTCHA.
• Pídele al usuario que pruebe con 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.