Índi Toggle Como proteger rotas com NextAuth e TypeScript O que é proteção de rotas com NextAuth Como proteger rotas com NextAuth e TypeScript O que é proteção de rotas com NextAuth Fundamentos da proteção no App Router Session no servidor Fundamentos da proteção no App Router Session no servidor Middleware como primeira barreira Validação dentro da rota Configuração inicial do NextAuth com TypeScript Instalação das dependências Configuração inicial do NextAuth com TypeScript Instalação das dependências Configuração inicial do NextAuth com TypeScript Instalação das dependências Módulo de declaração de tipos Callbacks para enriquecer a sessão Proteção de páginas, APIs e Server Actions Páginas privadas com Server Components Route Handlers Server Actions Proteção por papel e por recurso Tabela comparativa dos mecanismos de proteção Boas práticas de segurança Nunca confiar apenas na interface Boas práticas de segurança Nunca confiar apenas na interface Boas práticas de segurança Nunca confiar apenas na interface Usar cookies seguros Manter segredos fora do repositório Validar todas as entradas Aplicar o princípio do menor privilégio Registrar falhas importantes Evitar vazamento de existência de recursos Testes para verificar a proteção Erros comuns ao proteger rotas Confundir sessão com permissão Erros comuns ao proteger rotas: confundir sessão com permissão. Validar somente no Middleware Guardar autorização apenas no token Usar o ID enviado pelo cliente Logar dados sensíveis Esquecer páginas e APIs diferentes Ignorar a LGPD Checklist de implementação Perguntas Frequentes (FAQ) O NextAuth protege todas as rotas automaticamente?\n Perguntas Frequentes (FAQ) O NextAuth protege todas as rotas automaticamente? Qual é a diferença entre 401 e 403 em uma API protegida?\n O TypeScript impede que alguém acesse uma rota sem permissão?\n O TypeScript impede que alguém acesse uma rota sem permissão? É necessário usar o Middleware em todas as aplicações Next.js?\n Como revogar o acesso de um usuário que perdeu o perfil?\n O NextAuth ainda é chamado Auth.js? Conclusão Referências consultadas Perguntas Frequentes (FAQ) 1. O NextAuth protege todas as rotas automaticamente? Perguntas Frequentes (FAQ) 1. O NextAuth protege todas as rotas automaticamente? 2. Qual é a diferença entre 401 e 403 em uma API protegida? 3. O TypeScript impede que alguém acesse uma rota sem permissão? 4. É necessário usar o Middleware em todas as aplicações Next.js? 5. Como revogar o acesso de um usuário que perdeu o perfil? Proteger rotas com NextAuth e TypeScript é uma tarefa essencial em qualquer aplicação Next.js que possua áreas restritas, dados pessoais ou operações administrativas. A autenticação confirma quem é a pessoa visitante, enquanto a autorização determina o que essa pessoa pode fazer depois de entrar. Quando essas duas etapas não são bem separadas, um usuário autenticado pode acabar enxergando ou alterando informações que não deveria acessar.

O TypeScript, que é a extensão do JavaScript com verificação de tipos, ajuda a detectar possíveis erros antes da aplicação entrar em produção. Ainda assim, ele não protege uma rota sozinho. A segurança real depende da validação da sessão no servidor, da configuração correta dos callbacks, da checagem de permissões e de testes que tentem acessar cada endpoint sem autorização.

Este guia mostra uma abordagem prática para construir uma proteção de rotas com NextAuth e TypeScript, desde a configuração inicial até os testes de acesso. O foco está no App Router do Next.js, mas os conceitos de sessão e autorização também são úteis em projetos que ainda precisam planejar uma migração.

Este conteúdo tem caráter informativo. Decisões técnicas devem ser tomadas com profissional especializado.

O que é proteção de rotas com NextAuth

Uma rota é um endereço da aplicação que recebe uma requisição e devolve uma resposta. Em uma aplicação web, ela pode apresentar uma página, processar um formulário, buscar informações em uma API ou alterar dados. O Next.js permite criar essas rotas por meio de páginas, Server Components, Route Handlers, Server Actions e Middleware.

