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, você pode verificar se os usuários possuem o endereço de e-mail ou número de telefone associado à conta. A MFA pode ajudar a proteger seus usuários contra ataques de preenchimento de credenciais e de contas (ATOs, na sigla em inglês).

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

Entender o processo de configuração do MFA

Para configurar a autenticação multifator (MFA), siga estas etapas:

  1. Instrumente o fluxo de trabalho crítico (login, inscrição etc.) no cliente.
  2. Solicitar e interpretar as informações de MFA na avaliação.
  3. Acione um desafio de MFA no cliente.
  4. Solicite uma nova avaliação para garantir que o e-mail ou o número de telefone do usuário tenha sido verificado.

Antes de começar

  1. Escolha o melhor método para configurar o reCAPTCHA Enterprise em seu ambiente e concluir a configuração.

  2. A MFA pode ser acessada após a análise de segurança. Entre em contato com nossa equipe de vendas para integrar seu site a esse recurso.

  3. Integre o reCAPTCHA Enterprise nas plataformas para as quais você quer ativar o MFA seguindo as instruções específicas da plataforma:

Como instrumentar o fluxo de trabalho crítico no cliente

Transmita as informações necessárias para o reCAPTCHA Enterprise por meio da função execute() da 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 na amostra 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 token para seu aplicativo Android. Nenhum parâmetro adicional é necessário.

No iOS

Siga as instruções para gerar token para seu aplicativo iOS. Nenhum parâmetro adicional é necessário.

Como solicitar uma avaliação

Com o token gerado pela função execute(), faça uma solicitação de avaliação usando as Bibliotecas de cliente empresariais do reCAPTCHA ou a ferramenta de linha de comando gcloud para autenticaçã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 para verificar na avaliação. O identificador de conta com hash é um identificador anônimo permanente para uma conta de usuário exclusiva do seu site. Use um hash unidirecional de um identificador de conta estável. Recomendamos usar sha256-hmac com uma chave secreta 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 verificação mais recente bem-sucedida para os endpoints informados no dispositivo que emitiu o token, se houver. Ele também contém um campo requestToken por endpoint, que contém uma string criptografada. Se você decidir acionar um desafio de MFA para esse endpoint, precisará enviar essa string criptografada de volta ao cliente. Os tokens de solicitação são válidos por 15 minutos.

Como ativar um desafio de MFA no cliente

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

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

Em sites

Acione o desafio MFA com uma chamada para a função challengeAccount(), conforme mostrado no exemplo a seguir.

Forneça os valores a seguir:

  • REQUEST_TOKEN_FROM_ASSESSMENT: valor do campo requestToken da resposta da avaliação.
  • CONTAINER_HTML_COMPONENT_ID: código de um componente HTML em que o desafio de verificação precisa ser renderizado. Se você não especificar esse parâmetro, o desafio será renderizado em uma sobreposição na página.
grecaptcha.enterprise.challengeAccount(SITE_KEY, {
  'account-token': REQUEST_TOKEN_FROM_ASSESSMENT,
  'container': CONTAINER_HTML_COMPONENT_ID
}).then(newToken => {
  // Handle the new token.
});

No Android

Acione o desafio da MFA com uma chamada para challengeAccount() de um Context no seu aplicativo.

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

         }
       });

Depois de receber o PIN do usuário, chame verifyAccount() de Activity no app para verificar se o PIN inserido estava 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

Acione o desafio da 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.
}

Depois de receber o PIN do usuário, 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 que o fluxo de trabalho for concluído no cliente, você receberá um novo token que poderá ser usado para conseguir o veredito da verificação acionada. A avaliação contém um carimbo de data/hora recente sobre a verificação mais recente, além de um status de resultado do sucesso.

O exemplo a seguir mostra um exemplo de avaliação que você recebe ao solicitar uma nova avaliação usando o novo token obtido 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.
ERROR_USER_NOT_VERIFIED O usuário foi reprovado no desafio de verificação.
ERRO_SITE_ONBOARDING_WATCH Seu site não está devidamente integrado para usar o recurso.
ERRO____________ Esse destinatário não é aprovado para enviar SMS ou e-mail para (somente durante testes).
ERROR_RECIPIENT_PANEL_LIMIT_EXHAUSTED Este destinatário já recebeu muitos códigos de verificação em um curto período.
ERRO Você excedeu sua cota MFA disponível.
ERROR_CRITICAL_INTERNAL A verificação não foi concluída devido a um erro interno nos nossos sistemas.
RESULTANTE_ESPECSPECIFIEDFICOS Não há informações sobre a verificação mais recente, nunca verificada.