Documentação Auth21 Kernel

Introdução

A Auth21 Kernel é um provedor OAuth 2.0 / OpenID Connect com quatro pilares operacionais: Hosted, Bridge, Client embed e QR solo. O fluxo final continua padrão: sua aplicação recebe code, troca em /token e consulta /userinfo.

O que muda entre os modos é onde a identidade nasce. O que não muda é o contrato OAuth/OIDC, a sessão global da Auth21, a rotação de refresh token, a revogação por sessão e o uso de PKCE S256 no caminho moderno.

Quick Start

Se você quer sair do zero rápido, comece por Hosted. Ele é o caminho mais curto para validar callback, PKCE, /token, /userinfo e sessão local da sua app.

1. Crie a app em OAuth & Apps.
2. Cadastre a redirect_uri exata e copie issuer, client_id e client_secret.
3. Inicie o login pelo seu backend com state, code_verifier e code_challenge_method=S256.
4. No callback, valide state, troque code em /token e consulte /userinfo.
5. Crie sua sessão local e limpe os artefatos temporários de OAuth.

Checklist console

1. App OAuth ativa e com modo de identidade certo.
2. redirect_uri cadastrada exatamente como será usada no start e no token exchange.
3. Secretos guardados no backend, nunca no browser.
4. PKCE S256 validado no endpoint de start login.
5. Usuário de teste ativo para validar /userinfo.
6. Se usar QR, chave/entrada QR ativa para a app correta.
7. Se usar iframe, embed_parent_origins precisa conter a origem exata do site pai.
8. Se usar aprovação mobile no sistema cliente, a URL cliente de retomada/aprovação precisa estar pública e validada.
9. Integration Check e Sandbox executados antes de staging.

Processo completo

1. Seu backend gera state, code_verifier e code_challenge.
2. Seu frontend ou backend envia o usuario para /authorize.
3. A Auth21 autentica conforme o modo ativo: Hosted, Bridge, Client embed ou QR solo.
4. A Auth21 cria ou reaproveita a identity_session global.
5. A Auth21 devolve code para sua redirect_uri.
6. Seu backend troca o code em /token.
7. Seu backend consulta /userinfo e cria a sessão local da sua aplicação.

Fluxo oficial

O fluxo oficial recomendado continua server-to-server no callback. A Auth21 aceita qualquer stack, desde que o backend: valide state, envie code_verifier, proteja o client_secret e trate error antes de esperar code.

const url = new URL(`${process.env.AUTH21_ISSUER}/authorize`);
url.searchParams.set("response_type", "code");
url.searchParams.set("client_id", process.env.AUTH21_CLIENT_ID);
url.searchParams.set("redirect_uri", process.env.AUTH21_REDIRECT_URI);
url.searchParams.set("scope", "openid profile email");
url.searchParams.set("state", state);
url.searchParams.set("code_challenge", challenge);
url.searchParams.set("code_challenge_method", "S256");