Proteger uma rota significa bloquear a execução de uma operação quando arequisição não presenta credenciais válidas ou não possui a permissão necessária. A resposta adequada pode ser um redirecionamento para a página de login, uma resposta 401 Unauthorized ou uma resposta 403 Forbidden.

NextAuth, atualmente conhecido pelo pacote Auth.js, é uma biblioteca que simplifica a autenticação em aplicações Next.js. Ela oferece autenticação por provedores externos, como Google e GitHub, além de fluxos com credenciais. O NextAuth mantém a sessão e disponibiliza funções e hooks para consultar o usuário autenticado.

É importante distinguir duas responsabilidades:

• Autenticação: verificar se a pessoa é quem ela diz ser.
• Autorização: verificar se essa pessoa pode acessar uma função ou recurso específico.

Uma sessão válida não significa acesso automático a tudo. Um usuário comum pode estar autenticado, mas ainda assim não pode editar uma configuração administrativa. Por isso, a proteção de rotas com NextAuth deve considerar o perfil, o papel e o contexto da operação.

Fundamentos da proteção no App Router

Session no servidor

A forma mais confiável de verificar uma sessão em uma rota do App Router é utilizar a função getServerSession, geralmente combinada com o manipulador auth configurado no arquivo de autenticação. Essa verificação acontece no servidor, portanto, o cookie da sessão e os dados sensíveis não são enviados ao navegador da pessoa visitante.

Considere uma configuração estruturada assim:

// src/lib/auth.ts
import NextAuth from "next-auth"
import Google from "next-auth/providers/google"

import { prisma } from "@/lib/prisma"

+export const { handlers, auth, signIn, signOut } = NextAuth({
+  providers: [
+    Google({
+      clientId: process.env.AUTH_GOOGLE_ID!,
+      clientSecret: process.env.AUTH_GOOGLE_SECRET!,
+    }),
+  ],
+  callbacks: {
+    async session({ session, token }) {
+      if (session.user && token.sub) {
+        session.user.id = token.sub
+      }
+
+      return session
+    },
+  },
+})

O sinal ! informa ao TypeScript que a variável de ambiente existe em tempo de compilação, mas não garante que ela esteja preenchida no servidor. O ideal é validar as variáveis logo na inicialização da aplicação, usando um mecanismo como o schema do Zod, para evitar que o projeto continue funcionando com uma configuração incompleta.

A função auth pode envolver o manipulador retornado pelo NextAuth:

// src/lib/auth.ts
import NextAuth from "next-auth"
+import { authConfig } from "./auth.config"
+
+export const { handlers, auth, signIn, signOut } = NextAuth(authConfig)

Essa separação é especialmente útil quando o Middleware precisa importar apenas a configuração leve, sem carregar dependências de banco de dados ou outros módulos pesados do Node.js.

Middleware como primeira barreira

O Middleware do Next.js é executado antes de a rota ser acessada. Ele pode verificar a presença de um cookie de autenticação e redirecionar visitantes que não possuem um token válido para a tela de entrada.

// src/middleware.ts
import { NextResponse } from "next/server"
+
+import { authConfig } from "@/lib/auth.config"
+
+export default authConfig((req) => {
+  const isLoggedIn = !!req.auth
+  const isOnDashboard = req.nextUrl.pathname.startsWith("/dashboard")
+
+  if (isOnDashboard && !isLoggedIn) {
+    return NextResponse.redirect(new URL("/login", req.url))
+  }
+
+  return NextResponse.next()
+})
+
+export const config = {
+  matcher: ["/dashboard/:path*"],
+}

O Middleware é uma primeira barreira, não a validação definitiva. Ele reduz acessos desnecessários, mas a rota ou o manipulador que executa a ação deve confirmar a sessão novamente no servidor. Isso evita que uma manipulação do Middleware ou uma falha de configuração exponha dados protected.

