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 son 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 apropiación de cuentas (ATO).

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

Comprender el proceso de configuración de la MFA

La función de MFA de reCAPTCHA Enterprise se implementa además del flujo de trabajo normal de reCAPTCHA Enterprise.

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 mediante el token que muestra la llamada execute() y los parámetros de la MFA para obtener un requestToken de la MFA.
  3. Activa un desafío de MFA con el requestToken según el canal que desees usar (solo se admite el correo electrónico).
  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 Enterprise.

  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 incorporarlas
    • 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 o dominios de correo electrónico que necesitas durante la prueba

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

      Ir a reCAPTCHA Enterprise

    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 Configure 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 Enterprise en tu sitio web con claves basadas en puntuaciones.

Instrumenta el flujo de trabajo fundamental en tu sitio web

Pasa la información necesaria a reCAPTCHA Enterprise 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 el 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 puntuaciones que creaste para tu sitio web.

Crea una evaluación

Con el token que genera la función execute(), crea una evaluación mediante las bibliotecas cliente de reCAPTCHA Enterprise 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. Para obtener información sobre cómo crear una evaluación con las bibliotecas cliente, consulta Crea evaluaciones para sitios web.

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

  • Configura la autenticación en reCAPTCHA Enterprise.

    El método de autenticación que elijas dependerá del entorno en el que se haya configurado reCAPTCHA Enterprise. En la siguiente tabla, encontrarás ayuda para elegir el método de autenticación apropiado 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 adjuntas.
    Local o un proveedor de servicios en la nube diferente REST Usa claves de API o la federación de identidades para cargas de trabajo.

    Si deseas usar claves de API, te recomendamos que apliques 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 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.

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: tu ID del proyecto de Google Cloud.
  • TOKEN: Es el token que muestra la llamada grecaptcha.enterprise.execute().
  • KEY_ID: Es la clave basada en puntuaciones 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.

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"
    }
  }
  "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 para los extremos determinados en el dispositivo que emitió el token, si corresponde. También contiene un campo requestToken por extremo, que incluye una string 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 durante 15 minutos.

Si tienes habilitado el defensor de cuentas de reCAPTCHA Enterprise 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 que indica que se puede 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 un juicio 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 se verificó 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, consulte la respuesta de evaluación del defensor de la cuenta.

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

Activa el desafío de la MFA con una llamada a challengeAccount(). La función challengeAccount() muestra una promesa que se resuelve cuando se completa el desafío o se rechaza si se produce un error o se agota el tiempo de espera. Cuando finaliza, se genera un token nuevo que contiene información actualizada y 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

    Para activar un desafío de MFA con una llamada a challengeAccount(), proporciona los siguientes valores:

    • KEY_ID: Es la clave basada en puntuaciones que instalaste en tu sitio web.
    • REQUEST_TOKEN_FROM_ASSESSMENT: Es el valor del campo requestToken de 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 renderiza en una superposición sobre la página.

    En el siguiente ejemplo, se muestra cómo activar el desafío de la 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 mostrará el componente HTML para ingresar el PIN recibido. Después de ingresar el PIN correcto, la variable newToken se pasa a la función encadenada que contiene el token de veredicto que se verificará mediante una evaluación que se crea en el backend.

  2. Crea un identificador 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
    }
  });

Verificar un código 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 MFA.

Después de 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 contiene una marca de tiempo reciente sobre la verificación exitosa más reciente, junto con el estado del resultado de éxito.

En el siguiente ejemplo, se muestra una evaluación de muestra que recibes cuando creas una evaluación nueva con el token nuevo obtenido en el 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 verificación Descripción
SUCCESS_USER_VERIFIED El usuario se verificó correctamente.
ERROR_USER_NOT_VERIFIED El usuario no superó el desafío de verificación.
ERROR_SITE_ONBOARDING_INCOMPLETE Tu sitio no está integrado correctamente para usar la función.
ERROR_RECIPIENT_NOT_ALLOWED Este destinatario no tiene aprobación para enviarle correos electrónicos (solo durante la prueba).
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED Este destinatario ya recibió demasiados códigos de verificación en un corto período.
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?