Auth21 Kernel
Inicio Entrar

Auth21 Kernel | Autenticacao hospedada por email

Auth21 Mail2FA

Voce nao constroi infraestrutura OTP. Voce ativa autenticacao por email com paginas hosted, verificacao por link, OTP por email e controle de template pela propria Auth21.

Como funciona

Fluxo hospedado

Entenda o que a Auth21 hospeda, o que sua app configura e como o usuario conclui a autenticacao por email.

Ver fluxo

Quick Start

Primeira integracao

Veja a sequencia pratica para ativar a app, configurar credenciais, callback e disparar o challenge.

Abrir quick start

Template

Monte seu email

Veja logo, corpo, CTA, placeholders e o que o motor do runtime realmente preenche.

Ir para template

Seguranca

Erros e protecoes

Veja expiracao, tentativas, abuso, FAQ e referencia de erros do fluxo Mail2FA.

Ir para seguranca

Auth21 Mail2FA

Voce nao constroi infraestrutura OTP. Voce ativa autenticacao por email.

O Auth21 Mail2FA e uma solucao hospedada de autenticacao por email. A Auth21 gera o desafio, envia o email, hospeda a pagina OTP, hospeda a pagina de autorizacao por link e valida o resultado. A sua app so decide quando disparar o fluxo e o que fazer depois da verificacao.

Hospedado

Auth21 hospeda as paginas OTP e autorizacao por link.

Entrega

Auth21 envia o email e controla expiracao, tentativas e validacao.

Customizacao

Sua app pode usar o Padrao Auth21 ou um modelo proprio do Email Studio.

Integracao

O backend da sua app chama challenge e verify. O resto fica na Auth21.

Como funciona

Sua Aplicacao
      ↓
Auth21 Mail2FA
      ↓
Pagina OTP Hospedada
      ↓
Verificacao por Email
      ↓
Usuario Autenticado

A sua app continua dona da jornada de negocio. A Auth21 cuida da prova por email, das paginas hosted e da validacao do desafio. O objetivo e deixar o fluxo compreensivel em menos de 30 segundos para qualquer desenvolvedor novo no produto.

Quick Start

Esta e a sequencia principal para sair do zero rapido. Hoje a Auth21 trabalha com client_id, client_secret, aplicacao OAuth e callback. Se em alguma conversa interna voce chamar isso de API key, trate como a credencial da app no console atual.

1. Criar aplicacao

Crie uma aplicacao em OAuth & Apps. Essa aplicacao sera a origem do 2FA e do Email Studio.

2. Obter credenciais da app

Guarde o client_id e o client_secret. E isso que o backend da sua app usa para chamar /two-factor/challenge e /two-factor/verify.

3. Configurar dominio e callback

Ajuste redirect_uri e, quando aplicavel, origens confiaveis do seu fluxo. Para o caminho hosted do 2FA, a app tambem pode usar o return_to para concluir a operacao protegida.

4. Ativar a politica 2FA

Na tela 2FA, habilite o motor de desafio, defina TTL, tentativas e os escopos onde o 2FA deve atuar.

5. Escolher o email

Use o Padrao Auth21 ou salve um modelo no Email Studio e ative um item do historico no Hub da 2FA.

6. Iniciar autenticacao

No backend da sua app, chame POST /two-factor/challenge com as credenciais da aplicacao e os dados do usuario.

7. Receber o resultado

A sua app pode esperar o OTP manual ou o link de verificacao. Depois disso, ela chama /two-factor/verify ou aceita a aprovacao hosted para concluir a sessao.

Como desenvolver seu email no Studio

Blocos do template

  • Logo: imagem da marca da app.
  • Titulo: cabecalho principal do email.
  • Corpo: texto principal com placeholders reais.
  • Botao: CTA opcional que aponta para o link de verificacao.
  • Footer: texto de rodape opcional.
  • Footer URL: link opcional do rodape.

Regra importante

O Studio salva o visual e a copy. OTP, links, nome do usuario e expiracao continuam vindo do runtime do 2FA.

Exemplo de modelo compativel

Titulo:
Autorizacao de Login

Corpo:
Ola, [Nome do usuario],

Recebemos uma solicitacao de verificacao para a sua conta em {{app_name}}.

Use o codigo {{code}} para continuar.

Se preferir, abra:
[Link de verificacao]

Atenciosamente,
Equipe {{app_name}}

Botao:
Abrir verificacao segura

Placeholders suportados

