MODULO 3.2

🔐 Autenticacao e Onboarding

A porta de entrada do seu SaaS. Setup completo de Supabase Auth, JWT tokens, protecao de rotas, fluxos de onboarding e integracao com provedores sociais como Google e GitHub.

6
Topicos
50 min
Duracao
Intermediario
Nivel
Pratica
Tipo
1

🔑 Supabase Auth: Setup Completo

Autenticacao nao e algo que voce implementa do zero em 2026. Supabase Auth resolve signup, login, logout, reset de senha e OAuth com provedores sociais em minutos. O resultado e um JWT que identifica o usuario em cada request ao seu backend.

🎯 Conceito Principal

Supabase Auth suporta tres metodos principais: email/password (classico, usuario cria conta com credenciais), magic link (email com link de acesso, sem senha) e social login (Google, GitHub, Discord via OAuth). Voce configura uma vez e o Supabase gerencia tokens, sessoes e refresh automaticamente.

  • • createClient(): Inicializa o Supabase no frontend com a URL do projeto e a anon key. Essa instancia e usada em toda a aplicacao
  • • Auth Hooks: onAuthStateChange() escuta mudancas de estado (login, logout, token refresh). Fundamental para atualizar a UI em tempo real
  • • Session Management: Supabase gera um access_token (curta duracao, ~1h) e um refresh_token (longa duracao). O SDK renova automaticamente

💻 Setup do Supabase Client

1. Instalar e configurar:

// Terminal
npm install @supabase/supabase-js
// lib/supabase.ts
import
{ createClient } from '@supabase/supabase-js'
const
supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!
const
supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
export const
supabase = createClient(supabaseUrl, supabaseAnonKey)

2. Signup com email/senha:

const
{ data, error } = await supabase.auth.signUp({
email: 'user@example.com',
password: 'securePassword123',
options: {
data: { full_name: 'Joao Silva' } // metadata extra
}
})

3. Login + Magic Link + OAuth:

// Email/Password login
const
{ data } = await supabase.auth.signInWithPassword({
email, password
})
// Magic Link (sem senha)
await
supabase.auth.signInWithOtp({ email })
// Google OAuth
await
supabase.auth.signInWithOAuth({
provider: 'google',
options: { redirectTo: 'http://localhost:3000/auth/callback' }
})

4. Auth state listener:

supabase.auth.onAuthStateChange((event, session) => {
if (event === 'SIGNED_IN') {
console.log('User logged in:', session?.user.email)
router.push('/dashboard')
}
if (event === 'SIGNED_OUT') {
router.push('/login')
}
})

💡 Dica Pratica

Comece com email/senha + Google OAuth. Esses dois metodos cobrem 95% dos usuarios. Nao perca tempo configurando 10 provedores no MVP. Adicione GitHub se o publico for devs. O resto vem depois, quando voce tiver dados de quem realmente usa.

2

🪪 JWT Tokens e Sessoes

Quando o usuario faz login, o Supabase gera um JWT (JSON Web Token). Esse token e a "carteira de identidade digital" que viaja em cada request. Entender como ele funciona e onde armazenar e fundamental para seguranca.

🎯 Conceito Principal

Um JWT tem tres partes: header (algoritmo de assinatura), payload (dados do usuario: id, email, role, expiracao) e signature (prova de que ninguem adulterou). O backend verifica a assinatura sem consultar o banco a cada request.

  • • Access Token: Curta duracao (~1 hora). Enviado no header Authorization de cada request. Se vazar, o dano e limitado pelo tempo
  • • Refresh Token: Longa duracao (~30 dias). Usado para gerar novos access tokens sem pedir login novamente. Guardado com mais cuidado
  • • httpOnly Cookies vs localStorage: Cookies httpOnly sao mais seguros (inacessiveis via JavaScript, protegem contra XSS). localStorage e mais simples mas vulneravel a XSS

🔍 Anatomia de um JWT

// Um JWT decodificado tem esta estrutura:
// Header
{ "alg": "HS256", "typ": "JWT" }
// Payload (dados do usuario)
{
"sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"email": "user@example.com",
"role": "authenticated",
"iat": 1710000000, // issued at
"exp": 1710003600 // expires in 1h
}
// Signature
HMACSHA256(base64(header) + "." + base64(payload), secret)

📊 Onde Armazenar Tokens

httpOnly Cookies

  • + Inacessivel via JavaScript (protege contra XSS)
  • + Enviado automaticamente pelo browser
  • + Padrao recomendado para producao
  • - Precisa configurar CORS e SameSite
  • - Mais complexo de implementar

localStorage

  • + Simples de implementar
  • + Funciona sem configuracao de server
  • + Bom para MVPs e prototipos
  • - Vulneravel a XSS (scripts maliciosos leem)
  • - Nao recomendado para producao com dados sensiveis

💡 Dica Pratica

No MVP, use o Supabase SDK no modo padrao (ele guarda tokens em localStorage automaticamente). Quando for para producao, migre para o @supabase/ssr package que usa httpOnly cookies com Next.js middleware. A migracao e simples e esta documentada.

