Configurar a autenticação multifator

Nesta página, descrevemos 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, você pode verificar se o endereço de e-mail associado às contas dos usuários é seu. A MFA pode ajudar a proteger seus 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, e não para chaves de caixa de seleção.

Entender o processo de configuração da MFA

O recurso de MFA do reCAPTCHA Enterprise é implementado no fluxo de trabalho normal do reCAPTCHA Enterprise.

De modo geral, o fluxo de trabalho de MFA é o seguinte:

  1. Instrumentar 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 desafio de MFA com o requestToken de acordo com o canal que você quer usar (somente e-mail compatível).
  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 Enterprise.

  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 reCAPTCHA para integração
    • QPS médio (mensagens de e-mail por segundo)
    • Pico de QPS (mensagens de e-mail por segundo)
    • Para a MFA de e-mail, o endereço do remetente e os endereços de e-mail ou domínios necessários durante o teste

  3. Se você deseja 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 do reCAPTCHA Enterprise.

      Acessar o reCAPTCHA Enterprise

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

      Se você não vir o nome do seu 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, digite seu nome.

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

    6. Clique em Save.

  4. Configure o reCAPTCHA Enterprise 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 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.

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

Criar uma avaliação

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

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

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

  • Configurar a autenticação no reCAPTCHA Enterprise.

    O método de autenticação escolhido depende do ambiente em que o reCAPTCHA Enterprise está configurado. A tabela a seguir ajuda você a escolher o método de autenticação apropriado 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 um provedor de nuvem diferente REST Use as chaves de API ou a federação de identidade da carga de trabalho.

    Se você quiser usá-las, recomendamos proteger as chaves aplicando restrições à chave de API.
    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 para a 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 o identificador da conta:

    Identificadores de usuários

    Se cada conta puder ser exclusivamente associada 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 (que podem ser reutilizados em vários sites), o reCAPTCHA Enterprise usa essas informações para melhorar a proteção das contas de usuário com base em modelos entre sites, sinalizando identificadores de conta abusivos e usando o conhecimento de padrões de abuso entre sites relacionados a esses identificadores.

    Como alternativa, se você tiver um ID do usuário interno associado exclusivamente a cada conta, será possível fornecê-lo como accountId.

    Com hash ou criptografado

    Se você não tiver um ID do 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 defensor da conta do reCAPTCHA Enterprise entenda os padrões de atividade do usuário e detecte comportamentos anômalos, mas ele não é compartilhado com outros sites.

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

    • criptografia (recomendado): criptografe o identificador da conta usando um método de criptografia determinístico que produza um texto criptografado estável. Para instruções detalhadas, consulte Criptografar dados de maneira determinista. 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. Descriptografe os identificadores opacos retornados pelo reCAPTCHA Enterprise para transformá-los em identificadores de usuários.

    • hash: recomendamos gerar hash do identificador da conta usando o método SHA256-HMAC com um sal personalizado de sua escolha. Como os hashes são unidirecionais, você precisa manter um mapeamento entre os hashes gerados e os identificadores de usuário para mapear o identificador de conta com hash que é retornado às contas originais.

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

Antes de usar os dados da solicitação, 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 em pontuação que você instalou no seu site.
  • ACCOUNT_ID: identificador de uma conta de usuário exclusivo do seu site.
  • EMAIL_ID: o endereço de e-mail que acionará a solicitação de verificação.

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 desafio 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 o defensor de conta do reCAPTCHA Enterprise estiver ativado para seu projeto, a resposta da avaliação conterá informações relacionadas ao defensor da conta, além das informações relacionadas à autenticação multifator. O campo recommended_action mostra a possível ação que você pode realizar antes de acionar o desafio de MFA.

Confira a seguir um exemplo de avaliação que mostra a ação recomendada de pular a MFA:

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

O campo recommended_action pode ter qualquer um dos seguintes valores:

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

Acione um desafio de MFA no seu site

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

  1. Testar a integração da MFA.

    Acione um desafio 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 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 abaixo 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 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 MFA na página da Web

Depois de receber o PIN do usuário final, você precisa validar se o PIN 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 nova 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.

No exemplo a seguir, mostramos um exemplo de avaliação que você recebe ao criar uma nova avaliação usando o novo token extraído 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 Este destinatário não está aprovado para enviar e-mails para (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