const tokenResp = await fetch(`${process.env.AUTH21_ISSUER}/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-OAuth-Backend": "1" },
  body: JSON.stringify({
    grant_type: "authorization_code",
    code,
    client_id: process.env.AUTH21_CLIENT_ID,
    client_secret: process.env.AUTH21_CLIENT_SECRET,
    redirect_uri: process.env.AUTH21_REDIRECT_URI,
    code_verifier: verifier
  })
});

Exemplo completo

• /api/auth21/login monta OAuth com state + PKCE.
• /api/auth21/callback troca token, consulta userinfo e cria sessao local.
• /app representa sua area autenticada.

Explicação

Diagnóstico

Use o diagnóstico do painel para validar app, callback, PKCE, contrato por modo e respostas do provedor antes de culpar sua stack. Guarde sempre o trace_id das falhas.

• Status agregado: pass, warn ou fail.
• Checks com error_code estável e ação recomendada.
• Correlação com logs do core e troubleshooting rápido.

Sandbox

A Sandbox valida configuração, contrato de endpoints e cenários por modo sem emitir login real, token real ou sessão produtiva.

• Confere app, allowlist, secretos e contrato básico.
• Ajuda a validar Hosted, Bridge e QR antes de staging.
• Retorna trace_id para suporte e auditoria.

Erros comuns

Matriz staging-ready

Password Protection

Password Protection e a camada para operacoes sensiveis ligadas a credencial. Ele nao substitui o login Hosted nem o 2FA do fluxo principal; ele adiciona protecao extra em acao critica quando a jornada pede confirmacao adicional.

2FA

Hoje a Auth21 tem dois caminhos reais de 2FA: TOTP no login Hosted e step-up por email no core de seguranca. O Hosted ja traz caminho de MFA TOTP no proprio login. Para desafios operacionais e step-up, o modulo de 2FA por email continua integrado ao Email Studio. Ainda assim, o estado operacional deve ser tratado como implementado, mas dependente de configuracao e validacao por ambiente.

• TOTP fica no caminho de login do usuario hosted.
• Email 2FA fica melhor apresentado como step-up e confirmacao operacional.
• Entrega por email depende da infraestrutura de envio do ambiente.

Como integrar o 2FA por email

1. Ative a politica da app no console 2FA e ajuste TTL e tentativas.
2. No backend da sua app, chame POST /two-factor/challenge com client_id, client_secret, subject, email e action.
3. Mostre no seu frontend a tela para o usuario digitar o codigo de 6 digitos.
4. No backend da sua app, chame POST /two-factor/verify com challenge_token e code.
5. So conclua a sessao local ou a acao sensivel depois de receber status=pass / decision=allow.

Contrato minimo dos endpoints

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

{
  "status": "pass",
  "challenge_token": "token-gerado-pela-auth21",
  "method": "email",
  "reason_code": "TWO_FACTOR_EMAIL_SENT",
  "expires_at": "2026-05-28 16:00:00",
  "trace_id": "..."
}

{
  "challenge_token": "token-gerado-pela-auth21",
  "code": "123456",
  "action": "login_step_up"
}

{
  "status": "pass",
  "decision": "allow",
  "reason_code": "TWO_FACTOR_VERIFIED",
  "verified_at": "2026-05-28 15:55:00",
  "trace_id": "..."
}

O que o backend da sua app precisa fazer

• Nao chame /two-factor/challenge do browser. Chame sempre do backend para manter o client_secret fora do frontend.
• Guarde temporariamente o challenge_token na sessao local ou em storage server-side enquanto o usuario digita o codigo.
• Se o verify falhar, nao crie a sessao local e nao libere a acao sensivel.
• Se o verify passar, marque o step-up como concluido na sua sessao local e so entao finalize o login ou a operacao.
• Guarde o trace_id das falhas para diagnostico e suporte.

const challenge = await fetch(`${AUTH21_ISSUER}/two-factor/challenge`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Basic " + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")
  },
  body: JSON.stringify({
    subject: user.id,
    email: user.email,
    action: "login_step_up"
  })
}).then((r) => r.json());

const verification = await fetch(`${AUTH21_ISSUER}/two-factor/verify`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Basic " + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")
  },
  body: JSON.stringify({
    challenge_token: challenge.challenge_token,
    code: userCode,
    action: "login_step_up"
  })
}).then((r) => r.json());

Verification Layer

Verification Layer e a forma de reaproveitar o mesmo motor de challenge da Auth21 fora do login puro. Em vez de tratar OTP, approve-link e cross-device apenas como parte do 2FA, a app pode usar a mesma infraestrutura para qualquer acao sensivel.

Trust Center

Trust Center e a visao unica de readiness operacional da app. Em vez de obrigar o integrador a abrir Sandbox e Release Guard em telas separadas, ele consolida evidencias recentes, drift de configuracao e o estado geral de confianca da app em staging e producao.

• resume a ultima Sandbox executada;
• mostra readiness atual de staging e producao;
• exibe ultima publicacao e sinais de config drift;
• entrega uma leitura rapida de ready, warn ou blocked.

Session Center

Session Center fecha a camada inicial de Identity Operations da Auth21. Ele nao troca a autenticacao; ele ajuda a operar sessoes globais reais depois que a autenticacao ja aconteceu.

• lista sessoes ativas por organizacao;
• mostra source, device_id, IP de autenticacao, expiracao e subject;
• permite revogar sessao especifica;
• permite revogar todas as sessoes ativas de um mesmo subject.

Access Guard

Access Guard e a camada de decisao. Ele existe para dizer se uma operacao passa, falha ou exige step-up. Essa e uma das diferencas fortes da Auth21: autenticar e uma parte do problema; decidir acao sensivel e a outra.

• Decide allow, deny ou escalonamento.
• Pode acionar 2FA quando a operacao pede elevacao de confianca.
• Faz mais sentido como produto de seguranca transacional do que como detalhe de OAuth.

Email Studio

Email Studio funciona hoje como camada de branding, configuracao e historico para emails operacionais. Ele nao deve ser descrito sozinho como garantia de entrega: a parte visual existe, mas o envio real continua dependente da infraestrutura de email do ambiente.

• Use como camada de confianca e consistencia visual para desafios por email.
• Guarde branding e historico por app/tenant.
• Trate como suporte operacional, nao como prova de que o email ja esta validado em qualquer ambiente.

QR Reader Starter

Use o starter quando voce precisa adaptar a experiencia QR ao seu front sem quebrar o contrato do provedor. O importante nao e recriar OAuth; e respeitar o pareamento, a aprovacao e a finalizacao do fluxo.

• Trate QR como entrada visual do mesmo fluxo OAuth, nao como login separado.
• Se o desktop usar uma shell propria, a Auth21 ainda deve controlar a parte sensivel do QR e da aprovacao.
• Quando a app cliente concluir a aprovacao no mobile, ela ainda precisa finalizar o OAuth no backend do desktop.
• Em cenarios com iframe, valide sempre a origem do parent antes de processar o retorno.

Hosted + Embed

Use Hosted + Embed quando a identidade final continua na Auth21, mas a sua aplicacao quer controlar a casca da experiencia com iframe, shell propria ou retorno por postMessage.

1. O desktop inicia o mesmo OAuth padrao com /authorize e PKCE.
2. A Auth21 resolve que o pedido esta em contexto embed e conduz o login Hosted ou o QR de handoff.
3. Se houver QR, o mobile autentica na Auth21 e aprova o pedido.
4. A Auth21 devolve code para o contexto embed.
5. Sua aplicacao valida a origem do retorno, troca o code em /token e cria a sessao local.

Bridge + Embed

Use Bridge + Embed quando o login real continua no seu dominio, mas a jornada do utilizador precisa de UX embutida, retorno ao parent ou handoff desktop/mobile.

1. O desktop inicia /authorize normalmente.
2. A Auth21 identifica que a app usa Bridge e pode abrir o caminho de embed/QR para o desktop.
3. O mobile segue o handoff e volta para o seu sistema quando a aprovacao precisa ser concluida no seu dominio.
4. O seu backend devolve a prova de identidade ou a prova de aprovacao no contrato esperado.
5. A Auth21 continua o OAuth e a sua aplicacao conclui o fluxo no backend com /token.

Por que o leitor fica no cliente

A Auth21 nao oferece uma pagina generica e definitiva de leitura por camera para todos os cenarios porque a captura do QR, a permissao de camera, o contexto do dispositivo e a experiencia mobile precisam respeitar o dominio, a politica e o produto do cliente.

• A permissao de camera precisa ser pedida no contexto da aplicacao que o utilizador reconhece.
• O cliente pode precisar de branding, roteamento, login local ou sessao propria antes de aprovar um pending.
• O comportamento em mobile, PWA, app webview ou navegador corporativo varia e costuma ser responsabilidade do produto que esta recebendo o utilizador.
• A Auth21 continua dona do contrato de autenticacao e aprovacao, mas a camada de leitura precisa ser adaptavel ao canal do cliente.

Boas praticas para criar a pagina de leitura

• Limite a pagina de leitura a mobile ou contextos com camera real.
• Use HTTPS e contexto seguro do navegador para permissao de camera.
• Mostre claramente para qual aplicacao o utilizador esta aprovando acesso.
• Leia apenas QRs esperados para a sua jornada e trate codigos desconhecidos como invalidos.
• Nunca exponha client_secret, approval_secret ou qualquer chave sensivel no frontend.
• Quando a aprovacao exigir prova assinada, envie essa prova do backend, nao do browser.
• Se o desktop usar iframe, valide sempre a origem antes de aceitar postMessage.
• Implemente estados visuais claros: aguardando leitura, lido, aprovado, expirado e falhou.
• Mostre acao de retentativa quando o QR expirar ou quando o pedido ja tiver sido consumido.

Boas praticas para o funcionamento

• Inicie sempre do mesmo pedido OAuth do desktop; nao crie um login paralelo no mobile.
• Garanta que a chave QR/embed usada pela aplicacao e a chave atual registrada em OAuth & Apps.
• Se a aprovacao acontecer no seu dominio, publique uma URL cliente valida para receber o handoff mobile.
• Conclua o fluxo no backend com o mesmo redirect_uri usado no inicio.
• Trate QR, handoff e leitor como continuidade do OAuth, nao como mecanismo isolado de autenticacao.

Modos avancados

A Auth21 separa modo de identidade de modo de entrada. Isso importa porque o inicio muda, mas o final continua o mesmo: sua aplicacao recebe code e chama /token.