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.
Entender o processo de configuração da MFA
O recurso de MFA do reCAPTCHA é implementado sobre o fluxo de trabalho normal reCAPTCHA.
Em um nível alto, o fluxo de trabalho da MFA é o seguinte:
- Instrumente o fluxo de trabalho essencial no seu site.
- Crie uma avaliação usando o token retornado pela chamada
execute()e os parâmetros de MFA para receber umrequestTokende MFA. - Acione um teste de autenticação multifator (MFA) com o
requestTokende acordo com o canal que você quer usar (somente e-mail com suporte). - Verifique o PIN inserido pelo usuário final no seu site.
- Crie uma nova avaliação usando o token que é retornado na solicitação de verificação.
Antes de começar
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.
Se você quiser ativar o recurso de verificação de e-mail da MFA, faça o seguinte:
Noconsole, acesse a página reCAPTCHA. Google Cloud
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.
Clique em Configurações.
No painel Autenticação multifator, clique em Configurar.
Na caixa de diálogo Configurar MFA, faça o seguinte:
- Para ativar a verificação de e-mail, clique na opção Ativar e-mail.
- Na caixa Nome do remetente, insira seu nome.
Na caixa E-mail do remetente, insira seu endereço de e-mail.
Clique em Salvar.
Depois de configurar o endereço de e-mail do remetente, configure os registros DNS para evitar problemas de entrega. Nas etapas a seguir, substitua
example.compelo seu domínio.Adicione um registro SPF para permitir que o reCAPTCHA envie e-mails em seu nome:
Host: example.com Value: v=spf1 include:_spf.recaptchamail.goog ~allInclua as seguintes entradas CNAME para que os servidores encontrem a DKIM assinatura:
Host: recaptcha1._domainkey.example.com Value: recaptcha1._domainkey.recaptchamail.goog.Host: recaptcha2._domainkey.example.com Value: recaptcha2._domainkey.recaptchamail.goog.
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 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 com suporte 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 por aplicando restrições de chave de API.
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 por aplicando restrições de chave de API.
- Para outras linguagens, use a federação de identidade da carga de trabalho.
Escolha um identificador de conta estável
accountIdque não seja alterado com frequência pelo usuário e forneça-o à avaliação noprojects.assessments.createmétodo. 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 de conta:Identificadores de usuário
Se cada conta puder ser associada de maneira exclusiva 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 o
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 do reCAPTCHA entenda os padrões de atividade do usuário e detecte comportamentos anômalos, mas não é compartilhado em outros sites.
Escolha qualquer identificador de conta estável e deixe-o opaco antes de enviar para o reCAPTCHA usando criptografia ou hash:
Criptografia (recomendado): criptografe o identificador da conta usando um método de criptografia determinístico 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 os identificadores de usuário e os identificadores de usuário opacos correspondentes. Descriptografe os identificadores opacos retornados pelo reCAPTCHA para transformá-los no identificador de usuário.
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 você possa mapear o identificador de conta com 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: o Google Cloud ID do projeto.
- 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
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.
Ações recomendadas
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 ação possível que você pode realizar antes de acionar o teste de autenticação multifator (MFA).
O exemplo a seguir mostra uma avaliação de amostra que mostra a ação recomendada de ignorar a MFA:
{ [...], "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 defensor da conta não conseguiu fazer um julgamento para essa solicitação. |
SKIP_2FA |
Indica que o defensor da conta considera seguro ignorar a MFA para essa avaliação. Isso geralmente significa que o usuário foi verificado recentemente no seu site nesse dispositivo. |
REQUEST_2FA |
Indica que você aciona um teste de MFA para o usuário. Para mais informações, consulte a resposta da avaliação do defensor da conta. |
Acionar um teste de autenticação multifator (MFA) no seu site
Para desafiar o usuário com base nas informações contidas na avaliação, envie o requestToken de MFA referente ao endpoint que quer verificar a partir da avaliação de volta à página da Web.
Acione o teste de autenticação multifator (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 autenticação multifator (MFA), faça o seguinte:
Teste a integração da MFA.
Acione um teste de autenticação multifator (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
requestTokencampo 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 esse parâmetro, o teste será renderizado em uma sobreposição na parte de cima da página.
O exemplo a seguir mostra como acionar o desafio de autenticação multifator (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 for inserido, a variávelnewTokenserá transmitida para a função encadeada que contém o token de resultado a ser verificado por uma avaliação criada no back-end.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 de MFA na página da Web
Depois de receber o PIN do usuário final, você precisa validar se ele está correto.
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.
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-mails para (somente 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). |