Validação dentro da rota

Uma rota administrativa deve buscar a sessão antes de consultar ou alterar dados. O TypeScript também deve ajudar a documentar o formato esperado da sessão, especialmente quando o modelo de usuário possui campos adicionais, comorole ou organizationIdUma rota administrativa deve buscar a sessão antes de consultar ou alterar dados. O TypeScript também deve ajudar a documentar o formato esperado da sessão, especialmente quando o modelo de usuário possui campos adicionais, como role ou organizationId.

// src/app/api/admin/users/route.ts
import { NextResponse } from "next/server"
+
+import { auth } from "@/lib/auth"
+
+export async function GET() {
+  const session = await auth()
+
+  if (!session?.user) {
+    return NextResponse.json(
+      { message: "Autenticação necessária." },
+      { status: 401 },
+    )
+  }
+
+  if (session.user.role !== "admin") {
+    return NextResponse.json(
+      { message: "Você não tem permissão para esta ação." },
+      { status: 403 },
+    )
+  }
+
+  return NextResponse.json({ users: [] })
+}

Esse padrão separa duas respostas importantes. O código 401 indica que a identidade não foi confirmada ou a sessão expirou. O código 403 indica que a pessoa está autenticada, porém não está autorizada a executar a ação.

Configuração inicial do NextAuth com TypeScript

Instalação das dependências

Em um projeto Next.js com App Router, a instalação pode ser feita com o gerenciador de pacotes escolhido pela equipe:

npm install next-auth
+```

Para persistir usuários e sessions em um banco de dados, também pode ser necessário instalar o adaptador correspondente. O Auth.js oferece adaptadores para bancos SQL e NoSQL, mas a escolha depende da infraestrutura e do modelo de dados.

As variáveis secretas devem ficar no arquivo de ambiente do servidor. O valor de `AUTH_SECRET` é usado para proteger os dados relacionados à sessão. Ele não deve ser publicado no repositório nem inserido diretamente no código.

```env
AUTH_SECRET=valor_gerado_pelo_seu_ambiente
AUTH_GOOGLE_ID=identificador_do_provedor
AUTH_GOOGLE_SECRET=segredo_do_provedor

As chaves públicas do provedor podem ser usadas pelo fluxo de autenticação, enquanto o segredo deve permanecer exclusivamente no ambiente de servidor.

Módulo de declaração de tipos

Para usar propriedades personalizadas da sessão com segurança, é útil augmentar os tipos do Auth.js. O nome abaixo é apenas uma extensão:

// src/types/next-auth.d.ts
import "next-auth"
+import "next-auth/jwt"
+
+declare module "next-auth" {
+  interface Session {
+    user: {
+      id: string
+      role: "user" | "admin"
+    } & DefaultSession["user"]
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    id?: string
+    role?: "user" | "admin"
+  }
+}

A declaração correta dos tipos deve ser ajustada à versão instalada e ao modo de autenticação adotado. Com o uso de adaptadores, o objeto da sessão pode ser montado por meio do callback session, e o papel pode ser consultado diretamente no banco.

Callbacks para enrichecer a sessão

O callback session permite incorporar informações que serão disponibilizadas ao servidor e aos componentes. O ideal é buscar dados atualizados no banco quando o papel ou a organização forem relevantes para a autorização.

+callbacks: {
+  async session({ session, token }) {
+    if (session.user && token.sub) {
+      session.user.id = token.sub
+      session.user.role = token.role ?? "user"
+    }
+
+    return session
+  },
+},

O callback jwt pode ser usado para adicionar propriedades ao token, conforme o provedor e a estratégia de sessão adotados. Entretanto, dados que mudam com frequência, como saldo, status de assinatura ou permissões revogadas, não devem permanecer desatualizados no token sem uma verificação adicional.

Proteção de páginas, APIs e Server Actions

Páginas privadas com Server Components

Uma página protegida deve consultar a sessão no servidor e redirecionar quando necessário:

// src/app/dashboard/page.tsx
+import { redirect } from "next/navigation"
+
+import { auth } from "@/lib/auth"
+
+export default async function DashboardPage() {
+  const session = await auth()
+
+  if (!session?.user) {
+    redirect("/login")
+  }
+
+  return (
+    <main>
+      <h1>Olá, {session.user.name}</h1>
+      <p>Esta área exige uma sessão válida.</p>
+    </main>
+  )
+}

O componente redirect interrompe a renderização no servidor e leva a pessoa visitante para a tela de login. Depois do retorno do login, a aplicação pode direcioná-la ao destino original com uma URL segura e validada.

Route Handlers

Route Handlers são funções que recebem requisições HTTP. Eles precisam rejeitar requisições não autenticadas antes de executar consultas, gravações ou integrações externas.

+import { NextResponse } from "next/server"
+
+import { auth } from "@/lib/auth"
+
+export async function POST(request: Request) {
+  const session = await auth()
+
+  if (!session?.user) {
+    return NextResponse.json(
+      { message: "Sessão ausente ou expirada." },
+      { status: 401 },
+    )
+  }
+
+  const body = await request.json()
+
+  return NextResponse.json({
+    message: "Operação recebida.",
+    createdBy: session.user.id,
+  })
+}

A validação do corpo da requisição é outra etapa indispensável. Mesmo com uma sessão válida, o dado enviado pode estar incompleto, fora dos limites esperados ou attempts de modificar um recurso de outra pessoa. Ferramentas como Zod podem validar a estrutura antes que ela alcance a camada de negócio.

Server Actions

Server Actions executam operações no servidor, mas isso não significa que sejam automaticamente protegidas. A função deve confirmar quem fez a solicitação e se essa pessoa pode realizar a ação.

+"use server"
+
+import { revalidatePath } from "next/cache"
+
+import { auth } from "@/lib/auth"
+
+export async function removeArticle(articleId: string) {
+  const session = await auth()
+
+  if (!session?.user) {
+    throw new Error("Autenticação necessária.")
+  }
+
+  if (session.user.role !== "admin") {
+    throw new Error("Permissão insuficiente.")
+  }
+
+  await deleteArticle(articleId)
+  revalidatePath("/artigos")
+}

Em produção, mensagens de erro Destination devem ser tratadas de forma controlada. A aplicação pode usar classes de erro e uma camada de apresentação que evita revelar detalhes internos da infraestrutura.

Proteção por papel e por recurso

Nem toda autorização depende apenas do papel. Em sistemas multiusuário, a pessoa pode acessar um projeto se ele for membro dele. Uma verificação segura combina a sessão com a relação entre usuário e recurso.

+const session = await auth()
+
+if (!session?.user) {
+  return NextResponse.json({ message: "Não autenticado." }, { status: 401 })
+}
+
+const project = await getProject(projectId)
+
+if (!project || project.ownerId !== session.user.id) {
+  return NextResponse.json({ message: "Acesso negado." }, { status: 403 })
+}

Essa lógica deve existir na camada que executa a operação. Esconder um botão no frontend melhora a experiência, mas não protege o dado, porque qualquer pessoa pode chamar a API diretamente.

Tabela comparativa dos mecanismos de proteção

Boas práticas de segurança

Nunca confiar apenas na interface

A interface pode esconder links, menus e botões, mas a decisão final deve acontecer no servidor. A camada visual não é uma barreira de segurança.

Usar cookies seguros

O NextAuth utiliza cookies para manter a sessão. A configuração de produção deve preservar atributos como httpOnly, sameSite e secure nas condições adequadas. O site deve ser publicado por HTTPS.

Manter segredos fora do repositório

Credenciais de provedores, chaves de API, strings de conexão e tokens devem ser armazenados em variáveis de ambiente ou em um serviço de secrets. Arquivos .env precisam ser incluídos no .gitignore.

Validar todas as entradas

A sessão informa quem está fazendo a requisição, mas não garante que os dados enviados sejam válidos. IDs devem ser conferidos, campos devem ter formato esperado e valores devem respeitar limites.

