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, você pode verificar se os usuários são os proprietários do endereço de e-mail que está associados à conta. A MFA protege os usuários contra ataques de preenchimento de credenciais e invasão de contas (ATOs, na sigla em inglês).

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

Entender o processo de configuração da MFA

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

De modo geral, 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 desafio de autenticação multifator (MFA) com o requestToken de acordo com o canal que deseja usar (apenas e-mail aceito).
  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 do 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, digite 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 crítico no seu site

Transmita as informações necessárias ao reCAPTCHA com o 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 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 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 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 as 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 enviá-lo para a avaliação 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 informar o seguinte como a conta identificador:

    Identificadores de usuários

    Se cada conta pode ser associada de forma exclusiva a um nome de usuário, endereço de e-mail ou telefone estável é possível usá-lo como o accountId. Quando você fornece esse tipo de identificadores (identificadores que podem ser reutilizados entre sites), o reCAPTCHA utiliza esse para melhorar a proteção de suas contas de usuário com base em modelos entre sites ao sinalizar identificadores de conta abusivos e usar conhecimento de padrões de abuso entre sites relacionados a esses identificadores.

    Como alternativa, se você tem um ID de usuário interno associado exclusivamente a cada conta, é possível forneça-o como accountId.

    Com hash ou criptografado

    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 defensor da conta reCAPTCHA entenda a atividade do usuário padrões e detectam comportamentos anômalos, mas eles não são compartilhados com outros sites.

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

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

    • hash do identificador da conta: recomendamos usar 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 seus identificadores de usuário para que você possa mapear o hash identificador de conta retornado às contas originais.

Adicione o parâmetro accountId e um endpoint, como um endereço de e-mail, ao verificar na avaliação do 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 de conta de usuário exclusivo do seu site.
  • EMAIL_ID: o endereço de e-mail que precisa 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 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ê tem um defensor da conta reCAPTCHA ativada para seu projeto, a resposta da avaliação vai conter informações relacionadas para o defensor da conta, além de informações relacionadas à autenticação multifator (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 um exemplo de avaliação que mostra a opção "Pular MFA" como ação recomendada:

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

O campo recommended_action pode ter qualquer um destes 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 seguro pular a autenticação multifator (MFA) nesta avaliação. Isso geralmente significa que o usuário foi verificado recentemente para o site nesse dispositivo.
REQUEST_2FA Indica que você aciona um desafio de autenticação multifator (MFA) para o usuário. Para mais informações, consulte a resposta à avaliação do defensor da conta.

Como acionar um desafio de autenticação multifator (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 da autenticação multifator (MFA).

    Acione um desafio de autenticação multifator (MFA) com um chame o challengeAccount() fornecendo os seguintes valores:

    • KEY_ID: a chave com base na pontuação que você instalou no site.
    • REQUEST_TOKEN_FROM_ASSESSMENT: valor do 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 Crie 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 um exemplo de avaliação que você recebe Ao criar uma nova avaliação usando o novo token obtido no 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 em 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-mail para (durante o teste) apenas).
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