3

🛡️ Protecao de Rotas

De nada adianta ter autenticacao se qualquer pessoa consegue acessar /dashboard digitando a URL no browser. Protecao de rotas garante que paginas privadas so sao acessiveis por usuarios logados, e redireciona o resto para o login.

🎯 Conceito Principal

Em Next.js, existem duas abordagens para proteger rotas: server-side (middleware que roda antes da pagina carregar) e client-side (componente wrapper que checa auth no browser). A melhor pratica e combinar as duas para seguranca em camadas.

  • • Middleware (server-side): Roda no Edge antes de qualquer pagina. Checa o token no cookie e redireciona se invalido. Primeira linha de defesa
  • • AuthProvider (client-side): Context wrapper que verifica sessao no browser. Mostra loading enquanto checa. Segunda camada de protecao
  • • API Route Protection: Cada endpoint da API tambem precisa validar o token. Nunca confie apenas na protecao do frontend

💻 Middleware Next.js para Protecao de Rotas

middleware.ts (na raiz do projeto):

import
{ createServerClient } from '@supabase/ssr'
import
{ NextResponse } from 'next/server'
export async function
middleware(request) {
const response = NextResponse.next()
const supabase = createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{ cookies: { /* cookie handlers */ } }
)
const { data: { user } } = await supabase.auth.getUser()
// Redirect unauthenticated users to login
if (!user && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url))
}
// Redirect authenticated users away from login
if (user && request.nextUrl.pathname === '/login') {
return NextResponse.redirect(new URL('/dashboard', request.url))
}
return response
}
export const
config = {
matcher: ['/dashboard/:path*', '/login', '/register']
}

✓ O que FAZER

  • ✓ Usar middleware server-side como primeira linha de defesa
  • ✓ Validar token tambem no backend (API routes)
  • ✓ Mostrar loading skeleton enquanto checa autenticacao

✗ O que NAO fazer

  • ✗ Confiar apenas em checagem client-side (JavaScript desabilitado = bypass)
  • ✗ Deixar API routes sem protecao (qualquer um chama direto)
  • ✗ Mostrar flash de conteudo protegido antes do redirect
4

🎯 Onboarding Flow

O usuario acabou de criar conta. E agora? Se ele cair numa tela vazia sem saber o que fazer, voce perdeu. Onboarding e o fluxo que guia o usuario do "acabei de registrar" ate o "entendi como funciona e tive valor". Quanto menor o time-to-value, melhor.

🎯 Conceito Principal

Um bom onboarding tem tres etapas: welcome screen (boas-vindas personalizada com o nome do usuario), profile setup (coletar informacoes minimas para personalizar a experiencia) e first action guide (levar o usuario a fazer a primeira acao de valor no produto).

  • • Time-to-Value: Tempo entre o registro e o primeiro momento "aha" do usuario. Para apps de IA, isso e geralmente a primeira resposta util da IA
  • • Progressive Profiling: Nao peca tudo no registro. Colete nome e email no signup. Pergunte funcao e objetivo no onboarding. Descubra preferencias com o uso
  • • Checklist Pattern: Mostra uma lista de 3-5 acoes para completar. Progresso visual motiva. Notion, Linear e Slack usam esse padrao

🗺️ Fluxo de Onboarding Recomendado

👋

Welcome

Boas-vindas + nome do usuario

📝

Profile

Funcao, objetivo, preferencias

🚀

First Action

Guia para primeira conversa com IA

✅

Dashboard

Pronto para usar o produto

💻 Detectar Primeiro Acesso

// Em /dashboard/page.tsx
const
{ data: profile } = await supabase
.from('profiles')
.select('onboarding_completed')
.eq('user_id', user.id)
.single()
if
(!profile?.onboarding_completed) {
redirect('/onboarding') // First time? Go to onboarding
}
// After onboarding completes:
await
supabase
.from('profiles')
.update({ onboarding_completed: true })
.eq('user_id', user.id)

📊 Dados de Onboarding

  • • 63% dos usuarios consideram onboarding como fator decisivo para continuar usando um produto
  • • 3-5 passos e o numero ideal para um onboarding. Mais que isso e abandono cresce exponencialmente
  • • Primeira acao em <2 min: Se o usuario nao faz nada de valor nos primeiros 2 minutos, chance de churn sobe 40%

💡 Dica Pratica

A melhor forma de onboarding em apps de IA e levar o usuario a fazer a primeira pergunta. Welcome screen com nome, um campo de input grande e sugestoes de perguntas prontas como "Me ajude a escrever um email" ou "Resuma este documento". O "aha moment" e a primeira resposta da IA.

5

🌐 Social Login e OAuth

"Entrar com Google" nao e luxo, e obrigacao em 2026. Usuarios nao querem criar mais uma senha. Social login reduz friccao, aumenta conversao e pega dados verificados (nome, foto, email confirmado) de graca. OAuth e o protocolo por tras disso.

🎯 Conceito Principal

