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.
Descripción general
Cuando configuras la integración de Identity Platform con reCAPTCHA, Identity Platform aprovisiona claves del sitio de reCAPTCHA basadas en puntuaciones en tu proyecto por ti. Cuando un usuario accede a tu app o sitio con cualquiera 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 la contraseña | getOobCode |
Luego, reCAPTCHA le proporciona indicadores de riesgo a Identity Platform 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.
Antes de comenzar
Configura el acceso con correo electrónico de los usuarios.
Crea una cuenta de servicio
Antes de habilitar reCAPTCHA, debes crear una cuenta de servicio para cada proyecto que use reCAPTCHA y otorgar a cada cuenta de servicio acceso a reCAPTCHA. Esto permite que Identity Platform administre claves de reCAPTCHA en tu nombre.
Para crear una cuenta de servicio, 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 proyectoPROJECT_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 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 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 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. Solo habilita la aplicación forzosa después de haber migrado todos tus clientes a un SDK compatible con reCAPTCHA.
Para habilitar reCAPTCHA, haz lo siguiente:
- Si aún no lo hiciste, habilita la API de reCAPTCHA en tu proyecto.
Habilita la integración de Identity Platform con reCAPTCHA para un proyecto con el SDK de Admin. La compatibilidad con reCAPTCHA está disponible en las versiones 11.7.0 y posteriores del SDK de administrador 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); }); }
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.
Si usas Identity Platform en plataformas de Apple o Android, debes registrar tu app desde Firebase console:
- En el caso de las 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
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:
En la consola de Google Cloud, ve a la página de Identity Platform.
Ve a Configuración > Seguridad.
Haz clic en Agregar dominio.
Ingresa el nombre del dominio y haz clic en Agregar para guardarlo.
El aprovisionamiento de las claves de sitios 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 del cliente según la plataforma de tu app.
Web
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, esta recupera automáticamente la configuración de reCAPTCHA y protege a los proveedores que configuraste.
Para reducir la cantidad de llamadas de red que realiza el SDK y mejorar la recopilación de indicadores de reCAPTCHA, te recomendamos configurarlo 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
Actualiza a la versión 31.5.0 o posterior del SDK de Android. La compatibilidad con reCAPTCHA requiere el nivel de API 19 (KitKat) o superior y Android 4.4 o superior. Después de integrar el SDK de Android en tu app, esta recupera automáticamente la configuración de reCAPTCHA y protege a los proveedores que configuraste.
Agrega la siguiente regla de compilación a la sección de dependencias del archivo
build.gradle
del nivel de la app: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.
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 configurarlo de manera 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
Actualiza a la versión 10.14.0 o una posterior del SDK de iOS. Después de integrar el SDK de iOS en tu app, esta recupera automáticamente la configuración de reCAPTCHA y protege a los proveedores que configuraste.
Si quieres integrar el SDK de reCAPTCHA para iOS a tu app, consulta Prepara tu entorno.
Asegúrate de que
-ObjC
aparezca en las marcas del vinculador. Navega a Target > Build Settings > All > Linking y verifica queOther Linker Flags
muestre-ObjC
.Para reducir la cantidad de llamadas de red que realiza el SDK y 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 las métricas de reCAPTCHA que emite tu proyecto para asegurarte de que los flujos de autenticación estén protegidos. Si falla el aprovisionamiento de claves de sitio de reCAPTCHA o si no se crearon las cuentas de servicio necesarias, la autenticación de reCAPTCHA fallará.
Asegúrate de que la autenticación de reCAPTCHA funcione. Para ello, examina las siguientes métricas que el proyecto emite a Cloud Monitoring:
identitytoolkit.googleapis.com/recaptcha/verdict_count
Hace un seguimiento de los diferentes veredictos que muestra reCAPTCHA. Si hay un token presente, se genera un veredicto. Puedes filtrar los siguientes veredictos:
PASSED
: Indica que se permite una solicitud determinada cuando está habilitada la aplicación forzosa.FAILED_AUDIT
: Indica que se rechaza una solicitud determinada cuando está habilitado el modo de auditoría reCAPTCHA.FAILED_ENFORCE
: Indica que se rechaza una solicitud determinada cuando está habilitado el modo de aplicación de reCAPTCHA.CLIENT_TYPE_MISSING
: Indica que a una solicitud determinada le falta un tipo de cliente cuando la aplicación forzosa de reCAPTCHA está habilitada. Esto suele ocurrir si se envió una solicitud con una versión desactualizada del SDK del cliente que no es compatible 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 forzosa de reCAPTCHA está habilitada.
Si quieres modificar los rangos de puntuación y cambiar la proporción de los veredictos de aprobación a error, 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 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 que hay problemas o abuso en la red del cliente.DUPLICATE
: Indica que el token de reCAPTCHA que se pasó es un 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 determinada. Si faltan tokens, es posible que la app cliente esté desactualizada.UNCHECKED
: Indica que no se verificó el token de reCAPTCHA debido a veredictos deCLIENT_TYPE_MISSING
oKEYS_MISSING
.
Si tu app se lanzó correctamente para los usuarios, verás tráfico con tokens válidos. La cantidad de tokens válidos probablemente 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 tienen tokens válidos y la proporción de
PASSED
aFAILED_AUDIT
oFAILED_ENFORCE
es aceptable para tu caso comercial, 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 su 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:
En la consola de Google Cloud, ve a la página Explorador de métricas.
En Selecciona una métrica, ingresa Usuario de Identity Toolkit. Si usas la función multiusuario, puedes ver las métricas de cada usuario, así como del proyecto superior, si dejas
tenant_name
vacío.
Habilita la aplicación forzosa
Una vez que verifiques que la app recibe tráfico de usuarios aceptable, puedes habilitar la aplicación forzosa de reCAPTCHA para proteger a los usuarios. Asegúrate de no interrumpir a los usuarios existentes, incluidos los que podrían estar usando una versión anterior de la 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
Si quieres inhabilitar reCAPTCHA, usa el SDK de Admin para ejecutar lo siguiente:
const disableRequest = {
recaptchaConfig: {
emailPasswordEnforcementState: 'OFF',
}
};
Anula veredictos de reCAPTCHA con Cloud Functions
Además de configurar los umbrales de puntuación, puedes anular un veredicto de reCAPTCHA para un token determinado mediante una función de bloqueo personalizada de Cloud Functions. Esto es útil en los casos en los que una puntuación de reCAPTCHA para el acceso de un usuario determinado puede ser baja, pero el usuario es de confianza o se verificó por otros medios y, por lo tanto, se le permite completar el acceso.
Si quieres obtener más información para 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 sus contraseñas
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 de cliente, desactiva el modo de aplicación de inmediato. 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 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.