Implementando o MFA (login com segundo fator) no seu template

O MFA de login da Wake transforma a autenticação do cliente em dois passos: primeiro senha, depois uma chave de acesso enviada por e-mail. A API entrega as mutations e uma configuração de loja que fecha os outros métodos de login — mas a experiência dos dois passos não existe pronta no seu template. Ela precisa ser implementada.

Esta página explica o que customizar, em que ordem, e mostra como isso foi feito no template padrão (Awake) como referência.

Como o fluxo funciona

O cliente só está logado no fim do passo 2. Entre os dois passos ele não tem token e não tem sessão. O template precisa guardar o email retornado no passo 1 para usar no passo 2.

Para detalhes de argumentos, tipos de retorno e erros da mutation do passo 1, consulte a documentação da CustomerAuthenticatedLoginWith2FA.

Pré-requisitos

Ativando a configuração "Exigir login com segundo fator (senha + chave de acesso por e-mail) (Storefront)" no admin da loja:

Para utilizar o MFA, é necessário:

1. Acessar o admin da loja;
2. No menu lateral, procure por "Configurações" e depois "Configurações Gerais";
3. No campo "termo busca" digite "login" e encontre a configuração "Exigir login com segundo fator (senha + chave de acesso por e-mail) (Storefront)". Ative essa configuração.

O que precisa ser customizado

Esta é a parte que costuma ser subestimada. Não é só trocar a mutation.

Etapa 1 — Ler a configuração no template

A configuração Exigir login com segundo fator (senha + chave de acesso por e-mail) (Storefront) chega ao tema pelo objeto store.settings já convertida para booleano, sob a chave require_two_factor_login:

{{ if store.settings.require_two_factor_login }}
  <!-- renderizar o login de dois fatores -->
{{ else }}
  <!-- manter o login padrão da loja -->
{{ end }}

Se o seu código roda no front-end e precisa consultar a configuração pela Storefront API, use a query shopSetting com o nome original da configuração:

query {
  shopSetting(name: "LoginSegundoFatorObrigatorio") {
    name
    value
  }
}

Etapa 2 — Tela da senha (passo 1)

Reaproveite o formulário de login existente, trocando a mutation. O retorno não é um token — é o e-mail de destino da chave.

mutation CustomerAuthenticatedLoginWith2FA(
  $input: String!
  $password: String!
  $recaptchaToken: String
) {
  customerAuthenticatedLoginWith2FA(
    input: { input: $input, password: $password }
    recaptchaToken: $recaptchaToken
  ) {
    email
  }
}

Com o SDK:

const { data } = await sdk.customer.authenticateWith2FA(
  identificador,  // e-mail, CPF ou CNPJ
  senha,
  recaptchaToken
);

// Guarde este e-mail: ele é obrigatório no passo 2
const emailDestino = data.email;

Em caso de sucesso, avance a tela para o passo 2 e mostre ao cliente para qual e-mail a chave foi enviada.

Etapa 3 — Tela da chave de acesso (passo 2)

Nova tela (ou novo estado da mesma tela): um campo para a chave recebida por e-mail.

mutation CustomerAuthenticateAccessKey(
  $email: String!
  $accessKey: String!
  $recaptchaToken: String
) {
  customerAuthenticateAccessKey(
    email: $email
    accessKey: $accessKey
    recaptchaToken: $recaptchaToken
  ) {
    token
    type
    validUntil
  }
}

Com o SDK:

const login = await sdk.customer.authenticateAccessKey(
  emailDestino,   // o e-mail retornado no passo 1
  chaveDigitada,
  recaptchaToken
);

A partir daqui o cliente está autenticado — siga o mesmo tratamento de sessão que o seu template já faz hoje após o login.

Cuidados de UX nesta tela:

• Ofereça um caminho de reenvio da chave (voltar ao passo 1 e refazer com senha).
• Deixe visível o e-mail de destino, mascarado se necessário.
• A chave tem validade curta: trate o erro de chave expirada com mensagem própria e ofereça o reenvio.
• Permita voltar ao passo 1 para corrigir o identificador.

Etapa 4 — Remover os outros métodos de login da tela

Esta etapa não é opcional. Com a configuração ligada, a Storefront API recusa as mutations abaixo com o erro LOG156, sem executar nada:

Além disso, customerSendAccessKeyEmail passa a ter comportamento parcial:

Ou seja: se o seu template tem um fluxo de "entrar sem senha, só com a chave por e-mail", ele para de funcionar. Esse bloqueio é intencional — é ele que garante que ninguém obtenha uma chave de acesso sem saber a senha.

Use a leitura da configuração da Etapa 1 para esconder condicionalmente esses botões e formulários, em vez de removê-los do código. Assim o mesmo template atende lojas com e sem MFA.

Exemplo de referência: o que foi feito no Awake

O template padrão recebeu uma implementação de exemplo que você pode usar como base. Foram três frentes:

No repositório wake-components:

O componente entrega a estrutura das duas etapas e o script cuida das chamadas às duas mutations e da transição entre as telas.

No template da loja (awake):

A estrutura da condicional na página de autenticação é a seguinte:

{{ if store.settings.require_two_factor_login }}
  <!-- componente wake_login_two_factor + script wake_login_two_factor -->
{{ else }}
  <!-- login padrão: senha, social, simple login -->
{{ end }}

A chamada do componente e do script segue exatamente o mesmo padrão que o seu template já usa para os outros componentes wake_* — por exemplo o wake_login_social. Consulte o Pages/login/authenticate.html do Awake para a forma exata no seu caso.

⚠️ Lojas já instanciadas

Este ponto é decisivo para o planejamento da agência.

Consequência: em uma loja já existente, habilitar o MFA exige ajuste manual do template:

1. Replicar a lógica condicional de authenticate.html — renderizar wake_login_two_factor com o script wake_login_two_factor em vez do login padrão.
2. Estilizar as classes .wake-login-two-factor*.

Lojas novas já nascem com os dois arquivos.

Erros que o template precisa tratar

Ordem de ativação

1. Template implementa os dois passos          →  loja continua com login normal
2. Template esconde os métodos bloqueados      →  loja continua com login normal
3. Homologação do fluxo completo               →  loja continua com login normal
4. Ativação de LoginSegundoFatorObrigatorio    →  MFA passa a ser obrigatório

Invertida essa ordem, a loja fica sem login funcional entre o passo 4 e a conclusão do passo 1.