Configurar 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 tu identidad mediante el envío de un código de verificación por correo electrónico o SMS. Con esta función, puedes verificar que los usuarios tengan la dirección de correo electrónico o el número de teléfono asociado a su cuenta. La MFA puede ayudar a proteger a tus usuarios de los ataques de uso excesivo de credenciales y la apropiación de cuentas (ATO).

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

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

La MFA de reCAPTCHA Enterprise funciona como parte del flujo de trabajo de reCAPTCHA Enterprise. A grandes rasgos, el flujo de trabajo de la MFA es el siguiente:

  1. Instrumenta el flujo de trabajo crítico en el cliente.
  2. Crea una evaluación con el token que muestra la llamada execute() del cliente. Cuando crees la evaluación, incluye los parámetros de MFA para obtener una requestToken de MFA.
  3. Activa un desafío de MFA con la requestToken según el canal que quieras usar (SMS o correo electrónico).
  4. Verifica el PIN que ingresó el usuario final en tu app web o para dispositivos móviles.
  5. Solicita una evaluación nueva con el token que se muestra en la solicitud de verificación.

Antes de comenzar

  1. Elige el mejor método para configurar reCAPTCHA Enterprise en tu entorno y completa la configuración.

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

    • Número del proyecto de Google Cloud
    • Claves del sitio para incorporarse
    • Promedio de QPS (correos electrónicos/SMS por segundo)
    • QPS máximas (correos electrónicos/SMS por segundo)
    • En MFA de correo electrónico, la dirección del remitente y las direcciones de correo electrónico o los dominios que necesitas durante las pruebas
    • Para la MFA de SMS, el máximo y el promedio de QPS por país de destino (el país de tu usuario)
  3. Para integrar reCAPTCHA Enterprise a las plataformas en las que deseas habilitar la MFA, sigue las instrucciones específicas de cada plataforma:

Instrumenta el flujo de trabajo crítico en el cliente

Pasa la información necesaria a reCAPTCHA Enterprise mediante 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.

En sitios web

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

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

En Android

Sigue las instrucciones a fin de generar un token para tu aplicación para Android. No se requiere ningún parámetro adicional.

En iOS

Sigue las instrucciones a fin de generar un token para tu aplicación para iOS. No se requiere ningún parámetro adicional.

Solicita una evaluación

Con el token que genera la función execute(), realiza una solicitud de evaluación mediante las bibliotecas cliente de reCAPTCHA Enterprise o la CLI de Google Cloud para la autenticación desde tu backend. Para obtener información sobre cómo solicitar una evaluación, consulte Cómo crear una evaluación.

Proporciona un identificador de cuenta con hash y uno o más extremos, como una dirección de correo electrónico y un número de teléfono, para verificarlos en la evaluación. El identificador de cuenta con hash es un identificador anónimo y persistente para una cuenta de usuario que es exclusivo de tu sitio web. Usa un hash unidireccional de un identificador de cuenta estable. Te recomendamos que uses sha256-hmac con un secreto estable que no compartas con nosotros.

{
  "event": {
    "token": "token",
    "siteKey": "key",
    "hashedAccountId": "BP3ptt00D9W7UMzFmsPdEjNH3Chpi8bo40R6YW2b"
  },
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
    },
    {
      "phoneNumber": "+11111111111",
    }]
  }
}

Si la integración con la función es correcta, la evaluación debe contener más información relacionada con la MFA, como se muestra en el siguiente ejemplo:

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

La evaluación contiene la fecha y hora de la verificación correcta más reciente para los extremos determinados en el dispositivo que emitió el token, si corresponde. También contiene un campo requestToken por extremo, el cual contiene una string encriptada. Si decides activar un desafío de MFA para ese extremo, debes enviar esta string encriptada al cliente. Los tokens de solicitudes son válidos durante 15 minutos.

Además de la información relacionada con la MFA, la respuesta de la evaluación contiene información relacionada con el defensor de la cuenta. El campo recommended_action muestra la 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 omite la MFA como la acción recomendada:

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

El campo recommended actions puede tener cualquiera de los siguientes valores:

Valor Descripción
RECOMMENDED_ACTION_UNSPECIFIED Indica que el defensor de la cuenta no pudo juzgar 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, eso significa que el usuario se verificó recientemente para tu sitio en este dispositivo.
REQUEST_2FA Indica que activaste 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.

Activa un desafío de MFA en el cliente

Si decides desafiar al usuario en función de la información contenida en la evaluación, envía el token de solicitud de MFA del extremo que deseas verificar de la evaluación al cliente. Este token de solicitud es necesario para activar el desafío de MFA.

