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:
- Instrumentar 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 umrequestToken
de MFA. - Acione um desafio de MFA com o
requestToken
de acordo com o canal que você quer usar (somente e-mail compatível). - Verifique o PIN inserido pelo usuário final no seu site.
- Crie uma nova avaliação usando o token retornado na solicitação de verificação.
Antes de começar
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
Se você deseja ativar o recurso de verificação de e-mail da MFA, faça o seguinte:
No console do Google Cloud, acesse a página do reCAPTCHA Enterprise.
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.
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 no botão Ativar e-mail.
- Na caixa Nome do remetente, digite seu nome.
Na caixa E-mail do remetente, digite seu endereço de e-mail.
Clique em Save.
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:
- Para Python ou Java, use 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.
- 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 para a avaliação no métodoprojects.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.
Ações recomendadas
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:
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ávelnewToken
é transmitida para a função encadeada que contém o token de veredito 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 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). |