Configurar la autenticación multifactor

En esta página se describe cómo configurar la autenticación multifactor (MFA) para verificar la identidad de los usuarios enviándoles un código de verificación por correo electrónico. Con esta función, puedes verificar que tus usuarios son los propietarios de la dirección de correo asociada a su cuenta. La MFA puede ayudar a proteger a tus usuarios frente a los ataques de relleno de credenciales y la apropiación de cuentas (ATO).

La MFA está disponible para las claves basadas en puntuación, pero no para las claves de casilla.

Información sobre el proceso de configuración de la MFA

La función de MFA de reCAPTCHA se implementa sobre el flujo de trabajo habitual de reCAPTCHA.

A grandes rasgos, el flujo de trabajo de la MFA es el siguiente:

  1. Implemente el flujo de trabajo crítico en su sitio web.
  2. Crea una evaluación usando el token que devuelve la llamada execute() y los parámetros de MFA para obtener un requestToken de MFA.
  3. Activa una verificación en dos pasos con requestToken según el canal que quieras usar (solo se admite el correo electrónico).
  4. Verifica el PIN que ha introducido el usuario final en tu sitio web.
  5. Crea una nueva evaluación usando el token que se devuelve en la solicitud de verificación.

Antes de empezar

  1. Prepara tu entorno para reCAPTCHA.

  2. Se puede acceder a la MFA tras una revisión de seguridad, que se inicia cuando añades una cuenta de facturación a tu proyecto. Añade una cuenta de facturación para incorporar tu sitio a esta función.

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

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

      Ir a reCAPTCHA

    2. Comprueba que el nombre de tu proyecto aparece en el selector de recursos.

      Si no ves el nombre de tu proyecto, haz clic en el selector de recursos y, a continuación, selecciona tu proyecto.

    3. Haz clic en Configuración.

    4. En el panel Autenticación multifactor, 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 interruptor Habilitar correo.
      2. En el cuadro Nombre del remitente, escribe tu nombre.

      3. En el cuadro Correo del remitente, introduce tu dirección de correo.

    6. Haz clic en Guardar.

  4. Configura reCAPTCHA en tu sitio web con claves basadas en puntuaciones.

Implementar el flujo de trabajo crítico en tu sitio web

Transfiere la información necesaria a reCAPTCHA a través de la función execute() para la evaluación de riesgos. La función execute() devuelve una promesa que se resuelve cuando se genera el token.

Añade un parámetro twofactor adicional a tu función execute(), como se muestra en el siguiente código de ejemplo:

  grecaptcha.enterprise.execute(KEY_ID, {
    action: 'login',
    twofactor: true
  }).then(token => {
    // Handle the generated token.
  });

Sustituye KEY_ID por la clave basada en la puntuación que has creado para tu sitio web.

Crear una evaluación

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

En este documento se muestra cómo crear una evaluación para la MFA mediante la API REST. Para saber cómo crear una evaluación con bibliotecas de cliente, consulta el artículo 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 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 de cliente
    		 Usa cuentas de servicio asociadas.
    On-premise u otro proveedor de servicios en la nube REST Usa claves de API o la federación de identidades de cargas de trabajo.

    Si quieres usar claves de API, te recomendamos que las protejas aplicando restricciones a las claves de API.
    Bibliotecas de cliente

    Utiliza lo siguiente:

  • 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 cuenta:

    Identificadores de usuario

    Si cada cuenta se puede asociar de forma única a un nombre de usuario, una dirección de correo o un número de teléfono estables, puedes usarlo como accountId. Cuando proporciones identificadores entre sitios (identificadores que se pueden reutilizar en varios sitios), reCAPTCHA usará esta información para mejorar la protección de tus cuentas de usuario en función de modelos entre sitios. Para ello, marcará los identificadores de cuentas abusivas y usará el conocimiento de los patrones de abuso entre sitios relacionados con estos identificadores.

    Si tiene un ID de usuario interno asociado de forma exclusiva a cada cuenta, puede proporcionarlo como accountId.

    Cifrado con hash o encriptado

    Si no tiene un ID de usuario interno asociado de forma exclusiva a cada cuenta, puede convertir cualquier identificador estable en un identificador de cuenta opaco y específico del sitio. Este identificador sigue siendo necesario para que reCAPTCHA Account Defender comprenda los patrones de actividad de los usuarios 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 mediante cifrado o cifrado con hash:

    • Cifrado (opción recomendada): cifra el identificador de la cuenta mediante un método de cifrado determinista que genere un texto cifrado estable. Para obtener instrucciones detalladas, consulta el artículo sobre cifrar datos de forma determinista. Si eliges el cifrado simétrico en lugar del cifrado con hash, no tienes que mantener una asignación entre tus identificadores de usuario y los identificadores de usuario opacos correspondientes. Descifra los identificadores opacos que devuelve reCAPTCHA para convertirlos en el identificador de usuario.

    • Cifrado con hash: recomendamos cifrar con hash el identificador de cuenta mediante el método SHA256-HMAC con una sal personalizada de tu elección. Como 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 cifrado que se devuelve a las cuentas originales.

