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. 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ão de conta (ATOs, na sigla em inglês).

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

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

O recurso de MFA do reCAPTCHA é implementado com base no fluxo de trabalho regular do reCAPTCHA.

Em um nível mais alto, o fluxo de trabalho da 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 (apenas e-mail).
4. Verifique o PIN inserido pelo usuário final no seu site.
5. Crie uma 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 seu 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 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 vir o nome do projeto, clique no seletor de recursos para selecioná-lo.

   3. Clique em settingsConfiguraçõ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.

Instrumente 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 seu back-end.

Este documento mostra como criar uma avaliação para 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 no reCAPTCHA.

  O método de autenticação escolhido depende do ambiente em que o reCAPTCHA está configurado. A tabela a seguir ajuda você a escolher o método de autenticação adequado e a interface compatível para configurar a autenticação:

  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 protegê-las aplicando restrições.
  	Bibliotecas de cliente	Use o seguinte: Para Python ou Java, use chaves de API ou a federação de identidade da carga de trabalho. Se você quiser usar chaves de API, recomendamos protegê-las aplicando restrições. Para outros idiomas, use a federação de identidade da carga de trabalho.

• 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 de forma exclusiva a um nome de usuário, endereço de e-mail ou número de telefone estável, use essas informações como accountId. Quando você fornece esses identificadores entre sites (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. Para isso, ele sinaliza identificadores de contas abusivas e usa 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, forneça-o como accountId.

  Criptografadas ou transformadas em hash

  Se você não tiver um ID de usuário interno associado de forma exclusiva 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 reCAPTCHA Account Defender entenda os padrões de atividade do usuário e detecte comportamentos anômalos, mas não é compartilhado em outros sites.

  Escolha um identificador de conta estável e o torne opaco antes de enviar ao reCAPTCHA usando criptografia ou hash:

  • criptografia (recomendado): criptografe o identificador da conta usando um método de criptografia determinista que produza um texto cifrado estável. Para instruções detalhadas, consulte criptografar dados de forma determinística. Ao escolher a criptografia simétrica em vez do hash, não é necessário manter um mapeamento entre seus identificadores de usuário e os identificadores opacos correspondentes. Descriptografe 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 um salt personalizado de sua escolha. Como os hashes são unidirecionais, é necessário manter um mapeamento entre os hashes gerados e os identificadores de usuário para que seja possível mapear o identificador de conta com hash que é 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: o ID do projeto do Google Cloud .
• TOKEN: token retornado da chamada grecaptcha.enterprise.execute().
• KEY_ID: a chave baseada em pontuação que você instalou no seu site.
• ACCOUNT_ID: um identificador de uma conta de usuário exclusiva 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 -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"

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

Ações recomendadas

Se você tiver o defensor da conta do reCAPTCHA ativado no 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 da MFA.

O exemplo a seguir mostra uma avaliação que recomenda pular a MFA como a ação recomendada:

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

O campo recommended_action pode ter qualquer um dos seguintes valores:

Acionar um teste de MFA no seu site

Para desafiar o usuário com base nas informações contidas na avaliação, envie o requestToken da MFA referente ao endpoint que você quer verificar na avaliação de volta para a 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 teste de MFA, faça o seguinte:

1. Teste a integração do MFA.

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

   • KEY_ID: a chave baseada em 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 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 teste 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á mostrado 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 um desafio 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 da MFA na página da Web

Depois de receber o PIN do usuário final, valide se ele está correto ou não.

Para validar o PIN, chame verificationHandle.verifyAccount() com o PIN inserido 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 avaliação com accountId e endpoints. Para instruções, consulte criar uma avaliação para 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:

A seguir

• Detectar e evitar atividades fraudulentas relacionadas à conta usando o defensor da conta do reCAPTCHA