Padrões de Autenticação

Q: O que acontece se você esquecer de await a chamada cookies() no Next.js 15+?

cookies() é assíncrono no Next.js 15+ e retorna uma Promise. Esquecer await significa que você chama .get() em uma Promise, que retorna undefined. Isso quebra silenciosamente as verificações de autenticação, fazendo com que rotas protegidas pareçam não ter token.

Q: Você pode chamar redirect() dentro de um bloco try/catch?

redirect() lança internamente um erro especial NEXT_REDIRECT. Se envolvido em um try/catch, o redirecionamento é capturado e engolido, então o usuário nunca é redirecionado. Re-lance erros NEXT_REDIRECT ou chame redirect() fora do try/catch.

Q: Por que o Server Action de Login define httpOnly: true e secure: true no cookie?

httpOnly impede que o JavaScript leia o cookie, mitigando ataques XSS. secure garante que o cookie seja enviado apenas via HTTPS em produção. sameSite: "lax" fornece proteção básica contra CSRF.

Q: Armadilha: O que acontece se você usar variáveis de tempo de execução no array config.matcher do middleware?

O config.matcher deve ser estaticamente analisável em tempo de compilação. Usar variáveis ou chamadas de função faz com que o matcher falhe silenciosamente ou lance um erro de compilação. Coloque a lógica condicional dentro do corpo da função de middleware em vez disso.

Q: Como você tiparia o valor de retorno de verifySession em TypeScript?

JWTPayload de jose fornece o tipo base com iss, sub, exp, etc. Retorne null em caso de falha para que os chamadores possam fazer uma verificação simples de truthiness.

Q: Como você tipa a prop children em um componente de layout com TypeScript?

Use React.ReactNode para a prop children, que cobre elementos, strings, números, fragmentos e null.

Receita

Proteja páginas e rotas de API em uma aplicação Next.js 15+ App Router usando verificações de sessão baseadas em middleware, validação de autenticação no lado do servidor e proteção por página.

Exemplo de Funcionamento

Verificação de Sessão com Middleware

// middleware.ts
import { NextRequest, NextResponse } from "next/server";
 
const protectedPaths = ["/dashboard", "/settings", "/account"];
 
export function middleware(request: NextRequest) {
  const sessionToken = request.cookies.get("session-token")?.value;
  const { pathname } = request.nextUrl;
 
  const isProtected = protectedPaths.some((path) =>
    pathname.startsWith(path)
  );
 
  if (isProtected && !sessionToken) {
    const loginUrl = new URL("/login", request.url);
    loginUrl.searchParams.set("callbackUrl", pathname);
    return NextResponse.redirect(loginUrl);
  }
 
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/dashboard/:path*", "/settings/:path*", "/account/:path*"],
};

Autenticação no Lado do Servidor em um Layout

// app/dashboard/layout.tsx
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { verifySession } from "@/lib/auth";
 
export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const cookieStore = await cookies();
  const token = cookieStore.get("session-token")?.value;
 
  if (!token) {
    redirect("/login");
  }
 
  const session = await verifySession(token);
 
  if (!session) {
    redirect("/login");
  }
 
  return <>{children}</>;
}

Utilitário de Autenticação (Somente Servidor)

// lib/auth.ts
import "server-only";
import { SignJWT, jwtVerify } from "jose";
 
const secret = new TextEncoder().encode(process.env.AUTH_SECRET);
 
export async function createSession(userId: string) {
  return new SignJWT({ userId })
    .setProtectedHeader({ alg: "HS256" })
    .setExpirationTime("7d")
    .sign(secret);
}
 
export async function verifySession(token: string) {
  try {
    const { payload } = await jwtVerify(token, secret);
    return payload;
  } catch {
    return null;
  }
}

// app/login/actions.ts
"use server";
 
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { createSession } from "@/lib/auth";
 
export async function login(formData: FormData) {
  const email = formData.get("email") as string;
  const password = formData.get("password") as string;
 
  // Valide as credenciais contra seu banco de dados
  const user = await authenticateUser(email, password);
 
  if (!user) {
    return { error: "Credenciais inválidas" };
  }
 
  const token = await createSession(user.id);
  const cookieStore = await cookies();
 
  cookieStore.set("session-token", token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    maxAge: 60 * 60 * 24 * 7, // 7 dias
    path: "/",
  });
 
  redirect("/dashboard");
}

Análise Detalhada

Como Funciona

