Como configurar a autenticação multifator

Nesta página, descrevemos como configurar a autenticação multifator (MFA, na sigla em inglês) que permite verificar a identidade dos usuários enviando um código de verificação por e-mail ou SMS. Com esse recurso, é possível verificar se os usuários são proprietários do endereço de e-mail ou do número de telefone associado à conta. A MFA pode ajudar a proteger os usuários contra ataques de preenchimento de credenciais e invasão de conta (ATOs, na sigla em inglês).

A MFA está disponível para as chaves de site baseadas em pontuação, mas não para as chaves de site com caixa de seleção.

Noções básicas sobre o processo de configuração da MFA

A MFA do reCAPTCHA Enterprise funciona com base no fluxo de trabalho normal do reCAPTCHA Enterprise (em inglês). De modo geral, o fluxo de trabalho da MFA é o seguinte:

  1. Instrumentar o fluxo de trabalho crítico no cliente.
  2. Crie uma avaliação usando o token retornado pela chamada execute() do cliente. Ao criar a avaliação, inclua os parâmetros de MFA para receber uma requestToken de MFA.
  3. Acione um desafio de MFA com a requestToken de acordo com o canal que você quer usar (SMS ou e-mail).
  4. Verifique o PIN inserido pelo usuário final no seu app da Web ou para dispositivos móveis.
  5. Solicite uma nova avaliação usando o token retornado na solicitação de verificação.

Antes de começar

  1. Escolha o melhor método para configurar o reCAPTCHA Enterprise no ambiente e conclua a configuração.

  2. A MFA pode ser acessada após uma análise de segurança. Entre em contato com nossa equipe de vendas para integrar seu site a esse recurso. Envie as seguintes informações de integração à equipe de vendas:

    • Número do projeto do Google Cloud
    • Chaves do site para integração
    • Média de QPS (e-mails/SMS por segundo)
    • Pico de QPS (e-mails/SMS por segundo)
    • Para MFA de e-mail, o endereço do remetente e os endereços ou domínios de e-mail necessários para o teste
    • Para MFA de SMS, o pico e a média de QPS por país de destino (o país do usuário)
  3. Integre o reCAPTCHA Enterprise nas plataformas em que você quer ativar a MFA seguindo as instruções específicas da plataforma:

Instrumentar o fluxo de trabalho crítico no cliente

Transmita as informações necessárias para o reCAPTCHA Enterprise pela função execute() para a avaliação de risco. A função execute() retorna uma promessa que é resolvida na geração do token.

Em sites

Anexe um parâmetro twofactor extra à função execute(), conforme mostrado no exemplo de código a seguir:

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

No Android

Siga as instruções para gerar tokens para seu aplicativo Android. Não são necessários mais parâmetros.

No iOS

Siga as instruções para gerar tokens para seu aplicativo iOS. Não são necessários mais parâmetros.

Solicite uma avaliação

Com o token gerado pela função execute(), faça uma solicitação de avaliação usando as bibliotecas de cliente do reCAPTCHA Enterprise ou a CLI do Google Cloud para autenticação no back-end. Para saber como solicitar uma avaliação, consulte Criar uma avaliação.

Forneça um identificador de conta com hash e um ou mais endpoints, como um endereço de e-mail e um número de telefone a ser verificado na avaliação. O identificador de conta com hash é um identificador anônimo e persistente para uma conta de usuário exclusiva do seu site. Use um hash unidirecional de um identificador de conta estável. Recomendamos usar o sha256-hmac com um secret estável que você não compartilha conosco.

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

Se a integração com o recurso for bem-sucedida, a avaliação precisará conter mais informações relacionadas à MFA, como mostrado no exemplo a seguir:

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

A avaliação contém a data e a hora da última verificação bem-sucedida dos endpoints fornecidos no dispositivo que emitiu o token, se houver. Ela também contém um campo requestToken por endpoint, que inclui uma string criptografada. Se você decidir acionar um teste de MFA para esse endpoint, será necessário enviar essa string criptografada de volta ao cliente. Os tokens de solicitação são válidos por 15 minutos.

Além das informações relacionadas à MFA, a resposta da avaliação contém informações relacionadas ao defensor da conta. O campo recommended_action mostra a possível ação que você pode realizar antes de acionar o desafio MFA.

O exemplo a seguir mostra um exemplo de avaliação que mostra que a ação de ignorar MFA é a ação recomendada:

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

