Configure a autenticação multifator

Esta página descreve como configurar a autenticação multifator (MFA) que lhe permite validar a identidade dos seus utilizadores através do envio de um código de validação por email. Com esta funcionalidade, pode validar se os seus utilizadores são proprietários do endereço de email associado à respetiva conta. A MFA pode ajudar a proteger os seus utilizadores contra ataques de preenchimento de credenciais e roubos de contas (ATOs).

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

Compreenda o processo de configuração da AAF

A funcionalidade de MFA do reCAPTCHA é implementada além do fluxo de trabalho reCAPTCHA normal.

A um nível elevado, o fluxo de trabalho da MFA é o seguinte:

  1. Instrumente o fluxo de trabalho crítico no seu Website.
  2. Crie uma avaliação usando o token devolvido pela chamada execute() e os parâmetros de MFA para obter uma MFA requestToken.
  3. Acionar um desafio de MFA com o requestToken de acordo com o canal que quer usar (apenas email suportado).
  4. Validar o PIN introduzido pelo utilizador final no seu Website.
  5. Crie uma nova avaliação usando o token devolvido no pedido de validação.

Antes de começar

  1. Prepare o seu ambiente para o reCAPTCHA.

  2. A MFA está acessível após uma revisão de segurança, que é iniciada quando adiciona uma conta de faturação ao seu projeto. Adicione uma conta de faturação para integrar o seu site nesta funcionalidade.

  3. Se quiser ativar a funcionalidade de validação por email da MFA, faça o seguinte:

    1. Na Google Cloud consola, aceda à página reCAPTCHA.

      Aceder ao reCAPTCHA

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

      Se não vir o nome do seu projeto, clique no seletor de recursos e, em seguida, selecione o seu projeto.

    3. Clique em Definições.

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

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

      1. Para ativar a validação de email, clique no botão Ativar email.
      2. Na caixa Nome do remetente, introduza o seu nome.

      3. Na caixa Email do remetente, introduza o seu endereço de email.

    6. Clique em Guardar.

  4. Configure o reCAPTCHA no seu Website através de chaves baseadas em pontuação.

Instrumente o fluxo de trabalho crítico no seu Website

Transmita as informações necessárias ao reCAPTCHA através da função execute() para a avaliação de risco. A função execute() devolve uma promessa que é resolvida após a geração do token.

Acrescente um parâmetro twofactor adicional à sua função execute(), conforme mostrado no seguinte exemplo de código:

  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 criou para o seu Website.

Crie uma avaliação

Com o token gerado pela função execute(), crie uma avaliação através das bibliotecas cliente do reCAPTCHA ou da API REST a partir do seu back-end.

Este documento mostra como criar uma avaliação para a MFA através da API REST. Para saber como criar uma avaliação através das bibliotecas de cliente, consulte o artigo Crie avaliações para Websites.

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

  • Configure a autenticação para o reCAPTCHA.

    O método de autenticação que escolher depende do ambiente onde o reCAPTCHA está configurado. A tabela seguinte ajuda a escolher o método de autenticação adequado e a interface suportada para configurar a autenticação:

    Ambiente Interface Método de autenticação
    Google Cloud
    • REST
    • Bibliotecas cliente
    		 Use contas de serviço anexadas.
    Nas instalações ou num fornecedor de nuvem diferente REST Use chaves da API ou a Workload Identity Federation.

    Se quiser usar chaves da API, recomendamos que as proteja aplicando restrições de chaves da API.
    Bibliotecas cliente

    Use o seguinte:

  • Escolha um identificador de conta estável accountId que não seja alterado com frequência pelo utilizador e faculte-o à avaliação no método projects.assessments.create. Este identificador de conta estável deve ter o mesmo valor para todos os eventos relacionados com o mesmo utilizador. Pode indicar o seguinte como identificador da conta:

    Identificadores de utilizadores

    Se cada conta puder ser associada de forma exclusiva a um nome de utilizador, um endereço de email ou um número de telefone estável, pode usá-lo como o accountId. Quando fornece esses identificadores entre sites (identificadores que podem ser reutilizados em vários sites), o reCAPTCHA usa estas informações para melhorar a proteção das suas contas de utilizador com base em modelos entre sites, ao sinalizar identificadores de contas abusivas e usar o conhecimento de padrões de abuso entre sites relacionados com estes identificadores.

    Em alternativa, se tiver um ID do utilizador interno associado exclusivamente a cada conta, pode fornecê-lo como o accountId.

    Com hash ou encriptadas

    Se não tiver um ID de utilizador interno associado exclusivamente a cada conta, pode transformar qualquer identificador estável num identificador de conta opaco e específico do site. Este identificador continua a ser necessário para o reCAPTCHA account defender compreender os padrões de atividade do utilizador e detetar comportamentos anómalos, mas não é partilhado com outros sites.

    Escolha um identificador de conta estável e torne-o opaco antes de o enviar para o reCAPTCHA através de encriptação ou aplicação de hash:

    • Encriptação (recomendada): encriptar o identificador da conta através de um método de encriptação determinístico que produz um texto cifrado estável. Para ver instruções detalhadas, consulte o artigo sobre como encriptar dados de forma determinística. Quando escolhe a encriptação simétrica em vez da aplicação de hash, não precisa de manter um mapeamento entre os seus identificadores de utilizadores e os identificadores de utilizadores opacos correspondentes. Descriptografar os identificadores opacos devolvidos pelo reCAPTCHA para os transformar no identificador do utilizador.

    • aplicar hash: recomendamos que aplique hash ao identificador da conta através do método SHA256-HMAC com um sal personalizado à sua escolha. Uma vez que os hashes são apenas de sentido único, tem de manter um mapeamento entre os hashes gerados e os identificadores de utilizadores para poder mapear o identificador da conta com hash que é devolvido às contas originais.