Middleware é executado na borda (edge) antes que qualquer página ou rota de API seja renderizada. Ele pode ler cookies e cabeçalhos, mas não pode acessar um banco de dados diretamente. Use-o para verificações rápidas e de alto nível (um token está presente?).
Componentes de Servidor e layouts são executados no servidor Node.js. Eles podem realizar a verificação completa da sessão contra um banco de dados ou segredo JWT.
A importação server-only garante que lib/auth.ts nunca possa ser incluído no código do cliente, evitando vazamento de segredos.
Cookies são o principal transporte de sessão no App Router. A função cookies() é assíncrona no Next.js 15+ e deve ser aguardada.
redirect() lança internamente, então o código após ele é inalcançável. Nenhum return explícito é necessário após redirect().

Variações

Usando NextAuth.js (Auth.js v5):

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
});
 
// middleware.ts
export { auth as middleware } from "./auth";

Acesso Baseado em Papel:

// app/admin/layout.tsx
import { verifySession } from "@/lib/auth";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
 
export default async function AdminLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const cookieStore = await cookies();
  const token = cookieStore.get("session-token")?.value;
  const session = await verifySession(token!);
 
  if (session?.role !== "admin") {
    redirect("/unauthorized");
  }
 
  return <>{children}</>;
}

Notas de TypeScript

cookies().get() retorna { name: string; value: string } | undefined. Sempre use encadeamento opcional.
Server Actions que retornam dados (como { error: string }) não podem chamar redirect() no mesmo caminho de código, porque redirect() lança um erro.
Use import "server-only" no topo de qualquer módulo que contenha segredos para obter um erro em tempo de compilação se ele for importado de um Client Component.

Armadilhas

Middleware não pode acessar bancos de dados ou APIs do Node.js. Ele é executado no Edge Runtime por padrão. Verifique apenas a presença do token; verifique tokens em Server Components ou Route Handlers.
cookies() é assíncrono no Next.js 15+. Esquecer await produz um erro em tempo de execução.
O matcher do middleware deve ser estático. Você não pode usar variáveis de tempo de execução no array config.matcher. Use lógica condicional dentro da função de middleware em vez disso.
redirect() dentro de um try/catch será engolido porque ele lança um erro especial NEXT_REDIRECT. Re-lance-o ou chame redirect() fora do try/catch.
Páginas estáticas não podem verificar autenticação no momento da requisição. Use export const dynamic = "force-dynamic" ou execute a autenticação no middleware para páginas geradas estaticamente.

Alternativas

Abordagem	Prós	Contras
Apenas Middleware	Rápido, executa antes da renderização	Não pode verificar tokens contra o banco de dados
Autenticação Baseada em Layout	Acesso completo ao servidor, pode consultar o banco de dados	Executa após o middleware, leve latência
NextAuth.js (Auth.js)	Provedores integrados, gerenciamento de sessão	Dependência extra, mudanças de migração
Clerk ou Supabase Auth	Serviço gerenciado, menos código	Bloqueio de fornecedor, custo em escala
Iron Session	Cookies criptografados, sem JWT	Comunidade menor, configuração manual

FAQs

Por que o middleware apenas verifica a presença de um token em vez de verificá-lo completamente?

O middleware é executado no Edge Runtime, que não pode acessar bancos de dados ou a maioria das APIs do Node.js.
Uma verificação completa de JWT com consulta ao banco de dados é muito pesada para a borda.
O middleware realiza uma verificação de alto nível (o cookie está presente?), então os Server Components fazem a verificação completa.

O que acontece se você esquecer de `await` a chamada `cookies()` no Next.js 15+?

cookies() é assíncrono no Next.js 15+ e retorna uma Promise.
Esquecer await significa que você chama .get() em uma Promise, que retorna undefined.
Isso quebra silenciosamente as verificações de autenticação, fazendo com que rotas protegidas pareçam não ter token.

Por que `import "server-only"` é usado no topo de `lib/auth.ts`?

Ele garante um erro em tempo de compilação se algum Client Component importar este módulo.
Isso impede que seu AUTH_SECRET e a lógica de assinatura JWT vazem para o bundle do navegador.

Você pode chamar `redirect()` dentro de um bloco try/catch?

redirect() lança internamente um erro especial NEXT_REDIRECT.
Se envolvido em um try/catch, o redirecionamento é capturado e engolido, então o usuário nunca é redirecionado.
Re-lance erros NEXT_REDIRECT ou chame redirect() fora do try/catch.

