Configurar a autenticação multifator

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

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

Entender o processo de configuração da MFA

O recurso de MFA do reCAPTCHA é implementado sobre o fluxo normal do reCAPTCHA.

Em um nível alto, o fluxo de trabalho de MFA é o seguinte:

  1. Instrumente o fluxo de trabalho essencial no seu site.
  2. Crie uma avaliação usando o token retornado pela chamada execute() e os parâmetros de MFA para receber um requestToken de MFA.
  3. Acione um teste de MFA com o requestToken de acordo com o canal que você quer usar (somente e-mail).
  4. Verifique o PIN inserido pelo usuário final no seu site.
  5. Crie uma nova avaliação usando o token retornado na solicitação de verificação.

Antes de começar

  1. Prepare seu ambiente para o reCAPTCHA.

  2. A MFA pode ser acessada após uma análise de segurança, que é iniciada quando você adiciona uma conta de faturamento ao projeto. Adicione uma conta de faturamento para integrar seu site a esse recurso.

  3. Para ativar o recurso de verificação de e-mail da MFA, faça o seguinte:

    1. No console do Google Cloud, acesse a página reCAPTCHA.

      Acessar o reCAPTCHA

    2. Verifique se o nome do projeto aparece no seletor de recursos.

      Se você não encontrar o nome do projeto, clique no seletor de recursos e selecione o projeto.

    3. Clique em Configurações.

    4. No painel Autenticação multifator, clique em Configurar.

    5. Na caixa de diálogo Configurar MFA, faça o seguinte:

      1. Para ativar a verificação de e-mail, clique no botão Ativar e-mail.
      2. Na caixa Nome do remetente, insira seu nome.

      3. Na caixa E-mail do remetente, digite seu endereço de e-mail.

    6. Clique em Salvar.

  4. Configure o reCAPTCHA no seu site usando chaves baseadas em pontuação.

Instrumentar o fluxo de trabalho essencial no seu site

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

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

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

Substitua KEY_ID pela chave baseada em pontuação que você criou para seu site.

Criar uma avaliação

Com o token gerado pela função execute(), crie uma avaliação usando as bibliotecas de cliente do reCAPTCHA ou a API REST do back-end.

Este documento mostra como criar uma avaliação para a MFA usando a API REST. Para saber como criar uma avaliação usando as bibliotecas de cliente, consulte Criar avaliações para sites.

Antes de criar uma avaliação, faça o seguinte:

  • Configure a autenticação para o reCAPTCHA.

    O método de autenticação escolhido depende do ambiente em que o reCAPTCHA está configurado. A tabela a seguir ajuda a escolher o método de autenticação adequado e a interface com suporte para configurá-la:

    Ambiente Interface Método de autenticação
    Google Cloud
    • REST
    • Bibliotecas de cliente
    		 Use contas de serviço anexadas.
    No local ou em outro provedor de nuvem REST Use chaves de API ou a federação de identidade da carga de trabalho.

    Se você quiser usar chaves de API, recomendamos proteger as chaves de API aplicando restrições.
    Bibliotecas de cliente

    Use o seguinte:

  • Escolha um identificador de conta estável accountId que não seja alterado com frequência pelo usuário e forneça-o à avaliação no método projects.assessments.create. Esse identificador de conta estável precisa ter o mesmo valor para todos os eventos relacionados ao mesmo usuário. Você pode fornecer o seguinte como identificador da conta:

    Identificadores de usuários

    Se cada conta puder ser associada exclusivamente a um nome de usuário, endereço de e-mail ou número de telefone estável, você poderá usá-lo como o accountId. Quando você fornece esses identificadores entre sites (identificadores que podem ser reutilizados em vários sites), o reCAPTCHA usa essas informações para melhorar a proteção das suas contas de usuário com base em modelos entre sites, sinalizando identificadores de contas abusivas e usando o conhecimento de padrões de abuso entre sites relacionados a esses identificadores.

    Como alternativa, se você tiver um ID de usuário interno associado exclusivamente a cada conta, poderá fornecê-lo como accountId.

    Criptografado ou com hash

    Se você não tiver um ID de usuário interno associado exclusivamente a cada conta, poderá transformar qualquer identificador estável em um identificador de conta opaco e específico do site. Esse identificador ainda é necessário para que o Account Defender do reCAPTCHA entenda os padrões de atividade do usuário e detecte comportamentos anormais, mas ele não é compartilhado em outros sites.

    Escolha qualquer identificador de conta estável e torne-o opaco antes de enviar para o reCAPTCHA usando criptografia ou hash:

    • criptografia (recomendada): criptografe o identificador da conta usando um método de criptografia determinístico que produz um texto criptografado estável. Para instruções detalhadas, consulte Como criptografar dados de forma determinística. Quando você escolhe a criptografia simétrica em vez do hash, não é necessário manter um mapeamento entre os identificadores de usuário e os identificadores opacos correspondentes. Descriptografar os identificadores opacos retornados pelo reCAPTCHA para transformá-los no identificador do usuário.

    • Geração de hash: recomendamos gerar hash do identificador da conta usando o método SHA256-HMAC com uma opção de sal personalizada. Como os hashes são unidirecionais, é necessário manter um mapeamento entre os hashes gerados e os identificadores de usuário para que você possa mapear o identificador da conta hash retornado para as contas originais.

