En esta página, se describe cómo configurar la autenticación de varios factores (MFA), que te permite verificar la identidad de tus usuarios mediante el envío de un código de verificación por correo electrónico. Con esta función, puedes verificar que tus usuarios sean propietarios de la dirección de correo electrónico asociada con su cuenta. La MFA puede ayudar a proteger a tus usuarios contra los ataques de uso excesivo de credenciales y las apropiaciones de cuentas (ATO).
La MFA está disponible para las claves basadas en puntuación y no para las claves de casilla de verificación.
Comprende el proceso de configuración de la MFA
La función de MFA de reCAPTCHA se implementa sobre el flujo de trabajo normal de reCAPTCHA.
En un nivel alto, el flujo de trabajo de la MFA es el siguiente:
- Instrumenta el flujo de trabajo crítico en tu sitio web.
- Crea una evaluación con el token que muestra la llamada a
execute()y los parámetros de MFA para obtener unrequestTokende MFA. - Activa un desafío de MFA con el
requestTokensegún el canal que quieras usar (solo se admite el correo electrónico). - Verifica el PIN que ingresó el usuario final en tu sitio web.
- Crea una evaluación nueva con el token que se muestra en la solicitud de verificación.
Antes de comenzar
Se puede acceder a la MFA después de una revisión de seguridad, que se inicia cuando agregas una cuenta de facturación a tu proyecto. Agrega una cuenta de facturación para integrar tu sitio a esta función.
Si quieres habilitar la función de verificación por correo electrónico de la MFA, haz lo siguiente:
En la consola de Google Cloud, ve a la página reCAPTCHA.
Verifica que el nombre de tu proyecto aparezca en el selector de recursos.
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 Autenticación de varios factores, haz clic en Configurar.
En el diálogo Configurar MFA, haz lo siguiente:
- Para habilitar la verificación por correo electrónico, haz clic en el botón de activación Habilitar correo electrónico.
- En el cuadro Nombre del remitente, ingresa tu nombre.
En el cuadro Correo electrónico del remitente, ingresa tu dirección de correo electrónico.
Haz clic en Guardar.
Configura reCAPTCHA en tu sitio web con claves basadas en puntuaciones.
Instrumenta el flujo de trabajo crítico en tu sitio web
Pasa la información necesaria a reCAPTCHA a través de la función execute() para la evaluación de riesgos. La función execute() muestra una promesa que se resuelve tras la generación de tokens.
Agrega un parámetro twofactor adicional a tu función execute(), como se indica en el siguiente código de muestra:
grecaptcha.enterprise.execute(KEY_ID, {
action: 'login',
twofactor: true
}).then(token => {
// Handle the generated token.
});
Reemplaza KEY_ID por la clave basada en la puntuación que creaste para tu sitio web.
Crea una evaluación
Con el token que genera la función execute(), crea una evaluación con las bibliotecas cliente de reCAPTCHA o la API de REST desde tu backend.
En este documento, se muestra cómo crear una evaluación para la MFA con la API de REST. Para obtener información sobre cómo crear una evaluación con bibliotecas cliente, consulta Cómo crear evaluaciones para sitios web.
Antes de crear una evaluación, haz lo siguiente:
Configura la autenticación en reCAPTCHA.
El método de autenticación que elijas dependerá del entorno en el que se configure reCAPTCHA. La siguiente tabla te ayuda a elegir el método de autenticación y la interfaz compatibles para configurar la autenticación:
Entorno Interfaz Método de autenticación Google Cloud - REST
- Bibliotecas cliente
Usa cuentas de servicio conectadas. Local o en un proveedor de servicios en la nube diferente REST Usa claves de API o la federación de Workload Identity. Si quieres usar claves de API, te recomendamos que las protejas aplicando restricciones.
Bibliotecas cliente Para ello, usa los siguientes recursos:
- Para Python o Java, usa claves de API o la federación de identidades para cargas de trabajo.
Si quieres usar claves de API, te recomendamos que las protejas aplicando restricciones.
- Para otros idiomas, usa Federación de identidades para cargas de trabajo.
Elige un identificador de cuenta estable
accountIdque el usuario no cambie con frecuencia y proporciónalo a la evaluación en el métodoprojects.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 estable, puedes usarlo como
accountId. Cuando proporcionas esos identificadores entre sitios (identificadores que se pueden volver a usar en varios sitios), reCAPTCHA usa esta información para mejorar la protección de tus cuentas de usuario en función de modelos entre sitios, ya que marca los identificadores de cuentas abusivas y utiliza el conocimiento de los patrones de abuso entre sitios relacionados con estos identificadores.Como alternativa, si tienes un ID de usuario interno asociado de forma exclusiva con cada cuenta, puedes proporcionarlo como
accountId.Con codificación 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 cuentas de reCAPTCHA 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 hazlo opaco antes de enviarlo a reCAPTCHA con encriptación o hash:
encriptación (recomendado): Encripta el identificador de cuenta con un método de encriptación determinista que genere un texto cifrado estable. Para obtener instrucciones detalladas, consulta Cómo encriptar datos de forma determinista. Cuando eliges la criptografía simétrica en lugar del hash, no es necesario que mantengas una asignación entre tus identificadores de usuario y los identificadores de usuario opacos correspondientes. Desencripta los identificadores opacos que muestra reCAPTCHA para convertirlos en el identificador del usuario.
codificación hash: Te recomendamos que codifiques el identificador de cuenta con el método SHA256-HMAC con una sal personalizada de tu elección. Debido a que los hash son unidireccionales, debes mantener una asignación entre los hash generados y tus identificadores de usuario para que puedas asignar el identificador de cuenta con hash que se devuelve a las cuentas originales.
Agrega el parámetro accountId y un extremo, como una dirección de correo electrónico para verificar en la evaluación en el método projects.assessments.create.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: Es el ID de tu proyecto de Google Cloud.
- TOKEN: Es el token que se muestra a partir de la llamada
grecaptcha.enterprise.execute(). - KEY_ID: Es la clave basada en la puntuación que instalaste en tu sitio web.
- ACCOUNT_ID: Es un identificador para una cuenta de usuario que es única para tu sitio web.
- EMAIL_ID: Es la dirección de correo electrónico para la que se debe activar la solicitud de verificación.
Método HTTP y 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"
}
}
"accountVerification": {
"endpoints": [{
"emailAddress": "EMAIL_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/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:
{
[...],
"accountVerification": {
"endpoints": [{
"emailAddress": "foo@bar.com",
"requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
"lastVerificationTime": "",
}],
"latestVerificationResult": "RESULT_UNSPECIFIED"
}
}
La evaluación contiene la fecha y hora de la verificación correcta más reciente de los extremos determinados en el dispositivo que emitió el token, si corresponde. También contiene un campo requestToken por extremo, que contiene una cadena encriptada. Si decides activar una solicitud de MFA para ese extremo, debes enviar esta cadena encriptada a la página web. Los tokens de solicitud son válidos durante 15 minutos.
Acciones recomendadas
Si tienes habilitada la protección de cuentas de reCAPTCHA para tu proyecto, la respuesta de la evaluación contiene información relacionada con la protección de cuentas, además de la información relacionada con la MFA. El campo recommended_action muestra la posible acción que puedes realizar antes de activar el desafío de MFA.
En el siguiente ejemplo, se muestra una evaluación de muestra que muestra la omisión de la MFA como la acción recomendada:
{ [...], "accountDefenderAssessment": { labels: ["PROFILE_MATCH"], "recommended_action": "SKIP_2FA" } }
El campo recommended_action puede tener cualquiera de los siguientes valores:
| Valor | Descripción |
|---|---|
RECOMMENDED_ACTION_UNSPECIFIED |
Indica que el defensor de cuentas no pudo emitir un juicio sobre esta solicitud. |
SKIP_2FA |
Indica que la protección de cuentas considera que es seguro omitir la MFA para esta evaluación. Por lo general, esto significa que el usuario se verificó recientemente en tu sitio en este dispositivo. |
REQUEST_2FA |
Indica que activaste un desafío de MFA para el usuario. Para obtener más información, consulta la respuesta de la evaluación de Account Defender. |
Cómo activar un desafío de MFA en tu sitio web
Para desafiar al usuario según la información contenida en la evaluación, envía el requestToken de la MFA para el extremo que deseas verificar desde la evaluación a la página web.
Activa el desafío de MFA con una llamada a challengeAccount().
La función challengeAccount() muestra una promesa que se resuelve después de que se completa el desafío o se rechaza si hubo un error o un tiempo de espera.
Una vez finalizado, se genera un token nuevo que contiene información actualizada, que luego se envía para su evaluación.
Para activar un desafío de MFA, haz lo siguiente:
Prueba la integración de la MFA.
Activa un desafío de MFA con una llamada a
challengeAccount(). Para ello, proporciona los siguientes valores:- KEY_ID: Es la clave basada en la puntuación que instalaste en tu sitio web.
- REQUEST_TOKEN_FROM_ASSESSMENT: Es el valor del campo
requestTokende la respuesta de la evaluación. - CONTAINER_HTML_COMPONENT_ID: Es el ID del componente HTML en el que se debe renderizar el desafío de verificación. Si no especificas este parámetro, el desafío se renderizará en una superposición en la parte superior de la página.
En el siguiente ejemplo, se muestra cómo activar el desafío de MFA con una llamada a
challengeAccount():grecaptcha.enterprise.challengeAccount(KEY_ID, { 'account-token': REQUEST_TOKEN_FROM_ASSESSMENT, 'container': CONTAINER_HTML_COMPONENT_ID }).then(newToken => { // Handle the new token. });Si la solicitud
challengeAccount()se realiza correctamente, se muestra el componente HTML para ingresar el PIN recibido. Después de ingresar el PIN correcto, la variablenewTokense pasa a la función encadenada que contiene el token de veredicto que se verificará a través de una evaluación que se crea en el backend.Crea un identificador de verificación y, luego, inicia una solicitud de validación con los siguientes parámetros:
// Initialize verification handle. const verificationHandle = grecaptcha.enterprise.eap.initTwoFactorVerificationHandle( KEY_ID, REQUEST_TOKEN_FROM_ASSESSMENT ); // Call the challenge API. verificationHandle.challengeAccount().then( (challengeResponse) => { if (challengeResponse.isSuccess()) { // Handle success: This means displaying an input for the end user to // enter the PIN that they received and then call the `verifyAccount(pin)` // method. } else { // Handle API failure } });
Cómo verificar un código de MFA desde la página web
Después de obtener el PIN del usuario final, debes validar si es correcto o no.
Para validar el PIN, llama a verificationHandle.verifyAccount() con el PIN que ingresó el usuario final.
verificationHandle.verifyAccount(pin).then(
(verifyResponse) => {
if (verifyResponse.isSuccess()) {
// Handle success: Send the result of `verifyResponse.getVerdictToken()`
// to the backend in order to determine if the code was valid.
} else {
// Handle API failure
}
},
(error) => {
// Handle other errors
}
);
Crear una nueva evaluación
Crea una evaluación nueva con accountId y endpoints. Para obtener instrucciones, consulta Cómo crear una evaluación para la AUA.
Una vez que se complete el flujo de trabajo en el cliente, recibirás un token nuevo que puedes usar para obtener el veredicto de la verificación que activaste. La evaluación debe contener una marca de tiempo reciente respecto de la última verificación exitosa con un estado de resultado correcto:
En el siguiente ejemplo, se muestra una evaluación de muestra que recibes cuando creas una evaluación nueva con el token nuevo que se obtiene del sitio web:
{ [...], "accountVerification": { "endpoints": [{ "emailAddress": "foo@bar.com", "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv", "lastVerificationTime": "2020-03-23 08:27:12 PST", }], "latestVerificationResult": "SUCCESS_USER_VERIFIED" } }
El campo latestVerificationResult puede mostrar un estado diferente, como se indica en la siguiente tabla:
| Estado del resultado de la verificación | Descripción |
|---|---|
| SUCCESS_USER_VERIFIED | Se verificó correctamente al usuario. |
| ERROR_USER_NOT_VERIFIED | El usuario no pudo completar el desafío de verificación. |
| ERROR_SITE_ONBOARDING_INCOMPLETE | Tu sitio no está incorporado correctamente para usar la función. |
| ERROR_RECIPIENT_NOT_ALLOWED | Este destinatario no está aprobado para enviarle correos electrónicos (solo durante las pruebas). |
| ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED | Este destinatario ya recibió demasiados códigos de verificación en un período breve. |
| ERROR_CUSTOMER_QUOTA_EXHAUSTED | Superaste la cuota de MFA disponible. |
| ERROR_CRITICAL_INTERNAL | La verificación no se completó debido a un error interno en nuestros sistemas. |
| RESULT_UNSPECIFIED | No hay información sobre la verificación más reciente (nunca se verificó). |