OAuth 2.0 funciona assim: o usuario clica "Entrar com Google" > e redirecionado para o Google > autoriza o acesso > Google manda um code de volta para sua app > seu backend troca o code por tokens do usuario. O Supabase faz tudo isso automaticamente.

  • • Google OAuth: Mais usado. Configure no Google Cloud Console > Credentials > OAuth 2.0. Adicione o redirect URL do Supabase. 5 minutos de setup
  • • GitHub OAuth: Ideal para produtos dev-focused. Settings > Developer Settings > OAuth Apps. Mesmo padrao de redirect
  • • Account Linking: Quando o mesmo email existe com email/senha E Google login. Supabase pode linkar automaticamente ou criar contas separadas (configuravel)

💻 Implementando Google + GitHub Login

Componente de Social Login:

function
SocialLogin() {
const handleOAuth = async (provider: 'google' | 'github') => {
const { error } = await supabase.auth.signInWithOAuth({
provider,
options: {
redirectTo: `${window.location.origin}/auth/callback`,
queryParams: {
access_type: 'offline', // Google: get refresh token
prompt: 'consent',
}
}
})
if (error) console.error('OAuth error:', error)
}
return (
<div className="space-y-3">
<button onClick={() => handleOAuth('google')}>
Entrar com Google
</button>
<button onClick={() => handleOAuth('github')}>
Entrar com GitHub
</button>
</div>
)
}

Auth Callback Route (app/auth/callback/route.ts):

import
{ NextResponse } from 'next/server'
import
{ createServerClient } from '@supabase/ssr'
export async function
GET(request: Request) {
const { searchParams } = new URL(request.url)
const code = searchParams.get('code')
if (code) {
const supabase = createServerClient(/* ... */)
await supabase.auth.exchangeCodeForSession(code)
}
return NextResponse.redirect(new URL('/dashboard', request.url))
}

💡 Dica Pratica

Habilite "auto-link" no Supabase Auth settings. Isso faz com que se alguem registrar com email/senha e depois tentar logar com Google (mesmo email), as contas sejam vinculadas automaticamente. Sem isso, o usuario fica preso com "email ja existe".

6

🛠️ Exercicio: Auth Completo

Hora de montar tudo. Neste exercicio voce vai implementar o fluxo completo de autenticacao: registro, login, logout, protecao de rotas e uma tela de onboarding para novos usuarios. E a base sobre a qual todo o resto do SaaS sera construido.

🛠️

Exercicio: Fluxo de Auth Completo

Tempo estimado: 35-50 minutos

1

Setup Supabase Auth

Criar projeto no Supabase, configurar variaveis de ambiente e instalar o SDK:

npm install @supabase/supabase-js @supabase/ssr
# .env.local
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOi...
2

Pagina de Registro + Login

Criar formularios com email/senha e botoes de Google/GitHub OAuth. Tratar erros de validacao e feedback visual:

// Pagina com 3 opcoes de login:
1. Formulario email/senha (signup + login)
2. Botao "Entrar com Google"
3. Botao "Entrar com GitHub"
4. Link "Esqueci minha senha" (signInWithOtp)
3

Middleware de Protecao

Criar middleware.ts que protege /dashboard/* e redireciona usuarios nao autenticados para /login. Redirecionar usuarios logados que acessam /login para /dashboard.

4

Dashboard Protegido

Criar pagina /dashboard que mostra dados do usuario logado (nome, email, avatar). Botao de logout funcional. Se nao logado, redireciona.

5

Tela de Onboarding

Detectar primeiro acesso via flag no banco. Mostrar onboarding com welcome, profile setup e sugestao de primeira acao. Marcar como completado apos finalizar.

✅ Criterios de Sucesso

☐ Registro com email/senha funciona
☐ Login com Google OAuth funciona
☐ Logout limpa sessao e redireciona
☐ Rotas protegidas redirecionam corretamente
☐ Dashboard mostra dados do usuario
☐ Onboarding aparece no primeiro acesso

🌟 Bonus

Adicione password strength indicator no formulario de registro e GitHub login como segundo provedor. Implemente email de confirmacao customizado via Supabase email templates.

📋 Resumo do Modulo

✓
Supabase Auth resolve tudo - Email/senha, magic link, Google OAuth. Setup em 30 minutos. SDK gerencia tokens e sessoes automaticamente.
✓
JWT: access + refresh tokens - Access token de curta duracao em cada request. Refresh token renova automaticamente. httpOnly cookies para producao.
✓
Protecao em camadas - Middleware server-side + AuthProvider client-side + validacao na API. Nunca confie apenas no frontend.
✓
Onboarding reduz churn - Welcome > Profile > First Action. Time-to-value em menos de 2 minutos. Checklist pattern motiva conclusao.
✓
Social login e obrigatorio - Google + GitHub cobrem 95% dos usuarios. Auto-link de contas evita conflitos. OAuth callback route e essencial.

Proximo Modulo:

Modulo 3.3 - Dashboard e Interface Principal. Layout design para apps com IA, componentes essenciais e responsividade.

← Modulo Anterior Voltar para Trilha 3 Proximo Modulo →