Next.js + Auth.js v5

Adicione autenticação a um app Next.js 15 com Auth.js v5 (anteriormente NextAuth), incluindo OAuth do GitHub e proteção de rotas baseada em sessão.

Receita

1. Instale o Auth.js v5 beta:

   npm install next-auth@beta

2. Gere um segredo e adicione-o a .env.local:

   npx auth secret

3. Crie auth.ts na raiz do projeto exportando handlers configurados, auth, signIn, e signOut.
4. Crie o manipulador de rota em app/api/auth/[...nextauth]/route.ts que reexporta os handlers.
5. Adicione credenciais OAuth (ex: AUTH_GITHUB_ID, AUTH_GITHUB_SECRET) a .env.local.
6. Crie middleware.ts que usa a exportação auth para proteger rotas.

Exemplo de Trabalho

.env.local

AUTH_SECRET=<string de 32+ caracteres de `npx auth secret`>
AUTH_GITHUB_ID=<id do cliente da app oauth do github>
AUTH_GITHUB_SECRET=<segredo do cliente da app oauth do github>

auth.ts (raiz do projeto)

import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
 
export const \{ handlers, auth, signIn, signOut \} = NextAuth(\{
  providers: [GitHub],
  session: \{ strategy: "jwt" \},
  callbacks: \{
    authorized: async (\{ auth \}) => !!auth,
  \},
\});

app/api/auth/[...nextauth]/route.ts

export \{ GET, POST \} from "@/auth";

Espere - na v5 você exporta do objeto handlers em vez disso:

import \{ handlers \} from "@/auth";
export const \{ GET, POST \} = handlers;

middleware.ts

export \{ auth as middleware \} from "@/auth";
 
export const config = \{
  matcher: ["/dashboard/:path*"],
\};

app/dashboard/page.tsx

import \{ auth, signOut \} from "@/auth";
 
export default async function DashboardPage() \{
  const session = await auth();
 
  return (
    <main className="mx-auto max-w-xl p-8">
      <h1 className="text-2xl font-bold">Dashboard</h1>
      <p className="mt-4">Bem-vindo, \{session?.user?.name\}</p>
 
      <form
        action=\{async () => \{
          "use server";
          await signOut();
        \}\}
      >
        <button type="submit" className="mt-4 rounded bg-black px-4 py-2 text-white">
          Sair
        </button>
      </form>
    </main>
  );
\}

app/page.tsx (botão de login)

import \{ auth, signIn \} from "@/auth";
 
export default async function Home() \{
  const session = await auth();
 
  if (session?.user) \{
    return <a href="/dashboard">Ir para o dashboard</a>;
  \}
 
  return (
    <form
      action=\{async () => \{
        "use server";
        await signIn("github", \{ redirectTo: "/dashboard" \});
      \}\}
    >
      <button type="submit">Entrar com GitHub</button>
    </form>
  );
\}

Análise Detalhada

Como Funciona

O Auth.js v5 centraliza a configuração em um único arquivo auth.ts na raiz, que exporta todas as funções que você precisa em outros lugares. A função auth() é isomórfica - ela lê a sessão dos cookies em Server Components, Server Actions, Route Handlers e middleware. A importação de middleware export \{ auth as middleware \} transforma o Auth.js em um guard ciente de matchers que redireciona usuários não autenticados para a página de login.

Por baixo dos panos, o Auth.js define um cookie JWT assinado e criptografado por padrão (session.strategy: "jwt"). Você pode mudar para sessões de banco de dados adicionando um adaptador Prisma/Drizzle.

Variações

• Múltiplos provedores: adicione Google, Credentials, Email, etc. ao array providers.
• Sessões de banco de dados: instale @auth/prisma-adapter, passe adapter: PrismaAdapter(prisma), e defina session: \{ strategy: "database" \}.
• Página de login customizada: defina pages: \{ signIn: "/login" \} na configuração do NextAuth e crie sua própria página /login que chama signIn().
• Acesso baseado em roles: modifique a sessão nas callbacks jwt e session para incluir um claim de role, e então verifique-o no middleware ou em Server Components.
• auth() em RSC vs useSession() no cliente: código do servidor usa await auth(); código do cliente envolve o app com <SessionProvider> e chama useSession().
• Middleware compatível com Edge: mantenha auth.config.ts livre de adaptadores Node-only e importe apenas a configuração leve no middleware.

Notas TypeScript

Estenda a interface Session usando module augmentation para que seus claims customizados sejam tipados em todos os lugares:

// types/next-auth.d.ts
import \{ DefaultSession \} from "next-auth";
 
declare module "next-auth" \{
  interface Session \{
    user: \{
      id: string;
      role: "admin" | "user";
    \} & DefaultSession["user"];
  \}
\}

Após isso, session.user.role será fortemente tipado em todos os lugares onde você chamar auth().

Armadilhas

1. AUTH_SECRET deve ser longo o suficiente. O Auth.js v5 requer 32+ caracteres. Gere com npx auth secret - não digite um manualmente.
2. O middleware roda no runtime Edge. Você não pode usar APIs do Node.js (fs, crypto.randomBytes na forma legada, drivers de banco de dados). Mantenha lógica pesada fora de middleware.ts.
3. Matcher exclui assets estáticos. O matcher padrão pode corresponder a /_next/static e imagens se você não for cuidadoso. Use um negative lookahead como /((?!api|_next/static|_next/image|favicon.ico).*).
4. Limites de armazenamento da estratégia de sessão. Sessões JWT são stateless, rápidas, e o padrão - perfeitas para a maioria dos apps. Sessões de banco de dados requerem um adaptador, mas oferecem revogação instantânea, armazenamento maior e listagem fácil de sessões entre dispositivos. Escolha sessões de banco de dados para apps com recursos de logout-de-todos-os-lugares ou kick-user pelo admin.
5. Incompatibilidade de URL de callback OAuth. Apps OAuth do GitHub/Google devem listar a URL de callback exata, ex: https://yourapp.com/api/auth/callback/github. Uma barra final ou protocolo errado quebra o login com um erro vago.
6. URLs de callback de desenvolvimento vs produção. Normalmente você precisa de duas apps OAuth (ou duas URLs de callback) - uma para http://localhost:3000 e outra para produção.
7. auth.ts na raiz do projeto, não em app/. Colocá-lo dentro de app/ faz o Next.js tratá-lo como uma rota. Mantenha-o na raiz do projeto ou sob lib/ e use alias conforme necessário.

Alternativas

FAQs

import \{ auth \} from "@/auth";
 
const session = await auth();
if (!session?.user) redirect("/login");

callbacks: \{
  async jwt(\{ token, user \}) \{
    if (user) token.role = user.role;
    return token;
  \},
  async session(\{ session, token \}) \{
    session.user.role = token.role as "admin" | "user";
    return session;
  \},
\}

declare module "next-auth" \{
  interface Session \{
    user: \{ id: string; role: string \} & DefaultSession["user"];
  \}
\}

const session = await auth();
if (!session?.user) redirect("/login");

<form action=\{async () => \{ "use server"; await signOut(); \}\}>
  <button type="submit">Sair</button>
</form>

Relacionados

• Padrões Next.js: Autenticação
• Padrões Next.js: Variáveis de Ambiente
• Dados Next.js: Cookies e Headers
• Configuração Next.js: Prisma + PostgreSQL