En este documento, se muestra cómo usar la protección de cuentas de reCAPTCHA Enterprise para detectar y evitar actividades fraudulentas relacionadas con la cuenta en sitios web.
reCAPTCHA Enterprise te ayuda a proteger las acciones críticas, como el acceso y la confirmación de la compra. Sin embargo, hay muchas formas sutiles de abuso de cuenta que se pueden detectar si se observa el comportamiento de un usuario específico en un sitio web durante un período. El defensor de cuentas de reCAPTCHA Enterprise ayuda a identificar estos tipos de abusos sutiles mediante la creación de un modelo específico del sitio para que detecte una tendencia de comportamiento sospechoso o un cambio en la actividad. Mediante el uso del modelo específico para sitios, el defensor de cuentas de reCAPTCHA Enterprise te ayuda a detectar lo siguiente:
- Actividades sospechosas
- Cuentas con comportamientos similares
- Solicitudes provenientes de dispositivos que se marcaron como de confianza para usuarios específicos
Según el análisis del defensor de cuentas de reCAPTCHA Enterprise y el modelo específico del sitio, puedes tomar las siguientes medidas:
- Restringir o inhabilitar cuentas fraudulentas
- Evitar los intentos de apropiación de la cuenta.
- Mitigar las apropiaciones de cuenta exitosas
- Otorga acceso solo a las solicitudes que provengan de cuentas de usuario legítimas.
- Reduce las dificultades para los usuarios que acceden desde uno de sus dispositivos de confianza.
Antes de comenzar
Configura tus páginas web para el defensor de cuentas de reCAPTCHA Enterprise
El defensor de cuentas de reCAPTCHA Enterprise requiere una comprensión integral de las actividades de la cuenta para permitir una detección eficaz. Para comenzar a proporcionar actividades relacionadas con la cuenta al defensor de la cuenta de reCAPTCHA Enterprise y crear y mejorar el modelo específico del sitio, haz lo siguiente:
- Habilita la recopilación de datos de telemetría horizontal.
- Genera informes sobre las acciones críticas de los usuarios.
- Evalúa los eventos críticos de los usuarios.
- Anota eventos del usuario para ajustar el modelo específico de tu sitio.
Habilitar la recopilación de datos de telemetría horizontal
El defensor de cuentas de reCAPTCHA Enterprise requiere una vista completa de las acciones de los usuarios, por ejemplo, si este accedió o no. Para habilitar la recopilación pasiva de datos de telemetría horizontal por parte del defensor de cuentas de reCAPTCHA Enterprise, carga la secuencia de comandos de JavaScript de reCAPTCHA Enterprise con la clave del sitio basada en puntuaciones que creaste en segundo plano en todas las páginas web que forman parte del flujo de trabajo del usuario.
En el siguiente ejemplo, se muestra cómo cargar la secuencia de comandos de JavaScript de reCAPTCHA Enterprise en una página web.
<head> <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script> .... </head>
Genera informes sobre las acciones críticas de los usuarios
Para detectar patrones de actividad sospechosa y comprender mejor los patrones de actividad típicos en tu sitio, el defensor de cuentas de reCAPTCHA Enterprise necesita la información sobre las acciones críticas del usuario. Por lo tanto, informa las acciones críticas del usuario en las páginas web llamando a grecaptcha.enterprise.execute() en esas acciones.
Recomendamos informar todas las acciones críticas del usuario, ya que ayudan a recopilar indicadores adicionales. Para cada acción del usuario que desees denunciar, reemplaza el valor del parámetro action
de grecaptcha.enterprise.execute()
con un nombre de acción que describa la acción del usuario.
En la siguiente tabla, se incluyen los nombres de las acciones que puedes usar al informar las acciones críticas del usuario.
Nombre de la acción | Evento o acción iniciado por el usuario |
---|---|
LOGIN |
Accede al sitio web. |
REGISTRATION |
Registro en el sitio web. |
SECURITY_QUESTION_CHANGE |
Solicita cambiar la pregunta de seguridad. |
PASSWORD_RESET |
Solicita restablecer la contraseña. |
PHONE_NUMBER_UPDATE |
Solicita actualizar el número de teléfono. |
EMAIL_UPDATE |
Solicita actualizar la dirección de correo electrónico. |
ACCOUNT_UPDATE |
Solicita actualizar la información relacionada con la cuenta, como los detalles de contacto. |
TRIGGER_MFA |
Una acción que activa un desafío de MFA. |
REDEEM_CODE |
Solicita canjear un código. |
LIST_PAYMENT_METHODS |
Obtén la lista de formas de pago. |
En el siguiente ejemplo, se muestra cómo llamar a grecaptcha.enterprise.execute()
durante una actualización del número de teléfono:
<script> function onClick(e) { e.preventDefault(); grecaptcha.enterprise.ready(async () => { const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'PHONE_NUMBER_UPDATE'}); }); } </script>
Evalúa los eventos críticos de los usuarios
Cuando llamas a grecaptcha.enterprise.execute()
en una acción del usuario, esta genera un token. Para los eventos de usuario críticos, como los accesos correctos o fallidos, los registros y las acciones de los usuarios que accedieron, crea una evaluación para evaluar los resultados de la llamada a grecaptcha.enterprise.execute()
. La evaluación te proporciona un veredicto de riesgo que puedes usar para tomar una decisión sobre cómo manejar actividades potencialmente fraudulentas. Algunas de las medidas que puedes tomar son bloquear solicitudes sospechosas, cuestionar los accesos riesgosos y también investigar cuentas de interés.
El defensor de cuentas de reCAPTCHA Enterprise requiere que proporciones un identificador de cuenta estable para atribuir la actividad del usuario (como solicitudes de acceso, de acceso y de registro) a una cuenta específica. Esto ayuda al defensor de cuentas de reCAPTCHA Enterprise a comprender los patrones de actividad del usuario y a crear un modelo de actividad para cada cuenta a fin de detectar mejor el tráfico anómalo y abusivo.
Elige un identificador de cuenta estable (accountId
) que el usuario no cambie con frecuencia y proporciónalo a la evaluación en el método
projects.assessments.create
. Este identificador de cuenta estable debe tener el mismo valor para todos los eventos relacionados con el mismo usuario. Puedes proporcionar lo siguiente como identificador de la cuenta:
Identificadores de usuario
Si cada cuenta se puede asociar de forma única con un nombre de usuario, una dirección de correo electrónico o un número de teléfono estables, puedes usarlo como accountId
. Cuando proporcionas estos identificadores entre sitios (identificadores que se pueden volver a usar en varios sitios), reCAPTCHA Enterprise usa esta información para mejorar la protección de las cuentas de usuario en función de modelos entre sitios marcando los identificadores de cuenta abusivos y usando el conocimiento de los patrones de abuso entre sitios relacionados con estos identificadores.
De manera alternativa, si tienes un ID de usuario interno asociado de manera única con cada cuenta, puedes proporcionarlo como accountId
.
Con hash o encriptado
Si no tienes un ID de usuario interno asociado de forma exclusiva con cada cuenta, puedes convertir cualquier identificador estable en un identificador de cuenta opaco y específico del sitio. Este identificador aún es necesario para que el defensor de las cuentas de reCAPTCHA Enterprise comprenda los patrones de actividad del usuario y detecte comportamientos anómalos, pero no se comparte con otros sitios.
Elige cualquier identificador de cuenta estable y haz que sea opaco antes de enviarlo a reCAPTCHA Enterprise mediante el uso de encriptación o hash:
encriptación (recomendada): Encripta el identificador de la cuenta con un método de encriptación determinista que produzca un texto cifrado estable. Para obtener instrucciones detalladas, consulta Cómo encriptar datos de manera determinista. Cuando eliges la encriptación simétrica en lugar del hash, no necesitas mantener una asignación entre tus identificadores de usuario y los identificadores de usuario opacos correspondientes. Desencripta los identificadores opacos que muestra reCAPTCHA Enterprise para convertirlos en el identificador de usuario.
Hash: recomendamos generar un hash para el identificador de la cuenta mediante el método SHA256-HMAC con la sal personalizada que elijas. Debido a que los hashes son unidireccionales, debes mantener una asignación entre los hashes generados y tus identificadores de usuario para poder asignar el identificador de cuenta con hash que se devuelve a las cuentas originales.
Además de proporcionar un identificador de cuenta estable para todas las solicitudes relacionadas con la cuenta, puedes proporcionar identificadores de cuenta adicionales, potencialmente no estables, para algunas solicitudes específicas.
Los identificadores de cuenta específicos del contexto que se proporcionan junto con la accountId
ayudan a
el defensor de las cuentas de reCAPTCHA Enterprise a comprender mejor la actividad del usuario y detectar
los intentos de apropiación de cuentas para protegerlas. Cuando proporcionas identificadores adicionales,
reCAPTCHA Enterprise usa esta información para mejorar la protección de tus cuentas de usuario en función de
modelos entre sitios marcando identificadores de cuentas abusivos y usando el conocimiento de los patrones de abuso
entre sitios relacionados con estos identificadores. Por ejemplo, puedes proporcionar lo siguiente:
El nombre de usuario, la dirección de correo electrónico o el número de teléfono que se usó como identificador de acceso para las solicitudes de acceso
La dirección de correo electrónico o el número de teléfono que se verificó para una solicitud de autenticación de varios factores
Una dirección de correo electrónico o un número de teléfono (principal o secundario) que proporcionó el usuario durante una solicitud de actualización de la cuenta
Las direcciones de correo electrónico y los números de teléfono que proporciona el usuario durante una solicitud de registro
Agrega el identificador de cuenta estable elegido al parámetro accountId
en el método
projects.assessments.create
para todas las solicitudes relacionadas con la cuenta. De manera opcional, proporciona identificadores de cuenta adicionales para las solicitudes relevantes mediante el campo userIds
en la evaluación.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID del proyecto de Google Cloud.
- TOKEN: Token que se muestra a partir de la llamada
grecaptcha.enterprise.execute()
- KEY_ID: La clave reCAPTCHA asociada con el sitio
- ACCOUNT_ID: Es el identificador que está asociado de forma única con la cuenta de usuario de una cuenta de usuario de tu sitio web.
- EMAIL_ADDRESS: Opcional Una dirección de correo electrónico asociada con esta solicitud, si la hay
- PHONE_NUMBER: Opcional Un número de teléfono asociado con esta solicitud, si corresponde
- USERNAME: Opcional Un nombre de usuario asociado con esta solicitud, si corresponde
HTTP method and URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Cuerpo JSON de la solicitud:
{ "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userInfo": { "accountId": "ACCOUNT_ID", "userIds": [ { "email": "EMAIL_ADDRESS" }, { "phoneNumber": "PHONE_NUMBER" }, { "username": "USERNAME" } ] } } }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "login", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.6, }, "event": { "token": "TOKEN", "siteKey": "KEY", "userInfo": { "accountId": "ACCOUNT_ID" } }, "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000", "accountDefenderAssessment": { "labels": ["SUSPICIOUS_LOGIN_ACTIVITY"] } }
Muestra de código
Java
Para autenticarte en reCAPTCHA Enterprise, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Interpretar el veredicto de riesgo de los eventos críticos del usuario
Cuando creas una evaluación con la protección de cuentas habilitada, esta última muestra accountDefenderAssessment
como parte de la respuesta de la evaluación.
El valor de accountDefenderAssessment
te ayuda a evaluar si la actividad del usuario es legítima o fraudulenta. También muestra un ID de evaluación que debes usar cuando anotas eventos de usuario.
El siguiente ejemplo es una respuesta JSON de muestra:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "login", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.6, }, "event": { "token": "TOKEN", "siteKey": "KEY_ID", "expectedAction": "USER_ACTION" }, "name": "projects/PROJECT_ID/assessments/b6ac310000000000X", "accountDefenderAssessment": { labels: ["SUSPICIOUS_LOGIN_ACTIVITY"] } }
El campo accountDefenderAssessment
puede tener cualquiera de los siguientes valores:
Valor | Descripción |
---|---|
SUSPICIOUS_LOGIN_ACTIVITY |
Indica que la solicitud representa un riesgo alto de uso excesivo de credenciales o apropiación de cuentas. |
SUSPICIOUS_ACCOUNT_CREATION |
Indica que la solicitud representa un riesgo alto de creación abusiva de cuentas. |
PROFILE_MATCH |
Indica que los atributos del usuario coinciden con los atributos que se vieron antes para este usuario en particular. Este valor indica que el usuario utiliza un dispositivo de confianza que ya se usó para acceder a tu sitio web.
|
RELATED_ACCOUNTS_NUMBER_HIGH |
Indica que la solicitud tiene una gran cantidad de cuentas relacionadas. No implica necesariamente que la cuenta sea maliciosa, pero podría requerir más investigación. |
Anota eventos para ajustar el modelo específico de tu sitio
Para proporcionar más información al defensor de cuentas de reCAPTCHA Enterprise y mejorar el modelo de detección específico del sitio, debes anotar los eventos que evaluaste mediante la creación de evaluaciones.
Para anotar una evaluación, envía una solicitud al método projects.assessments.annotate
con el ID de evaluación. En el cuerpo de esa solicitud, debes incluir etiquetas que proporcionen información adicional sobre un evento descrito en la evaluación.
Para anotar una evaluación, haz lo siguiente:
-
Determina la información y las etiquetas que agregarás en el cuerpo JSON de la solicitud, según tu caso de uso.
En la siguiente tabla, se indican las etiquetas y los valores que puedes usar para anotar eventos:
Etiqueta Descripción Ejemplo de solicitud reasons
Obligatorio. Una etiqueta para respaldar tus evaluaciones. Proporciona detalles del evento en tiempo real en la etiqueta
reasons
unos segundos o minutos después del evento, ya que influyen en la detección en tiempo real.Para obtener la lista de valores posibles, consulta los valores de motivos.
Ejemplo: Para detectar apropiaciones de cuentas, anota si la contraseña que se ingresó era correcta con los valores
CORRECT_PASSWORD
oINCORRECT_PASSWORD
. Si implementaste tu propia MFA, puedes agregar los siguientes valores:INITIATED_TWO_FACTOR
yPASSED_TWO_FACTOR
oFAILED_TWO_FACTOR
.{ "reasons": ["INCORRECT_PASSWORD"] }
annotation
Opcional. Una etiqueta para indicar la legitimidad de las evaluaciones. En la etiqueta
annotation
, proporciona datos sobre los eventos de acceso y registro para validar o corregir tus evaluaciones de riesgos.Valores posibles:
LEGITIMATE
oFRAUDULENT
.Puedes enviar esta información en cualquier momento o como parte de un trabajo por lotes. Sin embargo, recomendamos enviar esta información en unos segundos o minutos después del evento, ya que influyen en la detección en tiempo real.
{ "annotation": "LEGITIMATE" }
accountId
Opcional. Una etiqueta para asociar un ID de cuenta a un evento.
Si creaste una evaluación sin un ID de cuenta, usa esta etiqueta para proporcionar el ID de la cuenta de un evento cuando esté disponible.
{ "accountId": "ACCOUNT_ID" }
Crea una solicitud de anotación con las etiquetas adecuadas.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- ASSESSMENT_ID: Es el valor del campo
name
que muestra la llamadaprojects.assessments.create
. - ANNOTATION: Opcional Una etiqueta para indicar si la evaluación es legítima o fraudulenta
- REASONS: Opcional Razones que respaldan tu anotación. Para obtener la lista de valores posibles, consulta los valores de motivos.
- ACCOUNT_ID: Es el identificador que está asociado de forma única con la cuenta de usuario en tu sitio web (opcional).
Para obtener más información, consulta las etiquetas de anotaciones.
HTTP method and URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Cuerpo JSON de la solicitud:
{ "annotation": ANNOTATION, "reasons": REASONS, "accountId": ACCOUNT_ID }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado
request.json
y ejecuta el siguiente comando:curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado
request.json
y ejecuta el siguiente comando:$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate" | Select-Object -Expand ContentDeberías recibir un código de estado exitoso (2xx) y una respuesta vacía.
- ASSESSMENT_ID: Es el valor del campo
Muestra de código
Java
Para autenticarte en reCAPTCHA Enterprise, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Habilitar la protección de cuentas de reCAPTCHA Enterprise
Después de configurar tus páginas web para el defensor de cuentas de reCAPTCHA Enterprise, puedes habilitarlo.
En la consola de Google Cloud, ve a la página reCAPTCHA Enterprise.
Verifica que el nombre de tu proyecto aparezca en el selector de recursos que se encuentra en la parte superior de la página.
Si no ves el nombre de tu proyecto, haz clic en el selector de recursos y, luego, selecciona tu proyecto.
- Haz clic en Configuración.
En el panel Defensor de la cuenta, haz clic en Habilitar.
En el diálogo Configura la protección de la cuenta, haz clic en Habilitar.
Es posible que la habilitación del defensor de cuentas de reCAPTCHA Enterprise tarde unas horas en propagarse a nuestros sistemas. Después de que la habilitación de funciones se propague a nuestros sistemas, deberías comenzar a recibir respuestas relacionadas con el defensor de la cuenta como parte de las evaluaciones.