Como funciona o padrão `callbackUrl` no redirecionamento do middleware?

Quando um usuário não autenticado acessa um caminho protegido, o middleware redireciona para /login.
O pathname original é anexado como ?callbackUrl=/dashboard (ou qualquer que seja o caminho solicitado).
Após o login bem-sucedido, seu manipulador de login pode ler este parâmetro e redirecionar de volta para a página original.

Qual é a diferença entre autenticação baseada em middleware e autenticação baseada em layout?

O middleware é executado antes de qualquer renderização, na borda, e só pode fazer verificações leves.
A autenticação baseada em layout é executada no servidor Node.js, pode consultar um banco de dados e verificar completamente uma sessão.
A melhor prática é combinar ambos: middleware para um gate rápido, layout para verificação completa.

Por que o Server Action de Login define `httpOnly: true` e `secure: true` no cookie?

httpOnly impede que o JavaScript leia o cookie, mitigando ataques XSS.
secure garante que o cookie seja enviado apenas via HTTPS em produção.
sameSite: "lax" fornece proteção básica contra CSRF.

Armadilha: O que acontece se você usar variáveis de tempo de execução no array `config.matcher` do middleware?

O config.matcher deve ser estaticamente analisável em tempo de compilação.
Usar variáveis ou chamadas de função faz com que o matcher falhe silenciosamente ou lance um erro de compilação.
Coloque a lógica condicional dentro do corpo da função de middleware em vez disso.

Como você tiparia o valor de retorno de `verifySession` em TypeScript?

import { JWTPayload } from "jose";
 
export async function verifySession(
  token: string
): Promise<JWTPayload | null> {
  try {
    const { payload } = await jwtVerify(token, secret);
    return payload;
  } catch {
    return null;
  }
}

JWTPayload de jose fornece o tipo base com iss, sub, exp, etc.
Retorne null em caso de falha para que os chamadores possam fazer uma verificação simples de truthiness.

Como você tipa a prop `children` em um componente de layout com TypeScript?

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // ...
}

Use React.ReactNode para a prop children, que cobre elementos, strings, números, fragmentos e null.

Por que páginas geradas estaticamente não podem verificar autenticação no momento da requisição?

Páginas estáticas são pré-renderizadas em tempo de compilação e servidas como arquivos HTML simples.
Não há execução no lado do servidor no momento da requisição para ler cookies ou verificar sessões.
Use export const dynamic = "force-dynamic" ou proteja a rota via middleware em vez disso.

Como o NextAuth.js (Auth.js v5) simplifica a configuração do middleware?

Você exporta auth as middleware diretamente, o que lida com verificações de sessão automaticamente.
Auth.js gerencia provedores, armazenamento de sessão e rotação de tokens prontos para uso.
A troca é uma dependência extra e manter-se atualizado com as mudanças de migração do Auth.js.

Relacionados

Route Handlers - proteja endpoints de API com os mesmos utilitários de autenticação
Variáveis de Ambiente - armazenando AUTH_SECRET com segurança
Tratamento de Erros - tratando falhas de autenticação graciosamente
Documentação do Middleware do Next.js

// middleware.ts
import { NextRequest, NextResponse } from "next/server";
 
const protectedPaths = ["/dashboard", "/settings", "/account"];
 
export function middleware(request: NextRequest) {
  const sessionToken = request.cookies.get("session-token")?.value;
  const { pathname } = request.nextUrl;
 
  const isProtected = protectedPaths.some((path) =>
    pathname.startsWith(path)
  );
 
  if (isProtected && !sessionToken) {
    const loginUrl = new URL("/login", request.url);
    loginUrl.searchParams.set("callbackUrl", pathname);
    return NextResponse.redirect(loginUrl);
  }
 
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/dashboard/:path*", "/settings/:path*", "/account/:path*"],
};

Autenticação no Lado do Servidor em um Layout

// app/dashboard/layout.tsx
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { verifySession } from "@/lib/auth";
 
export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const cookieStore = await cookies();
  const token = cookieStore.get("session-token")?.value;
 
  if (!token) {
    redirect("/login");
  }
 
  const session = await verifySession(token);
 
  if (!session) {
    redirect("/login");
  }
 
  return <>{children}</>;
}

Utilitário de Autenticação (Somente Servidor)

// lib/auth.ts
import "server-only";
import { SignJWT, jwtVerify } from "jose";
 