Aplicar o princípio do menor privilégio

Conceda apenas as permissões necessárias para cada tarefa. Se um usuário precisa visualizar relatórios, talvez ele não precise alterar configurações. Perfis bem definidos reduzem o impacto de erros de implementação.

Registrar falhas importantes

Registros de aplicação e ferramentas de observabilidade ajudam a identificar tentativas repetidas de acesso, sessões inválidas e falhas de autorização. Dados sensíveis não devem aparecer nos logs.

Evitar vazamento de existência de recursos

Em algumas aplicações, responder 404 em vez de 403 para recursos que não pertencem ao usuário evita confirmar que aquele registro existe. Essa decisão deve fazer parte da política de segurança e ser aplicada de forma consistente.

Testes para verificar a proteção

Proteger uma rota apenas porque o código parece correto não é suficiente. A equipe deve simular diferentes contextos de acesso.

Um roteiro básico pode conter:

• Acessar uma rota protegida sem cookie de sessão.
• Acessar a rota com uma sessão expirada.
• Acessar a rota com sessão válida.
• mas sem o papel exigido.
• Acessar um recurso pertencente a outra pessoa.
• Acessar uma API sem cabeçalho de autorização ou credencial adequada.
• Enviar uma Server Action diretamente.
• sem passar pela interface.
• Confirmar se os dados sensíveis não aparecem na resposta.
• Confirmar se os redirecionamentos não criam loops.

Em testes automatizados, as sessões podem ser simuladas por meio de uma estratégia de autenticação de teste, separada da configuração de produção. Essa estratégia deve existir apenas em ambientes controlados e nunca ser habilitada acidentalmente em um deploy.

A documentação de testes end-to-end do Next.js, como Playwright, pode ser usada para validar a jornada completa. Para a camada de regras, testes unitários com Vitest ou Jest ajudam a cobrir funções de autorização, enquanto testes de integração verificam a combinação entre sessão, banco de dados e rota.

Erros comuns ao proteger rotas

Confundir sessão com permissão

A presença de session.user comprova apenas que existe uma sessão. Se a rota exige um perfil específico, o código precisa comparar o papel ou a relação do usuário com o recurso.

Validar somente no Middleware

O Middleware é útil, mas a validação final deve acontecer junto à operação protegida. Se a regra estiver apenas no Middleware, um erro de matcher, configuração ou implantação pode deixar a rota aberta.

Guardar autorização apenas no token

O token pode ficar desatualizado. Quando um papel é alterado ou uma conta é bloqueada, a aplicação deve ter uma forma de invalidar ou atualizar a sessão. Para operações sensíveis, é recomendável consultar o banco novamente.

Usar o ID enviado pelo cliente

Não é seguro que um userId enviado pelo frontend corresponde à pessoa autenticada. Em operações, use o ID da sessão ou confirme a autorização do recurso informado.

Logar dados sensíveis

Cookies, tokens, senhas e informações pessoais não devem ser registrados. Um log deve conter apenas o necessário para diagnóstico, e ainda assim precisa passar por uma revisão de privacidade.

Esquecer páginas e APIs diferentes

Acesso protegido em uma página não protege automaticamente uma API, uma rota dinâmica ou uma Server Action. Cada superfície de execução precisa ser analisada separadamente.

Ignorar a LGPD

Aplicações que tratam dados pessoais precisam de uma base legal, minimização de dados, controle de acesso e políticas de retenção. A autenticação ajuda a reduzir acessos indevidos, mas não substitui uma postura completa de proteção de dados.

Checklist de implementação

Antes de considerar a proteção concluída, revise os seguintes pontos:

