Configura la autenticación de varios factores

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 ataques de uso excesivo de credenciales y apropiaciones de cuentas (ATO).

La MFA está disponible para claves basadas en puntuaciones y no para claves de casilla de verificación.

Comprender 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 y se lanza.

En un nivel alto, el flujo de trabajo de la MFA es el siguiente:

  1. Instrumenta el flujo de trabajo fundamental en tu sitio web.
  2. Crea una evaluación con el token que muestra la llamada a execute() y los parámetros de MFA para obtener un requestToken de MFA.
  3. Activa un desafío de MFA con el requestToken según el canal que desees usar (solo compatible con correos electrónicos).
  4. Verifica el PIN que ingresó el usuario final en tu sitio web.
  5. Crea una evaluación nueva con el token que se muestra en la solicitud de verificación.

Antes de comenzar

  1. Prepara tu entorno para reCAPTCHA.

  2. Se puede acceder a la MFA después de una revisión de seguridad. Comunícate con nuestro equipo de ventas para incorporar esta función en tu sitio. Proporciona la siguiente información de integración al equipo de ventas:

    • Número de proyecto de Google Cloud
    • Claves de reCAPTCHA para incorporar
    • Promedio de QPS (mensajes de correo electrónico por segundo)
    • Máximo de QPS (mensajes de correo electrónico por segundo)
    • Para la MFA de correo electrónico, la dirección del remitente y las direcciones de correo electrónico o dominios que necesitas durante las pruebas

  3. Si deseas habilitar la función de verificación por correo electrónico de la MFA, haz lo siguiente:

    1. En la consola de Google Cloud, ve a la página reCAPTCHA.

      Ir a reCAPTCHA

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

    3. Haz clic en Configuración.

    4. En el panel Autenticación de varios factores, haz clic en Configurar.

    5. En el cuadro de diálogo Configurar MFA, haz lo siguiente:

      1. Para habilitar la verificación por correo electrónico, haz clic en el botón de activación Habilitar correo electrónico.
      2. En el cuadro Nombre del remitente, ingresa tu nombre.

      3. En el cuadro Correo electrónico del remitente, ingresa tu dirección de correo electrónico.

    6. Haz clic en Guardar.

  4. Configura reCAPTCHA en tu sitio web mediante claves basadas en la puntuación.

Instrumenta el flujo de trabajo fundamental 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 cuando se genera un token.

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.

Crear una evaluación

Con el token que genera la función execute(), crea una evaluación mediante las bibliotecas cliente de reCAPTCHA o la API de REST de tu backend.

Este documento muestra cómo crear una evaluación para la MFA mediante la API de REST. Si quieres obtener más información para crear una evaluación con las bibliotecas cliente, consulta Cómo crear evaluaciones para sitios web.

Antes de crear una evaluación, haz lo siguiente:

  • Configura la autenticación de reCAPTCHA.

    El método de autenticación que elijas dependerá del entorno en el que se configure reCAPTCHA. La siguiente tabla te ayudará a elegir el método de autenticación adecuado y la interfaz compatible para configurar la autenticación:

    Entorno Interfaz Método de autenticación
    Google Cloud
    • REST
    • Bibliotecas cliente
    		 Usa cuentas de servicio conectadas.
    Infraestructura local o con otro proveedor de servicios en la nube REST Usa claves de API o la federación de identidades para cargas de trabajo.

    Si deseas usar claves de API, te recomendamos aplicar restricciones de claves de API para protegerlas.
    Bibliotecas cliente

    Para ello, usa los siguientes recursos:

  • Elige un identificador de cuenta estable accountId que el usuario no cambie con frecuencia y proporciónalo a la evaluación del 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 manera única con un nombre de usuario, una dirección de correo electrónico o un número de teléfono estables, puedes usarla como accountId. Cuando proporcionas estos 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. Para ello, marca los identificadores de cuenta abusivos y usa 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 única con cada cuenta, puedes proporcionarlo como el 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 para el sitio. Este identificador aún es necesario para que el defensor de la cuenta de reCAPTCHA comprenda los patrones de actividad del usuario y detecte comportamientos anómalos, pero no se comparte en otros sitios.

    Elige cualquier identificador de cuenta estable y haz que sea opaco antes de enviarlo a reCAPTCHA mediante encriptación o hash:

    • encriptación (recomendada): Encripta el identificador de cuenta con un método de encriptación determinista que produce un texto cifrado estable. Para obtener instrucciones detalladas, consulta encripta los datos de manera determinista. Cuando eliges la criptografía simétrica en lugar de la codificación 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 devuelve reCAPTCHA para convertirlos en el identificador de usuario.

    • Hashing: te 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 hash son unidireccionales únicamente, 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.