const secret = new TextEncoder().encode(process.env.AUTH_SECRET);
 
export async function createSession(userId: string) {
  return new SignJWT({ userId })
    .setProtectedHeader({ alg: "HS256" })
    .setExpirationTime("7d")
    .sign(secret);
}
 
export async function verifySession(token: string) {
  try {
    const { payload } = await jwtVerify(token, secret);
    return payload;
  } catch {
    return null;
  }
}

// app/login/actions.ts
"use server";
 
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { createSession } from "@/lib/auth";
 
export async function login(formData: FormData) {
  const email = formData.get("email") as string;
  const password = formData.get("password") as string;
 
  // Valide as credenciais contra seu banco de dados
  const user = await authenticateUser(email, password);
 
  if (!user) {
    return { error: "Credenciais inválidas" };
  }
 
  const token = await createSession(user.id);
  const cookieStore = await cookies();
 
  cookieStore.set("session-token", token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    maxAge: 60 * 60 * 24 * 7, // 7 dias
    path: "/",
  });
 
  redirect("/dashboard");
}

Análise Detalhada

Como Funciona

Middleware é executado na borda (edge) antes que qualquer página ou rota de API seja renderizada. Ele pode ler cookies e cabeçalhos, mas não pode acessar um banco de dados diretamente. Use-o para verificações rápidas e de alto nível (um token está presente?).
Componentes de Servidor e layouts são executados no servidor Node.js. Eles podem realizar a verificação completa da sessão contra um banco de dados ou segredo JWT.
A importação server-only garante que lib/auth.ts nunca possa ser incluído no código do cliente, evitando vazamento de segredos.
Cookies são o principal transporte de sessão no App Router. A função cookies() é assíncrona no Next.js 15+ e deve ser aguardada.
redirect() lança internamente, então o código após ele é inalcançável. Nenhum return explícito é necessário após redirect().

Variações

Usando NextAuth.js (Auth.js v5):

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
});
 
// middleware.ts
export { auth as middleware } from "./auth";

Acesso Baseado em Papel:

// app/admin/layout.tsx
import { verifySession } from "@/lib/auth";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
 
export default async function AdminLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const cookieStore = await cookies();
  const token = cookieStore.get("session-token")?.value;
  const session = await verifySession(token!);
 
  if (session?.role !== "admin") {
    redirect("/unauthorized");
  }
 
  return <>{children}</>;
}

Notas de TypeScript

cookies().get() retorna { name: string; value: string } | undefined. Sempre use encadeamento opcional.
Server Actions que retornam dados (como { error: string }) não podem chamar redirect() no mesmo caminho de código, porque redirect() lança um erro.
Use import "server-only" no topo de qualquer módulo que contenha segredos para obter um erro em tempo de compilação se ele for importado de um Client Component.

Armadilhas

Middleware não pode acessar bancos de dados ou APIs do Node.js. Ele é executado no Edge Runtime por padrão. Verifique apenas a presença do token; verifique tokens em Server Components ou Route Handlers.
cookies() é assíncrono no Next.js 15+. Esquecer await produz um erro em tempo de execução.
O matcher do middleware deve ser estático. Você não pode usar variáveis de tempo de execução no array config.matcher. Use lógica condicional dentro da função de middleware em vez disso.
redirect() dentro de um try/catch será engolido porque ele lança um erro especial NEXT_REDIRECT. Re-lance-o ou chame redirect() fora do try/catch.
Páginas estáticas não podem verificar autenticação no momento da requisição. Use export const dynamic = "force-dynamic" ou execute a autenticação no middleware para páginas geradas estaticamente.

Alternativas

Abordagem	Prós	Contras
Apenas Middleware	Rápido, executa antes da renderização	Não pode verificar tokens contra o banco de dados
Autenticação Baseada em Layout	Acesso completo ao servidor, pode consultar o banco de dados	Executa após o middleware, leve latência
NextAuth.js (Auth.js)	Provedores integrados, gerenciamento de sessão	Dependência extra, mudanças de migração
Clerk ou Supabase Auth	Serviço gerenciado, menos código	Bloqueio de fornecedor, custo em escala
Iron Session	Cookies criptografados, sem JWT	Comunidade menor, configuração manual

FAQs

Por que o middleware apenas verifica a presença de um token em vez de verificá-lo completamente?