O motor do 2FA substitui placeholders do template por valores reais no momento do envio.

Formato com chaves

{{app_name}}
{{action}}
{{code}}
{{minutes}}
{{verification_url}}
{{verification_link}}
{{otp_url}}
{{user_name}}
{{nome_do_usuario}}

Formato com colchetes

[Nome do usuario]
[Nome do usuário]
[nomedousuario]
[Link de verificacao]
[Link de verificação]

O que cada valor faz

  • {{code}}: codigo OTP do challenge.
  • {{minutes}}: tempo de validade do desafio.
  • {{verification_link}} / {{verification_url}}: link para a pagina hosted de autorizacao por link.
  • {{otp_url}}: link para a pagina hosted com campo OTP.
  • {{user_name}} / [Nome do usuario]: nome real do usuario, quando a app envia user_name, name ou full_name no challenge.
  • {{app_name}}: nome da aplicacao.

Como configurar no Hub da 2FA

  1. Abra o Email Studio Hub pela tela 2FA.
  2. Escolha um item do historico do Studio.
  3. Clique no card para selecionar.
  4. Clique em Salvar no proprio card.
  5. O modelo fica ativo imediatamente e deve continuar marcado ao reabrir o Hub.
  6. Para voltar ao fallback da Auth21, use Remover.

Regra do Hub

O modelo ativo do 2FA deve ser sempre um item salvo do historico do Studio, nao o estado solto atual do editor.

Dados que sua app precisa enviar

Para o email sair completo, o backend deve mandar dados reais no challenge. 

{
  "subject": "user-123",
  "email": "user@empresa.com",
  "user_name": "Maria Oliveira",
  "action": "login_step_up"
}

Se a app nao enviar user_name, name ou full_name, a Auth21 tenta derivar um fallback do email ou do subject.

Seguranca

Expiracao dos codigos

O TTL e definido na politica da app. Quando o prazo termina, OTP e link de verificacao deixam de funcionar.

Rate limiting e abuso

A politica de tentativas protege contra erro repetido e tentativas abusivas. O comportamento depende do limite configurado para a app.

Protecao contra brute force

O desafio e invalidado quando as tentativas ultrapassam o limite aceito. Para continuar, a app precisa disparar um novo challenge.

Infraestrutura hospedada

A Auth21 gerencia envio, pagina OTP, pagina de autorizacao por link, expiracao e validacao. A app cliente gerencia quando exigir o 2FA e o que fazer apos a verificacao.

Referencia de erros

Codigo Descricao
INVALID_OTPCodigo OTP invalido.
OTP_EXPIREDCodigo expirado.
TOO_MANY_ATTEMPTSNumero maximo de tentativas atingido.
RATE_LIMITEDLimite de requisicoes excedido.
INVALID_CALLBACKReturn ou callback invalido para a operacao.

FAQ

Preciso criar minha propria pagina OTP?

Nao. A Auth21 hospeda a pagina OTP e a pagina de autorizacao por link.

Preciso configurar SMTP?

Nao no fluxo de produto. O envio e responsabilidade da infraestrutura da Auth21 no ambiente em que o produto esta rodando.

Preciso armazenar codigos OTP?

Nao. A Auth21 gerencia o desafio, a expiracao e a validacao.

Posso remover o botao do email?

Sim. Deixe o button_text vazio e use apenas o OTP, o link textual ou ambos.

O Auth21 hospeda toda a experiencia de autenticacao por email?

Sim na parte de 2FA por email: envio, paginas hosted e validacao. A app cliente continua responsavel por iniciar o fluxo e concluir a operacao apos o resultado.

Changelog e status

Changelog resumido

v1.0.0
- Fluxo OTP hospedado
- Verificacao por email

v1.1.0
- Personalizacao visual
- Pagina de autorizacao por link
- Integracao com Email Studio

Status e atualizacoes

Para acompanhar novas entregas, use a pagina Novidades do console. Ela e o melhor lugar para divulgar melhorias de fluxo, runtime e experiencia do Mail2FA.

Checklist final

  • A app ativou 2FA e escolheu o modo correto de email?
  • O template do Studio usa placeholders que o motor entende?
  • O card salvo no Hub continua marcado como ativo quando a pagina reabre?
  • O backend envia user_name ou full_name no challenge?
  • O botao ficou vazio de proposito ou o CTA deveria existir?
  • O fluxo do usuario esta claro: OTP manual, link de verificacao ou ambos?