O campo recommended actions pode ter qualquer um dos seguintes valores:

Valor Descrição
RECOMMENDED_ACTION_UNSPECIFIED Indica que o defensor da conta não conseguiu fazer um julgamento sobre essa solicitação.
SKIP_2FA Indica que o defensor da conta considera que é seguro pular a autenticação multifator (MFA) para esta avaliação. Isso geralmente significa que o usuário foi verificado recentemente para seu site neste dispositivo.
REQUEST_2FA Indica que você acionou um desafio MFA para o usuário. Para mais informações, consulte a resposta de avaliação do defensor da conta.

Como acionar um teste de MFA no cliente

Se você decidiu desafiar o usuário com base nas informações contidas na avaliação, precisa enviar o token de solicitação de MFA referente ao endpoint que quer verificar a partir do cliente. O token de solicitação é necessário para acionar o teste de MFA.

Acione o teste de MFA com uma chamada para challengeAccount(). A função challengeAccount() retorna uma promessa que é resolvida após a conclusão do teste ou rejeitada se houve um erro ou tempo limite. Após a conclusão, um novo token com informações atualizadas é gerado e enviado para avaliação.

Como testar a integração de MFA

Para testar rapidamente a integração da MFA, você pode acionar o desafio da MFA com uma chamada para o challengeAccount(), fornecendo os seguintes valores:

  • REQUEST_TOKEN_FROM_ASSESSMENT: valor do campo requestToken da resposta da avaliação.
  • CONTAINER_HTML_COMPONENT_ID: ID de um componente HTML em que o teste de verificação precisa ser renderizado. Se você não especificar este parâmetro, o teste é renderizado em uma sobreposição na parte superior da página.

O exemplo a seguir mostra como acionar o desafio MFA com uma chamada para `challengeAccount():

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

Se a solicitação challengeAccount() for bem-sucedida, um componente HTML será exibido para inserir o PIN recebido. Depois que o alfinete correto é inserido, a variável newToken é transmitida para a função encadeada que contém o token de veredito a ser verificado por meio de uma avaliação criada no back-end.

Em sites

Crie um identificador de verificação e inicie um desafio com os seguintes 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
    }
  });

No Android

Acione o teste de MFA com uma chamada para challengeAccount() de um Context no seu 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 ...
           }

         }
       });

No iOS

Acione o teste de MFA com uma chamada para challengeAccount().

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

Verificar um código MFA do cliente

Depois de receber o PIN do usuário final, verifique se o PIN está correto ou não:

Em sites

Chame verificationHandle.verifyAccount() com o PIN inserido pelo usuário final para verificar se ele está correto.

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

No Android

Chame verifyAccount() de um Activity no seu app para verificar se o PIN inserido está correto.

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

No iOS

Chame o método verifyPin() do objeto verificationHandler para concluir a verificação.

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

Como solicitar uma nova avaliação

Solicite uma nova avaliação com o identificador de conta com hash e o campo endpoints.

Depois de concluir o fluxo de trabalho no cliente, você receberá um novo token que poderá ser usado para encontrar o resultado da verificação acionada. A avaliação contém um carimbo de data/hora referente à verificação bem-sucedida mais recente, além de um status de resultado bem-sucedido.

O exemplo a seguir mostra uma avaliação de amostra que você recebe ao solicitar uma nova avaliação usando o novo token recebido do cliente.

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

O campo latestVerificationResult pode mostrar um status diferente, conforme listado na tabela a seguir:

Status do resultado da verificação Descrição
SUCCESS_USER_VERIFIED O usuário foi verificado com sucesso.
ERROR_USER_NOT_VERIFIED O usuário falhou no teste de verificação.
ERROR_SITE_ONBOARDING_INCOMPLETE A integração do site com o recurso está incorreta.
ERROR_RECIPIENT_NOT_ALLOWED Esse destinatário não está aprovado para enviar SMS ou e-mail (apenas durante o teste).
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED Esse destinatário já recebeu muitos códigos de verificação em um período curto.
ERROR_CUSTOMER_QUOTA_EXHAUSTED Você excedeu a cota disponível de MFA.
ERROR_CRITICAL_INTERNAL A verificação não foi concluída devido a um erro interno em nossos sistemas.
RESULT_UNSPECIFIED Nenhuma informação sobre a verificação mais recente (nunca verificada).