O middleware é executado no Edge Runtime, que não pode acessar bancos de dados ou a maioria das APIs do Node.js.
Uma verificação completa de JWT com consulta ao banco de dados é muito pesada para a borda.
O middleware realiza uma verificação de alto nível (o cookie está presente?), então os Server Components fazem a verificação completa.

O que acontece se você esquecer de `await` a chamada `cookies()` no Next.js 15+?

cookies() é assíncrono no Next.js 15+ e retorna uma Promise.
Esquecer await significa que você chama .get() em uma Promise, que retorna undefined.
Isso quebra silenciosamente as verificações de autenticação, fazendo com que rotas protegidas pareçam não ter token.

Por que `import "server-only"` é usado no topo de `lib/auth.ts`?

Ele garante um erro em tempo de compilação se algum Client Component importar este módulo.
Isso impede que seu AUTH_SECRET e a lógica de assinatura JWT vazem para o bundle do navegador.

Você pode chamar `redirect()` dentro de um bloco try/catch?

redirect() lança internamente um erro especial NEXT_REDIRECT.
Se envolvido em um try/catch, o redirecionamento é capturado e engolido, então o usuário nunca é redirecionado.
Re-lance erros NEXT_REDIRECT ou chame redirect() fora do try/catch.

Como funciona o padrão `callbackUrl` no redirecionamento do middleware?

Quando um usuário não autenticado acessa um caminho protegido, o middleware redireciona para /login.
O pathname original é anexado como ?callbackUrl=/dashboard (ou qualquer que seja o caminho solicitado).
Após o login bem-sucedido, seu manipulador de login pode ler este parâmetro e redirecionar de volta para a página original.

Qual é a diferença entre autenticação baseada em middleware e autenticação baseada em layout?

O middleware é executado antes de qualquer renderização, na borda, e só pode fazer verificações leves.
A autenticação baseada em layout é executada no servidor Node.js, pode consultar um banco de dados e verificar completamente uma sessão.
A melhor prática é combinar ambos: middleware para um gate rápido, layout para verificação completa.

Por que o Server Action de Login define `httpOnly: true` e `secure: true` no cookie?

httpOnly impede que o JavaScript leia o cookie, mitigando ataques XSS.
secure garante que o cookie seja enviado apenas via HTTPS em produção.
sameSite: "lax" fornece proteção básica contra CSRF.

Armadilha: O que acontece se você usar variáveis de tempo de execução no array `config.matcher` do middleware?

O config.matcher deve ser estaticamente analisável em tempo de compilação.
Usar variáveis ou chamadas de função faz com que o matcher falhe silenciosamente ou lance um erro de compilação.
Coloque a lógica condicional dentro do corpo da função de middleware em vez disso.

Como você tiparia o valor de retorno de `verifySession` em TypeScript?

import { JWTPayload } from "jose";
 
export async function verifySession(
  token: string
): Promise<JWTPayload | null> {
  try {
    const { payload } = await jwtVerify(token, secret);
    return payload;
  } catch {
    return null;
  }
}

JWTPayload de jose fornece o tipo base com iss, sub, exp, etc.
Retorne null em caso de falha para que os chamadores possam fazer uma verificação simples de truthiness.

Como você tipa a prop `children` em um componente de layout com TypeScript?

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // ...
}

Use React.ReactNode para a prop children, que cobre elementos, strings, números, fragmentos e null.

Por que páginas geradas estaticamente não podem verificar autenticação no momento da requisição?

Páginas estáticas são pré-renderizadas em tempo de compilação e servidas como arquivos HTML simples.
Não há execução no lado do servidor no momento da requisição para ler cookies ou verificar sessões.
Use export const dynamic = "force-dynamic" ou proteja a rota via middleware em vez disso.

Como o NextAuth.js (Auth.js v5) simplifica a configuração do middleware?

Você exporta auth as middleware diretamente, o que lida com verificações de sessão automaticamente.
Auth.js gerencia provedores, armazenamento de sessão e rotação de tokens prontos para uso.
A troca é uma dependência extra e manter-se atualizado com as mudanças de migração do Auth.js.

Relacionados

Route Handlers - proteja endpoints de API com os mesmos utilitários de autenticação
Variáveis de Ambiente - armazenando AUTH_SECRET com segurança
Tratamento de Erros - tratando falhas de autenticação graciosamente
Documentação do Middleware do Next.js

Padrões de Autenticação

Buscar na documentação

Padrões de Autenticação