Adicione o parâmetro accountId e um ponto final, como um endereço de email, para validar na avaliação no método projects.assessments.create.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • TOKEN: token devolvido pela chamada grecaptcha.enterprise.execute().
  • KEY_ID: a chave baseada em pontuação que instalou no seu Website.
  • ACCOUNT_ID: um identificador de uma conta de utilizador que é exclusivo do seu Website.
  • EMAIL_ID: o endereço de email para o qual o pedido de validação tem de ser acionado.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Deve receber uma resposta JSON semelhante à seguinte:


{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "",
    }],
    "latestVerificationResult": "RESULT_UNSPECIFIED"
  }
}

A avaliação contém a data e a hora da validação bem-sucedida mais recente para os pontos finais indicados no dispositivo que emitiu o token, se existirem. Também contém um campo requestToken por ponto final, que contém uma string encriptada. Se decidir acionar um desafio de MFA para esse ponto final, tem de enviar esta string encriptada de volta para a página Web. Os tokens de pedido são válidos durante 15 minutos.

Se tiver o reCAPTCHA account defender ativado para o seu projeto, a resposta da avaliação contém informações relacionadas com o account defender, além das informações relacionadas com a MFA. O campo recommended_action mostra a possível ação que pode realizar antes de acionar o desafio da MFA.

O exemplo seguinte mostra uma avaliação de amostra que apresenta a opção Ignorar 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:

Valor Descrição
RECOMMENDED_ACTION_UNSPECIFIED Indica que o Account Defender não conseguiu emitir um julgamento para este pedido.
SKIP_2FA Indica que o Account Defender considera que é seguro ignorar a MFA para esta avaliação. Normalmente, isto significa que o utilizador foi validado recentemente para o seu site neste dispositivo.
REQUEST_2FA Indica que aciona um desafio de MFA para o utilizador. Para mais informações, consulte a resposta da avaliação do Account Defender.

Acione um desafio de MFA no seu Website

Para desafiar o utilizador com base nas informações contidas na avaliação, envie a MFA requestToken para o ponto final que quer validar a partir da avaliação de volta para a página Web.

Acione o desafio de MFA com uma chamada para challengeAccount(). A função challengeAccount() devolve uma promessa que é resolvida após a conclusão do desafio ou rejeitada se ocorrer um erro ou um limite de tempo. Após a conclusão, é gerado um novo token que contém informações atualizadas, o qual é, em seguida, enviado para avaliação.

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

  1. Teste a integração da MFA.

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

    • KEY_ID: a chave baseada em pontuação que instalou no seu Website.
    • REQUEST_TOKEN_FROM_ASSESSMENT: valor do campo requestToken da resposta da avaliação.
    • CONTAINER_HTML_COMPONENT_ID: ID do componente HTML no qual o desafio de validação tem de ser renderizado. Se não especificar este parâmetro, o desafio é renderizado numa sobreposição na parte superior da página.

    O exemplo seguinte mostra como acionar o desafio da 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 o pedido challengeAccount() for bem-sucedido, o componente HTML é apresentado para introduzir o PIN recebido. Depois de introduzir o PIN correto, a variável newToken é transmitida para a função encadeada que contém o token de veredicto a ser validado através de uma avaliação criada no back-end.

  2. Crie um identificador de validaçã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
    }
  });

Valide um código da MFA a partir da página Web

Depois de receber o PIN do utilizador final, tem de validar se o PIN está correto ou não.

Para validar o PIN, chame verificationHandle.verifyAccount() com o PIN introduzido pelo utilizador 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
  }
);

Crie uma nova avaliação

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

Após a conclusão do fluxo de trabalho no cliente, recebe um novo token que pode usar para obter o veredito da validação que acionou. A avaliação contém uma data/hora recente relativa à validação bem-sucedida mais recente, juntamente com um estado de resultado bem-sucedido.

O exemplo seguinte mostra uma avaliação de amostra que recebe após criar uma nova avaliação com o novo token obtido a partir do Website:

{
  [...],
  "accountVerification": {
    "endpoints": [{
      "emailAddress": "foo@bar.com",
      "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
      "lastVerificationTime": "2020-03-23 08:27:12 PST",
    }],
    "latestVerificationResult": "SUCCESS_USER_VERIFIED"
  }
}

O campo latestVerificationResult pode apresentar um estado diferente, conforme indicado na tabela seguinte:

Estado do resultado da validação Descrição
SUCCESS_USER_VERIFIED O utilizador foi validado com êxito.
ERROR_USER_NOT_VERIFIED O utilizador não passou no desafio de validação.
ERROR_SITE_ONBOARDING_INCOMPLETE O seu site não está corretamente integrado para usar a funcionalidade.
ERROR_RECIPIENT_NOT_ALLOWED Este destinatário não tem aprovação para enviar emails para (apenas durante os testes).
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED Este destinatário já recebeu demasiados códigos de validação num curto período.
ERROR_CUSTOMER_QUOTA_EXHAUSTED Excedeu a sua quota de MFA disponível.
ERROR_CRITICAL_INTERNAL A validação não foi concluída devido a um erro interno nos nossos sistemas.
RESULT_UNSPECIFIED Não existem informações sobre a validação mais recente (nunca foi validado).

O que se segue?