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

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

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

Para configurar la MFA, sigue estos pasos:

  1. Instrumenta el flujo de trabajo crítico (acceso, registro, etc.) en el cliente.
  2. Solicitar y, luego, interpretar la información del MFA en la evaluación
  3. Activación de un desafío de MFA en el cliente.
  4. Solicita una evaluación nueva para asegurarte de que la dirección de correo electrónico o el número de teléfono del usuario se hayan verificado correctamente.

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 MFA después de una revisión de seguridad. Comunícate con nuestro equipo de ventas para incorporar tu sitio a esta función.

  3. Integra reCAPTCHA Enterprise en las plataformas para las que quieres habilitar MFA mediante las instrucciones específicas de cada plataforma:

La instrumentación del flujo de trabajo crítico en el cliente

Pasa la información necesaria a reCAPTCHA Enterprise a través de la función execute() para la evaluación del riesgo. La función execute() muestra una promesa que se resuelve al generar el token.

En sitios web

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

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 herramienta de línea de comandos de gcloud para la autenticació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 verificar en la evaluación. El identificador de la cuenta con hash es un identificador anónimo y persistente de una cuenta de usuario que es único para tu sitio web. Usa un hash unidireccional para un identificador de cuenta estable. Te recomendamos usar sha256-hmac con un secreto estable que no compartes 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 última verificación exitosa realizada para los extremos determinados en el dispositivo que emitió el token, si corresponde. También contiene un campo requestToken por extremo que 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 solicitud son válidos durante 15 minutos.

Activa un desafío de MFA en el cliente

Si decidiste trasladar al usuario según la información contenida en la evaluación, envía el token de solicitud de MFA para el extremo que quieres 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 que se completa el desafío o se rechaza si hubo un error o tiempo de espera. Al finalizar, se generará un token nuevo que contiene información actualizada, que luego se enviará para la evaluación.

En sitios web

Activa el desafío de MFA con una llamada a la función challengeAccount() como se muestra en el siguiente ejemplo.

Ingresa los siguientes valores:

  • REQUEST_TOKEN_FROM_ASSESSMENT: Valor del campo requestToken de la respuesta de la evaluación.
  • CONTAINER_HTML_COMPONENT_ID: 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 procesa en una superposición sobre la página.
grecaptcha.enterprise.challengeAccount(SITE_KEY, {
  'account-token': REQUEST_TOKEN_FROM_ASSESSMENT,
  'container': CONTAINER_HTML_COMPONENT_ID
}).then(newToken => {
  // Handle the new token.
});

En Android

Activa el desafío de MFA con una llamada a challengeAccount() desde un Context en tu app.

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

         }
       });

Después de obtener el PIN del usuario, llama a verifyAccount() desde un Activity en 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

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

Después de obtener el PIN del usuario, 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.

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 con respecto a la verificación exitosa más reciente, junto con un estado de resultado correcto.

En el siguiente ejemplo, se muestra una evaluación de muestra que puedes recibir cuando solicites una evaluación nueva con el token nuevo que obtuviste 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 pudo realizar 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 está aprobado para enviar SMS o correos electrónicos a (solo durante pruebas).
ERROR_RECIPIENT_ADDR_LIMIT_EXHAUSTED Este destinatario ya recibió demasiados códigos de verificación en un período breve.
ERROR_CUSTOMER_PersistentVolume_EXHAUSTED Superaste la cuota de MFA disponible.
ERROR_CRITICAL_INTERNAL La verificación no se completó debido a un error interno en nuestros sistemas.
RESULT_UNSPECIFIED No hay información sobre la última verificación (nunca verificada).