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

Para configurar a MFA, siga estas etapas:

  1. Instrumente o fluxo de trabalho essencial (login, inscrição etc.) no cliente.
  2. Solicite e interprete as informações de MFA na avaliação.
  3. Acione um teste de MFA no cliente.
  4. Solicite uma nova avaliação para garantir que o endereço de e-mail ou número de telefone do usuário foi verificado.

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. Forneça 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. Siga as instruções específicas para integrar o reCAPTCHA Enterprise nas plataformas que você quiser:

Como instrumentar o fluxo de trabalho essencial 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.

Como solicitar uma avaliação

Com o token gerado pelo execute() faça uma solicitação de avaliação usando as bibliotecas de cliente do reCAPTCHA Enterprise 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 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.

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

Em sites

Acione o teste de 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: 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.
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 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 ...
           }

         }
       });

Depois de receber o PIN do usuário, chame verifyAccount() de uma Activity no 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

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

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