Integra con la función de verificación de correo electrónico

En esta página se explica cómo integrar la función de verificación por correo electrónico.

La verificación por correo electrónico es una función que te permite verificar que tus usuarios tengan la dirección de correo electrónico asociada a su cuenta. Puede ayudar a proteger a tus usuarios contra ataques de robo de credenciales. Esta función te permite enviar un código de verificación por correo electrónico y proporcionar una pantalla de entrada para validar la respuesta del usuario. Puedes recuperar los resultados de la verificación en la evaluación de riesgo.

La integración de la función de verificación por correo electrónico se realiza mediante los siguientes pasos:

  1. Instrumenta el flujo crítico (acceso, registro, etc.) en el cliente, antes de solicitar la evaluación.
  2. Solicita e interpreta la información de verificación por correo electrónico en la evaluación.
  3. Activa un desafío de verificación de correo electrónico en el cliente.
  4. Solicita una evaluación nueva para asegurarte de que se verificó correctamente el correo electrónico del usuario.

Antes de comenzar

Por el momento, la función de verificación de correo electrónico solo está disponible para lista. Comunícate con nuestro equipo de ventas para incorporar tu sitio a esta función.

Asegúrate de completar los pasos de la Guía de inicio rápido para obtener acceso a la API. Según las plataformas para las que deseas habilitar la verificación de correo electrónico, también deberás seguir las guías de integración específicas del cliente:

Instrumenta el flujo crítico en el cliente

En esta sección se explica cómo pasar la información necesaria a reCAPTCHA Enterprise para usar en la evaluación de riesgo.

En Android

Agrega la dirección de correo electrónico del usuario a RecaptchaAction, que se usará en las llamadas de execute. Esto se puede realizar de la siguiente manera:

Bundle bundle = new Bundle();
bundle.putString("username", "foo@bar.com");
RecaptchaAction action =
  new RecaptchaAction(
    new RecaptchaActionType(RecaptchaActionType.LOGIN), bundle));

En iOS

Deberás proporcionar el argumento username. Por ejemplo:

recaptchaClient.execute(
   RecaptchaAction(
      action: .login,
      extraParameters: ["username": "foo@bar.com"])
).then { token in
   // Do something with the token
}.catch { error in
   // Act on the error.
}

En la Web

Deberás adjuntar un parámetro username adicional a tu llamada a execute, como el siguiente ejemplo:

grecaptcha.enterprise.execute({
  action: 'login',
  username: 'foo@bar.com'
}).then(token => {
  /// Handle the generated token.
});

Ten en cuenta que execute muestra una promesa que se resuelve tras la generación de tokens.

Solicita una evaluación

Independientemente de la plataforma que creó el token, puedes seguir las instrucciones para crear una evaluación mediante ese token.

Debes proporcionar el nombre de usuario y la dirección de correo electrónico en Assessment:

{
  "event": {
    "token": "token",
    "siteKey": "key"
  },
  "accountVerification": {
    "username": "foo@bar.com",
    "endpoints: [{
      "emailAddress": "foo@bar.com",
    }]
  }
}

Si la integración con la función es exitosa, la evaluación debe contener más información relacionada con la verificación por correo electrónico específicamente. Por ejemplo:

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

La evaluación contendrá la fecha y hora de la verificación correcta más reciente de la dirección de correo electrónico determinada en el dispositivo que emitió el token, si corresponde. También contendrá un campo requestToken, que contiene un BLOB opaco que deberás enviar al cliente si decides activar un desafío de verificación de correo electrónico.

Activa un desafío de verificación de correo electrónico en el cliente

Si decidiste desafío al usuario según la información contenida en la evaluación, debes enviar el token de solicitud de verificación por correo electrónico de la evaluación al cliente. Este token de solicitud será necesario para activar el desafío de verificación por correo electrónico.

En Android

El desafío por correo electrónico se envía con una llamada a challengeAccount desde una Activity 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 ...
           }

         }
       });

Una vez que obtengas el PIN del usuario, debes llamar a verifyAccount desde una Activity en tu aplicación 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

El desafío se activa 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.
}

Una vez que obtengas el PIN del usuario, puedes usar el verifyPin de verificationHandler para finalizar la verificación.

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

En la Web

El desafío se activa con una sola llamada a función:

grecaptcha.enterprise.challengeAccount({
  'account-token': requestTokenFromCreateAssessment,
  'container': containerHTMLComponentID
}).then(newToken => {
  // Handle the new token.
});

En el ejemplo anterior, containerHTMLComponentID 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 procesará en una superposición en la parte superior de la página.

La función challengeAccount muestra una promesa que se resuelve una vez que se completa el desafío o se rechaza en caso de error o tiempo de espera. Una vez finalizado, el agente de resolución recibe un nuevo token generado que contiene información actualizada que se recuperará mediante la solicitud de una nueva evaluación.

Solicita una nueva evaluación

Debes solicitar una Assessment nueva, una vez más, incluye los campos username y endpoints.

Una vez que se complete el flujo en el cliente, deberías recibir un token nuevo que puedes usar para obtener el veredicto de la verificación que activaste. La evaluación debe contener una marca de tiempo muy reciente respecto de la última verificación exitosa con un estado de resultado correcto:

{
  [...],
  "accountVerification": {
    "username": "foo@bar.com",
    "endpoints: [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "2020-03-23 08:27:12 PST",
    }],
    "latestVerificationResult": "SUCCESS_USER_VERIFIED"
  }
}

El campo latestVerificationResult también puede mostrar un estado diferente, incluido lo siguiente:

  • ERROR_USER_NOT_VERIFIED si el usuario falló en el desafío de verificación
  • ERROR_SITE_ONBOARDING_INCOMPLETE si su sitio no está incorporado adecuadamente a la función
  • ERROR_CRITICAL_INTERNAL si la verificación no se pudo completar debido a un error interno en nuestros sistemas.