Adicione o parâmetro accountId e um endpoint, como um endereço de e-mail para verificar na avaliação no método projects.assessments.create.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: é seu ID do projeto no Google Cloud.
  • TOKEN: token retornado da chamada grecaptcha.enterprise.execute().
  • KEY_ID: a chave baseada na pontuação que você instalou no seu site.
  • ACCOUNT_ID: um identificador exclusivo da conta de usuário do seu site.
  • EMAIL_ID: o endereço de e-mail para o qual a solicitação de verificação precisa ser acionada.

Método HTTP e URL: 

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

Corpo JSON da solicitação:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userInfo": {
       "accountId": "ACCOUNT_ID"
    }
  }
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "EMAIL_ID",
    }]
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:


{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "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 à página da Web. Os tokens de solicitação são válidos por 15 minutos.

Se você tiver o defensor da conta do reCAPTCHA ativado para seu projeto, a resposta da avaliação vai conter informações relacionadas ao defensor da conta, além das informações relacionadas à MFA. O campo recommended_action mostra a possível ação que você pode realizar antes de acionar o desafio de MFA.

O exemplo a seguir mostra uma avaliação que mostra a omissão da MFA como a ação recomendada:

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

O campo recommended_action pode ter um dos seguintes valores:

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

Acionar um teste de MFA no seu site

Para desafiar o usuário com base nas informações contidas na avaliação, envie o MFA requestToken para o endpoint que você quer verificar na avaliação de volta à página da Web.

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.

Para acionar um desafio de MFA, faça o seguinte:

  1. Teste a integração do MFA.

    Acione um desafio de MFA com uma chamada para o challengeAccount() fornecendo os seguintes valores:

    • KEY_ID: a chave baseada na pontuação que você instalou no seu site.
    • REQUEST_TOKEN_FROM_ASSESSMENT: valor do campo requestToken da resposta da avaliação.
    • CONTAINER_HTML_COMPONENT_ID: ID do componente HTML em que o desafio 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 de MFA com uma chamada para challengeAccount():

    grecaptcha.enterprise.challengeAccount(KEY_ID, {
  '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, o componente HTML será exibido para inserir o PIN recebido. Depois que o PIN correto é inserido, a variável newToken é transmitida para a função encadeada que contém o token de veredito a ser verificado por uma avaliação criada no back-end.

  2. Crie um identificador de verificação e inicie uma contestação com os seguintes parâmetros:

    // Initialize verification handle.
const verificationHandle = grecaptcha.enterprise.eap.initTwoFactorVerificationHandle(
  KEY_ID,
  REQUEST_TOKEN_FROM_ASSESSMENT
);

// Call the challenge API.
verificationHandle.challengeAccount().then(
  (challengeResponse) => {
    if (challengeResponse.isSuccess()) {
      // Handle success: This means displaying an input for the end user to
      // enter the PIN that they received and then call the `verifyAccount(pin)`
      // method.
    } else {
      // Handle API failure
    }
  });

Verificar um código de MFA na página da Web

Depois de receber o PIN do usuário final, você precisa validar se ele está correto ou não.

Para validar o PIN, chame verificationHandle.verifyAccount() com o PIN digitado pelo usuário final.

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

Criar uma nova avaliação

Crie uma nova avaliação com accountId e endpoints. Para instruções, consulte Criar uma avaliação para a MFA.

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 criar uma nova avaliação usando o novo token recebido do site:

{
  [...],
  "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 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).

A seguir