• A sessão é obtida no servidor por auth() ou getServerSession().
• Páginas privadas redirecionam visitantes sem sessão válida.
• APIs retornam 401 quando a autenticação está ausente.
• APIs retornam 403 quando a autorização está negada.
• Regras por papel e por recurso estão aplicadas no servidor.
• Dados recebidos em formulários.
• JSON e Server Actions são validados.
• Variáveis secretas não estão no repositório.
• Cookies operam com HTTPS e atributos seguros.
• O Middleware possui um matcher restrito às rotas necessárias.
• A página de login não cria redirecionamento infinito.
• Existem testes para usuário anônimo.
• usuário comum e administrador.
• Logs não registram credenciais ou dados pessoais desnecessários.
• Alterações de papel e revogações de acesso são refletidas em um tempo aceitável.

Perguntas Frequentes (FAQ)

O NextAuth protege todas as rotas automaticamente?\n

Não. O NextAuth oferece a base da autenticação, mas cada rota precisa utilizar a sessão e as regras de autorização. O Middleware pode bloquear acessos antecipadamente, enquanto páginas, APIs e Server Actions devem confirmar a sessão no servidor.

Qual é a diferença entre 401 e 403 em uma API protegida?\n

O status 401 indica que a requisição não possui autenticação válida ou a sessão expirou. O status 403 indica que a pessoa foi identificada, mas não tem permissão para acessar o recurso ou executar a ação.

O TypeScript impede que alguém acesse uma rota sem permissão?\n

Não. O TypeScript verifica tipos durante o desenvolvimento, mas não controla as permissões em tempo de execução. Ele ajuda a evitar erros de código, enquanto a autenticação e a autorização precisam ser implementadas com verificações no servidor.

É necessário usar o Middleware em todas as aplicações Next.js?\n

Não é obrigatório. O Middleware melhora a navegação e evita.processar redirecionamentos. Mesmo assim, a rota que executa a operação deve fazer sua própria validação de sessão e permissão.

Como revogar o acesso de um usuário que perdeu o perfil?\n

A estratégia depende da aplicação. É possível atualizar o registro do usuário, invalidar sessões no banco, incluir o papel na sessão e consultá-lo em operações sensíveis, ou remover o token de atualização da estratégia de sessão. A resposta 403 precisa ter um comportamento previsível.

O NextAuth ainda é chamado Auth.js?

Sim. O projeto Auth.js é a evolução do NextAuth e passou a ser conhecido por essa marca. Ao seguir a documentação, confirme a versão instalada e use o guia compatível com o pacote e com o modo de roteamento utilizado no projeto.

Conclusão

Proteger rotas com NextAuth e TypeScript exige mais do que adicionar um botão de login. É preciso validar a sessão no servidor, diferenciar autenticação de autorização, conferir o papel e a relação do usuário com cada recurso, além de testar os caminhos de acesso sem permissão.

O Middleware pode agir como uma primeira barreira e melhorar a experiência de navegação. As páginas, Route Handlers e Server Actions, porém, devem preservar suas próprias verificações, porque elas são o ponto em que dados são lidos ou alterados. O TypeScript contribui ao tornar contratos e estados mais claros, mas a segurança depende das regras implementadas no servidor.

Uma implementação segura também considera segredos, cookies, validação de entrada, logs, privacidade e revogação de acesso. Com essa base, é possível criar áreas restritas sem confundir sessão válida com permissão automática.

Se você precisa de ajuda para colocar isso em prática, a Baita Site tem uma equipe especializada em sites, e-commerce, sistemas e inteligência artificial, com domínio total de WordPress. Fale com a gente e veja como podemos acelerar o seu projeto.

Referências consultadas

Documentação oficial do Next.js sobre Authentication, referência para middleware, Route Handlers, Server Actions e proteção de rotas no App Router. Documentação oficial do Auth.js sobre Next.js, referência para instalação, configuração e integração do Auth.js com projetos Next.js. Documentação oficial do Next.js sobre Middleware, referência para matchers, execução anterior às rotas e boas práticas de configuração. Documentação oficial do Next.js sobre Route Handlers, referência para criação de endpoints HTTP e tratamento de requisições no App Router. Documentação oficial do Next.js sobre Server Actions, referência para mutations executadas no servidor eoggles considerações de segurança.