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 enviándoles 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 a su cuenta. La MFA puede ayudar a proteger a tus usuarios contra los ataques de uso excesivo de credenciales y la apropiación de cuentas (ATO).

La MFA está disponible para las claves basadas en la puntuación, pero 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:

1. Instrumenta el flujo de trabajo crítico en tu sitio web.
2. Crea una evaluación con el token que devuelve la llamada execute() y los parámetros de MFA para obtener un requestToken de MFA.
3. Activa un desafío de MFA con requestToken según el canal que quieras 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 devuelve 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, que se inicia cuando agregas una cuenta de facturación a tu proyecto. Agrega 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 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 settingsConfiguració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 con claves basadas en la puntuación.

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 riesgo. La función execute() devuelve 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 usando 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 las bibliotecas cliente, consulta Crea 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. En la siguiente tabla, se te ayuda 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.
  Local o en un proveedor de servicios en la nube diferente	REST	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.
  	Bibliotecas cliente	Para ello, usa los siguientes recursos: En el caso de 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 lenguajes, usa la federación de identidades para cargas de trabajo.

• 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 esos identificadores entre sitios (identificadores que se pueden reutilizar en diferentes sitios), reCAPTCHA usa esta información para mejorar la protección de tus cuentas de usuario en función de los modelos entre sitios, ya que marca los identificadores de cuentas abusivas 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 a cada cuenta, puedes proporcionarlo como accountId.

  Con hash o encriptado

  Si no tienes un ID de usuario interno asociado de forma única a cada cuenta, puedes convertir cualquier identificador estable en un identificador de cuenta opaco y específico del sitio. Este identificador sigue siendo 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 en otros sitios.

  Elige cualquier identificador de cuenta estable y hazlo opaco antes de enviarlo a reCAPTCHA con encriptación o hash:

  • Encriptación (recomendada): Encripta el identificador de la cuenta con un método de encriptación determinístico que produzca un texto cifrado estable. Para obtener instrucciones detalladas, consulta cómo encriptar datos de forma determinística. Cuando eliges el encriptado simétrico en lugar del hash, no necesitas mantener una asignación entre tus identificadores de usuario y los identificadores de usuario opacos correspondientes. Descifrar los identificadores opacos que devuelve reCAPTCHA para convertirlos en el identificador del usuario

  • Codificación hash: Recomendamos codificar el identificador de la cuenta con el método SHA256-HMAC y una cadena de caracteres personalizada de tu elección. Dado 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 hasheado 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 de 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 -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"

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

Acciones recomendadas

Si tienes habilitada la protección de cuentas de reCAPTCHA para tu proyecto, la respuesta de la evaluación contendrá 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 indica que omitir la MFA es la acción recomendada:

{
  [...],
  "accountDefenderAssessment": {
    labels: ["PROFILE_MATCH"],
    "recommended_action": "SKIP_2FA"
  }
}

El campo recommended_action puede tener cualquiera de los siguientes valores:

Cómo activar un desafío de MFA en tu sitio web

Para desafiar al usuario en función de la información que contiene la evaluación, envía el objeto requestToken de MFA para el extremo que deseas verificar desde la evaluación a la página web.

Activa el desafío MFA con una llamada a challengeAccount(). La función challengeAccount() devuelve 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 nuevo token 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. Prueba la integración del MFA.

   Activa un desafío 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 requestToken de la respuesta de la evaluación.
   • CONTAINER_HTML_COMPONENT_ID: 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 procesará 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 de 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 encadenada que contiene el token de veredicto que se verificará a través de 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
       }
     });
   

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

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 contiene 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 nueva evaluación con el token nuevo que obtuviste 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:

¿Qué sigue?

• Detecta y evita las actividades fraudulentas relacionadas con las cuentas con la protección de cuentas de reCAPTCHA