Añade el parámetro accountId y un endpoint, como una dirección de correo electrónico, para verificarlo en la evaluación con el método projects.assessments.create.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto Google Cloud .
  • TOKEN: token devuelto por la llamada grecaptcha.enterprise.execute().
  • KEY_ID: la clave basada en una puntuación que ha instalado en su sitio web.
  • ACCOUNT_ID: identificador de una cuenta de usuario que es único en su sitio web.
  • EMAIL_ID: 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 siguiente:


{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "",
    }],
    "latestVerificationResult": "RESULT_UNSPECIFIED"
  }
}

La evaluación contiene la fecha y la hora de la última verificación correcta de los endpoints del dispositivo que emitió el token, si los hay. También contiene un campo requestToken por cada endpoint, que contiene una cadena cifrada. Si decides activar una verificación en dos pasos para ese endpoint, debes enviar esta cadena cifrada de vuelta a la página web. Los tokens de solicitud son válidos durante 15 minutos.

Si tienes habilitado reCAPTCHA Account Defender en tu proyecto, la respuesta de la evaluación contendrá información relacionada con Account Defender, además de la información relacionada con la MFA. El campo recommended_action muestra la acción que puedes llevar a cabo antes de activar la verificación en dos pasos.

En el siguiente ejemplo se muestra una evaluación de muestra en la que se recomienda omitir la MFA:

{
  [...],
  "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 Account Defender no ha podido tomar una decisión sobre esta solicitud.
SKIP_2FA Indica que Account Defender considera que es seguro omitir la MFA en esta evaluación. Esto suele significar que el usuario se ha verificado recientemente en tu sitio en este dispositivo.
REQUEST_2FA Indica que activas una verificación de la identidad de dos factores para el usuario. Para obtener más información, consulta Respuesta de la evaluación de Account Defender.

Activar una petición de autenticación multifactor en tu sitio web

Para desafiar al usuario en función de la información contenida en la evaluación, envíe el MFA requestToken del endpoint que quiera verificar de la evaluación a la página web.

Activa la autenticación multifactor con una llamada a challengeAccount(). La función challengeAccount() devuelve una promesa que se resuelve una vez completado el reto o se rechaza si se produce un error o se agota el tiempo de espera. Una vez completado el proceso, se genera un nuevo token que contiene la información actualizada, que se envía para su evaluación.

Para activar una verificación en dos pasos, haz lo siguiente:

  1. Prueba la integración de la MFA.

    Activa una verificación en dos pasos con una llamada a challengeAccount() proporcionando los siguientes valores:

    • KEY_ID: la clave basada en una puntuación que ha instalado en su sitio web.
    • REQUEST_TOKEN_FROM_ASSESSMENT: valor del campo requestToken de la respuesta de la evaluación.
    • CONTAINER_HTML_COMPONENT_ID: ID del componente HTML en el que se debe renderizar el reto de verificación. Si no especifica este parámetro, el reto se renderizará en una superposición en la parte superior de la página.

    En el siguiente ejemplo se muestra cómo activar la verificación en dos pasos 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 introducir el PIN recibido. Una vez que se introduce el PIN correcto, la variable newToken se transfiere a la función encadenada que contiene el token de veredicto que se va a verificar mediante una evaluación que se crea en el backend.

  2. Crea un identificador de verificación e inicia un reto 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 de MFA desde la página web

Una vez que hayas obtenido el PIN del usuario final, debes validar si es correcto o no.

Para validar el PIN, llama a verificationHandle.verifyAccount() con el PIN introducido por 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 evaluación

Crea una evaluación con accountId y endpoints. Para obtener instrucciones, consulta cómo crear una evaluación para la MFA.

Una vez que se haya completado el flujo de trabajo en el cliente, recibirás un nuevo token que podrás usar para obtener el veredicto de la verificación que hayas activado. La evaluación contiene una marca de tiempo reciente sobre la última verificación correcta, junto con un estado de resultado correcto.

En el siguiente ejemplo se muestra una evaluación de muestra que recibe al crear una nueva evaluación con el nuevo token 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 El usuario se ha verificado correctamente.
ERROR_USER_NOT_VERIFIED El usuario no ha superado el reto de verificación.
ERROR_SITE_ONBOARDING_INCOMPLETE Su sitio no se ha configurado correctamente para usar la función.
ERROR_RECIPIENT_NOT_ALLOWED Este destinatario no está aprobado para enviar correos (solo durante las pruebas).
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED Este destinatario ya ha recibido demasiados códigos de verificación en un breve periodo.
ERROR_CUSTOMER_QUOTA_EXHAUSTED Has superado la cuota de MFA disponible.
ERROR_CRITICAL_INTERNAL No se ha completado la verificación debido a un error interno en nuestros sistemas.
RESULT_UNSPECIFIED No hay información sobre la última verificación (nunca se ha verificado).

Siguientes pasos