Activa el desafío de MFA con una llamada a challengeAccount(). La función challengeAccount() muestra una promesa que se resuelve después de completar el desafío o se rechaza si se produjo un error o tiempo de espera. Cuando se completa, se genera un token nuevo que contiene información actualizada, que luego se envía para su evaluación.

Prueba la integración de MFA

Para probar rápidamente la integración de MFA, puedes activar el desafío de MFA con una llamada a challengeAccount() si proporcionas los siguientes valores:

  • REQUEST_TOKEN_FROM_ASSESSMENT: El valor del campo requestToken correspondiente a la respuesta de la evaluación.
  • CONTAINER_HTML_COMPONENT_ID: Es el ID de un componente HTML en el que se debe procesar 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 MFA con una llamada a `challengeAccount():

grecaptcha.enterprise.challengeAccount(SITE_KEY, {
  '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á un componente HTML para ingresar el PIN que se recibió. Después de ingresar el PIN correcto, la variable newToken se pasa a la función encadenada que contiene el token de veredicto para verificarla mediante una evaluación que se crea en el backend.

En sitios web

Crea un controlador de verificación e inicia un desafío con los siguientes parámetros:

// Initialize verification handle.
const verificationHandle = grecaptcha.enterprise.eap.initTwoFactorVerificationHandle(
  SITE_KEY,
  REQUEST_TOKEN_FROM_ASSESSMENT
);

// Call the challenge API.
verificationHandle.challengeAccount().then(
  (challengeResponse) => {
    if (challengeResponse.isSuccess()) {
      // Handle success: Usually this means displaying an input for the user to
      // enter the pin that they received and then call the `verifyAccount(pin)`
      // method described below.
    } else {
      // Handle API failure
    }
  });

En Android

Activa el desafío MFA con una llamada a challengeAccount() desde un Context en tu aplicación.

Recaptcha.getClient(this)
   .challengeAccount(recaptchaHandle, requestToken)
   .addOnSuccessListener(
       this,
       new OnSuccessListener<VerificationHandle>() {
         @Override
         public void onSuccess(VerificationHandle handle) {
           VerificationHandle verificationHandle = handle;
           // Handle success ...
         }
       })
   .addOnFailureListener(
       this,
       new OnFailureListener() {
         @Override
         public void onFailure(@NonNull Exception e) {
           if (e instanceof ApiException) {
              ApiException apiException = (ApiException) e;
              Status apiErrorStatus = apiException.getStatusCode();
              // Handle API errors ...
           } else {
              // Handle other failures ...
           }

         }
       });

En iOS

Activa el desafío de MFA con una llamada a challengeAccount().

recaptchaClient.challengeAccount(withRequestToken: "Request Token").then { verificationHandler in
  // Show your UI and retrieve the pin from the user.
}.catch { error in
  // Handle error.
}

Verifica el código de MFA del cliente

Después de obtener el PIN del usuario final, debes validar si el PIN es correcto o no:

En sitios web

Llama a verificationHandle.verifyAccount() con el PIN que ingresó el usuario final para verificar que haya sido correcto.

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
  }
);

En Android

Llama a verifyAccount() desde un Activity de tu app para verificar que el PIN ingresado sea correcto.

Recaptcha.getClient(this)
   .verifyAccount("userProvidedPIN", recaptchaHandle)
   .addOnSuccessListener(
       this,
       new OnSuccessListener<VerificationResult>() {
         @Override
         public void onSuccess(VerificationResult result) {
           if (result.getVerificationStatus().isSuccess()) {
             String recaptchaToken = result.recaptchaToken().orNull()
             // Handle success ...
           } else {
             VerificationHandle verificationHandle =
                              result.verificationHandle().orNull();
             Status errorStatus = result.getVerificationStatus();
             // Handle retries ...
           }
         }
       })
   .addOnFailureListener(
       this,
       new OnFailureListener() {
         @Override
         public void onFailure(@NonNull Exception e) {
           if (e instanceof ApiException) {
              ApiException apiException = (ApiException) e;
              Status apiErrorStatus = apiException.getStatusCode();
              // Handle API errors ...
           } else {
              // Handle other failures ...
           }
         }
       });

En iOS

Llama al método verifyPin() del objeto verificationHandler para completar la verificación.

handler.verifyPin("PIN") { recaptchaToken, recaptchaError in
  // Handle token/error.
}

Solicita una nueva evaluación

Solicita una evaluación nueva con el identificador de cuenta con hash y el campo endpoints.

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 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 solicitas una evaluación nueva con el token nuevo obtenido del cliente.

{
  [...],
  "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 aprobó 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 enviarle SMS o 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 corto.
ERROR_CUSTOMER_QUOTA_EXHAUSTED Superaste tu cuota de MFA disponible.
ERROR_CRITICAL_INTERNAL No se completa 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 se verificó).