Agrega el parámetro accountId y un extremo, como una dirección de correo electrónico, para verificar en la evaluación del método projects.assessments.create.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: tu ID del proyecto de Google Cloud.
  • TOKEN: Es el token que muestra la llamada a 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 único 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 última verificación exitosa 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 un desafío de MFA para ese extremo, debes enviar esta cadena encriptada de vuelta a la página web. Los tokens de solicitud son válidos por 15 minutos.

Si tienes habilitado el defensor de cuentas de reCAPTCHA para tu proyecto, la respuesta de la evaluación contiene información relacionada con el defensor de la cuenta además de la información relacionada con la MFA. El campo recommended_action muestra la acción posible que puedes realizar antes de activar el desafío de la MFA.

En el siguiente ejemplo, se muestra una evaluación de muestra en la que se indica omitir 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 la cuenta no pudo emitir una decisión sobre esta solicitud.
SKIP_2FA Indica que el defensor de la cuenta considera que es seguro omitir la MFA para esta evaluación. Por lo general, esto significa que el usuario fue verificado recientemente para tu sitio en este dispositivo.
REQUEST_2FA Indica que activas un desafío de MFA para el usuario. Para obtener más información, consulta el artículo Respuesta a la evaluación del defensor de cuentas.

Activa 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 de vuelta a la página web el requestToken de MFA para el extremo que deseas verificar desde la evaluación.

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 bien se rechaza si hubo un error o se agotó el tiempo de espera. Cuando finaliza, 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:

  1. Probar la integración de la MFA.

    Activa un desafío de MFA con una llamada a challengeAccount() proporcionando 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 requestToken de la respuesta de evaluación.
    • CONTAINER_HTML_COMPONENT_ID: Es el ID del componente HTML en el que se debe renderizar la comprobación de verificación. Si no especificas este parámetro, el desafío se renderiza 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 variable newToken se pasa a la función en cadena que contiene el token de veredicto que se verificará mediante una evaluación que se crea en el backend.

  2. Crea un controlador de verificación y, luego, inicia un desafío 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
    }
  });

Verifica un código MFA desde la página web

Después de obtener el PIN del usuario final, debes validar si el PIN 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 nueva evaluación con accountId y endpoints. Para obtener instrucciones, consulta Crea una evaluación para la MFA.

Una vez que se completa el flujo de trabajo en el cliente, recibes un token nuevo que puedes usar para obtener el veredicto de la verificación que activaste. La evaluación contiene una marca de tiempo reciente sobre la verificación correcta más reciente, junto con un estado de resultado exitoso.

En el siguiente ejemplo, se muestra una evaluación de muestra que recibes cuando creas una evaluación nueva con el token nuevo obtenido 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 superó el desafío de verificación.
ERROR_SITE_ONBOARDING_INCOMPLETE Tu sitio no se incorporó correctamente para usar esta función.
ERROR_RECIPIENT_NOT_ALLOWED Este destinatario no está aprobado para enviar correos electrónicos a (solo durante las pruebas).
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED Este destinatario ya recibió demasiados códigos de verificación en poco tiempo.
ERROR_CUSTOMER_QUOTA_EXHAUSTED Superaste tu cuota de MFA disponible.
ERROR_CRITICAL_INTERNAL No se completó la verificación debido a un error interno en nuestros sistemas.
RESULT_UNSPECIFIED No hay información sobre la verificación más reciente (nunca verificada).

¿Qué sigue?