NextAuth.js / Auth.js v5 - Autenticação para Next.js App Router com provedores, sessões e middleware

Q: O que a função auth() retorna e onde posso chamá-la?

Retorna Session | null contendo informações do usuário e expiração Pode ser chamada em Server Components, Server Actions, rotas de API e middleware Não pode ser chamada em componentes cliente - use useSession() de next-auth/react em vez disso Sempre verifique se é null antes de acessar session.user

Q: Como funciona o fluxo OAuth com Auth.js v5 e Next.js?

1. O usuário clica em "entrar", a ação do formulário chama signIn("github") 2. Next.js redireciona para a página de autorização do provedor OAuth 3. O usuário concede permissão, o provedor redireciona de volta com um código 4. Auth.js troca o código por tokens e cria uma sessão JWT 5. O cookie de sessão é definido e as chamadas subsequentes a auth() retornam a sessão

Q: Armadilha: Por que meu aplicativo trava em produção com "AUTH_SECRET is missing"?

AUTH_SECRET é necessário para assinar JWTs em produção Gere-o com npx auth secret e adicione às suas variáveis de ambiente Deve ter pelo menos 32 caracteres Em desenvolvimento, Auth.js gera um segredo temporário automaticamente

Q: Como protejo rotas com middleware?

Sempre defina config.matcher para limitar o middleware a caminhos protegidos.

Q: Como acesso a sessão em um componente cliente?

Envolva seu layout com de next-auth/react Use o hook useSession() em componentes cliente useSession() retorna { data: session, status } onde status é "loading", "authenticated", ou "unauthenticated"

Q: Como adiciono um provedor Credentials para login com email/senha?

Importe Credentials de next-auth/providers/credentials Defina os campos credentials e uma função authorize A função authorize valida as credenciais e retorna um objeto de usuário ou null O provedor Credentials suporta apenas sessões JWT, não sessões de banco de dados

Q: Como estendo a sessão com campos personalizados como role?

Também estenda o tipo Session através de aumento de módulo em types/next-auth.d.ts.

Q: Como faço o type-extend da interface Session em TypeScript?

Isso adiciona id e role a session.user em todo o seu aplicativo.

Q: Armadilha: Por que auth() retorna null no meu componente cliente?

auth() é uma função apenas do servidor e não pode ser chamada em componentes cliente Use e o hook useSession() para acesso à sessão no lado do cliente Certifique-se de que SessionProvider envolva a árvore de componentes em seu layout

Q: Como configuro um adaptador de banco de dados Prisma para sessões persistentes?

Instale @auth/prisma-adapter e defina session.strategy como "database".

Receita

npm install next-auth@beta

// auth.ts (raiz do projeto)
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    GitHub({
      clientId: process.env.AUTH_GITHUB_ID!,
      clientSecret: process.env.AUTH_GITHUB_SECRET!,
    }),
    Google({
      clientId: process.env.AUTH_GOOGLE_ID!,
      clientSecret: process.env.AUTH_GOOGLE_SECRET!,
    }),
  ],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
 
export const { GET, POST } = handlers;

// .env.local
AUTH_SECRET=your-random-secret-at-least-32-chars
AUTH_GITHUB_ID=...
AUTH_GITHUB_SECRET=...
AUTH_GOOGLE_ID=...
AUTH_GOOGLE_SECRET=...

Quando usar isso: Você precisa de login OAuth (GitHub, Google, etc.), gerenciamento de sessão e proteção de rotas em uma aplicação Next.js App Router.

Exemplo de Trabalho

// app/components/AuthButtons.tsx
import { auth, signIn, signOut } from "@/auth";
 
export async function SignInButton() {
  const session = await auth();
 
  if (session?.user) {
    return (
      <div className="flex items-center gap-3">
        {session.user.image && (
          <img
            src={session.user.image}
            alt=""
            className="w-8 h-8 rounded-full"
          />
        )}
        <span className="text-sm">{session.user.name}</span>
        <form
          action={async () => {
            "use server";
            await signOut();
          }}
        >
          <button className="text-sm text-gray-500 hover:text-gray-700">
            Sair
          </button>
        </form>
      </div>
    );
  }
 
  return (
    <div className="flex gap-2">
      <form
        action={async () => {
          "use server";
          await signIn("github");
        }}
      >
        <button className="bg-gray-900 text-white px-4 py-2 rounded text-sm">
          Entrar com GitHub
        </button>
      </form>
      <form
        action={async () => {
          "use server";
          await signIn("google");
        }}
      >
        <button className="bg-blue-600 text-white px-4 py-2 rounded text-sm">
          Entrar com Google
        </button>
      </form>
    </div>
  );
}

// app/dashboard/page.tsx
import { auth } from "@/auth";
import { redirect } from "next/navigation";
 
export default async function DashboardPage() {
  const session = await auth();
 
  if (!session) {
    redirect("/api/auth/signin");
  }
 
  return (
    <div className="max-w-2xl mx-auto p-6">
      <h1 className="text-2xl font-bold">Dashboard</h1>
      <p className="mt-2">Bem-vindo, {session.user?.name}!</p>
      <pre className="mt-4 bg-gray-100 p-4 rounded text-sm">
        {JSON.stringify(session, null, 2)}
      </pre>
    </div>
  );
}

// middleware.ts
import { auth } from "./auth";
 
export default auth((req) => {
  const isLoggedIn = !!req.auth;
  const isProtected = req.nextUrl.pathname.startsWith("/dashboard");
 
  if (isProtected && !isLoggedIn) {
    return Response.redirect(new URL("/api/auth/signin", req.nextUrl));
  }
});
 
export const config = {
  matcher: ["/dashboard/:path*", "/settings/:path*"],
};

O que isso demonstra:

Configuração do Auth.js v5 com provedores GitHub e Google
Acesso à sessão em Server Components com auth()
Formulários de entrada/saída em Server Actions
Páginas protegidas com redirecionamento
Proteção de rotas baseada em middleware

Mergulho Profundo

Como Funciona

Auth.js v5 exporta auth(), signIn(), signOut() e handlers de uma única configuração
auth() retorna a sessão atual em Server Components, Server Actions, rotas de API e middleware
Sessões são baseadas em JWT por padrão (sem necessidade de banco de dados); adicione um adaptador de banco de dados para sessões persistentes
A exportação handlers fornece manipuladores de rota GET e POST para a rota catch-all /api/auth/[...nextauth]
Fluxo OAuth: o usuário clica em "entrar", redireciona para o provedor, o provedor redireciona de volta com um código, Auth.js troca o código por tokens e cria uma sessão
AUTH_SECRET é necessário em produção para assinar JWTs; gere com npx auth secret

Variações

Provedor de Credenciais (email/senha):

import Credentials from "next-auth/providers/credentials";
import { z } from "zod";
import bcrypt from "bcryptjs";
import { prisma } from "@/lib/prisma";
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    Credentials({
      credentials: {
        email: { label: "Email", type: "email" },
        password: { label: "Password", type: "password" },
      },
      authorize: async (credentials) => {
        const parsed = z
          .object({
            email: z.string().email(),
            password: z.string().min(8),
          })
          .safeParse(credentials);
 
        if (!parsed.success) return null;
 
        const user = await prisma.user.findUnique({
          where: { email: parsed.data.email },
        });
 
        if (!user || !user.password) return null;
 
        const valid = await bcrypt.compare(parsed.data.password, user.password);
        if (!valid) return null;
 
        return { id: String(user.id), name: user.name, email: user.email };
      },
    }),
  ],
});

Adaptador de banco de dados Prisma:

npm install @auth/prisma-adapter

import { PrismaAdapter } from "@auth/prisma-adapter";
import { prisma } from "@/lib/prisma";
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [GitHub, Google],
  session: { strategy: "database" }, // Use sessões de banco de dados em vez de JWT
});

Estendendo a sessão com campos personalizados:

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.role = user.role; // Adiciona role do usuário do banco de dados
      }
      return token;
    },
    async session({ session, token }) {
      session.user.id = token.sub!;
      session.user.role = token.role as string;
      return session;
    },
  },
});

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

Acesso à sessão no lado do cliente:

// app/providers.tsx
"use client";
import { SessionProvider } from "next-auth/react";
 
export function AuthProvider({ children }: { children: React.ReactNode }) {
  return <SessionProvider>{children}</SessionProvider>;
}
 
// app/components/ClientProfile.tsx
"use client";
import { useSession } from "next-auth/react";
 
export function ClientProfile() {
  const { data: session, status } = useSession();
 
  if (status === "loading") return <p>Carregando...</p>;
  if (!session) return <p>Não autenticado</p>;
 
  return <p>Autenticado como {session.user?.name}</p>;
}

Notas TypeScript

Estenda os tipos Session e JWT através de aumento de módulo em types/next-auth.d.ts
auth() retorna Session | null; sempre verifique se é nulo antes de acessar session.user
Tipos de perfil específicos do provedor estão disponíveis, mas raramente necessários
O tipo User pode ser estendido para campos de banco de dados personalizados

import type { Session } from "next-auth";
 
async function getUser(): Promise<Session["user"] | null> {
  const session = await auth();
  return session?.user ?? null;
}

Armadilhas

AUTH_SECRET ausente - O aplicativo trava em produção sem AUTH_SECRET. Correção: Gere-o com npx auth secret e adicione às suas variáveis de ambiente. Necessário para assinatura de JWT.
URL de callback incorreta - Provedores OAuth rejeitam redirecionamentos se a URL de callback não corresponder. Correção: Registre https://seudominio.com/api/auth/callback/github (e /google) nas configurações do desenvolvedor de cada provedor.
Sessão nula em componentes cliente - auth() só funciona no lado do servidor. Correção: Use SessionProvider e o hook useSession() para componentes cliente. Envolva seu layout com <SessionProvider>.
Middleware é executado em todas as requisições - Sem um matcher, o middleware de autenticação é executado em ativos estáticos, rotas de API, etc. Correção: Sempre configure config.matcher para limitar o middleware a caminhos protegidos.
Limitações do provedor Credentials - O provedor Credentials não suporta sessões de banco de dados prontas para uso (apenas JWT). Correção: Use a estratégia JWT com credenciais. Para sessões de banco de dados, use provedores OAuth com um adaptador de banco de dados.
Compatibilidade com o runtime Edge - Alguns adaptadores de banco de dados e bcrypt não funcionam no runtime Edge. Correção: Use bcryptjs em vez de bcrypt. Verifique a compatibilidade do adaptador com o Edge. Use runtime: "nodejs" no middleware, se necessário.
Migração de v4 para v5 - Auth.js v5 tem uma API significativamente diferente do NextAuth v4. Correção: Siga o guia de migração oficial. Mudanças importantes: NextAuth() exporta auth em vez de usar getServerSession(), e next-auth/react é apenas para componentes cliente.

Alternativas

Biblioteca	Melhor para	Contrapartida
Auth.js / NextAuth v5	Gerenciamento completo de OAuth + sessão para Next.js	Configuração complexa para fluxos personalizados
Clerk	Componentes de UI de autenticação prontos para uso	Serviço pago, dependência de fornecedor
Supabase Auth	Integração com o ecossistema Supabase	Vinculado ao Supabase
Lucia	Autenticação leve, DIY	Configuração mais manual, menos abstração
Kinde	Autenticação B2B com organizações	Serviço pago
JWT Personalizado	Controle total	Deve lidar com segurança, atualização, revogação você mesmo

FAQs

O que a função `auth()` retorna e onde posso chamá-la?

Retorna Session | null contendo informações do usuário e expiração
Pode ser chamada em Server Components, Server Actions, rotas de API e middleware
Não pode ser chamada em componentes cliente - use useSession() de next-auth/react em vez disso
Sempre verifique se é null antes de acessar session.user

Como funciona o fluxo OAuth com Auth.js v5 e Next.js?

O usuário clica em "entrar", a ação do formulário chama signIn("github")
Next.js redireciona para a página de autorização do provedor OAuth
O usuário concede permissão, o provedor redireciona de volta com um código
Auth.js troca o código por tokens e cria uma sessão JWT
O cookie de sessão é definido e as chamadas subsequentes a auth() retornam a sessão

Armadilha: Por que meu aplicativo trava em produção com "AUTH_SECRET is missing"?

AUTH_SECRET é necessário para assinar JWTs em produção
Gere-o com npx auth secret e adicione às suas variáveis de ambiente
Deve ter pelo menos 32 caracteres
Em desenvolvimento, Auth.js gera um segredo temporário automaticamente

Como protejo rotas com middleware?

// middleware.ts
import { auth } from "./auth";
 
export default auth((req) => {
  if (!req.auth && req.nextUrl.pathname.startsWith("/dashboard")) {
    return Response.redirect(new URL("/api/auth/signin", req.nextUrl));
  }
});
 
export const config = {
  matcher: ["/dashboard/:path*"],
};

Sempre defina config.matcher para limitar o middleware a caminhos protegidos.

Como acesso a sessão em um componente cliente?

Envolva seu layout com <SessionProvider> de next-auth/react
Use o hook useSession() em componentes cliente
useSession() retorna { data: session, status } onde status é "loading", "authenticated", ou "unauthenticated"

Como adiciono um provedor Credentials para login com email/senha?

Importe Credentials de next-auth/providers/credentials
Defina os campos credentials e uma função authorize
A função authorize valida as credenciais e retorna um objeto de usuário ou null
O provedor Credentials suporta apenas sessões JWT, não sessões de banco de dados

Como estendo a sessão com campos personalizados como `role`?

callbacks: {
  async jwt({ token, user }) {
    if (user) token.role = user.role;
    return token;
  },
  async session({ session, token }) {
    session.user.role = token.role as string;
    return session;
  },
}

Também estenda o tipo Session através de aumento de módulo em types/next-auth.d.ts.

Como faço o type-extend da interface Session em TypeScript?

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

Isso adiciona id e role a session.user em todo o seu aplicativo.

Armadilha: Por que `auth()` retorna null no meu componente cliente?

auth() é uma função apenas do servidor e não pode ser chamada em componentes cliente
Use <SessionProvider> e o hook useSession() para acesso à sessão no lado do cliente
Certifique-se de que SessionProvider envolva a árvore de componentes em seu layout

Como configuro um adaptador de banco de dados Prisma para sessões persistentes?

import { PrismaAdapter } from "@auth/prisma-adapter";
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  session: { strategy: "database" },
  providers: [GitHub, Google],
});

Instale @auth/prisma-adapter e defina session.strategy como "database".

Armadilha: Por que meu middleware é executado em todas as requisições, incluindo ativos estáticos?

Sem uma configuração matcher, o middleware é executado em todas as rotas, incluindo _next/static, imagens e rotas de API
Sempre configure config.matcher para limitá-lo a caminhos protegidos
Exemplo: matcher: ["/dashboard/:path*", "/settings/:path*"]

Quais são as principais diferenças entre NextAuth v4 e Auth.js v5?

v5 exporta auth() em vez de exigir getServerSession(authOptions)
v5 usa uma única chamada NextAuth() que retorna auth, signIn, signOut e handlers
next-auth/react (useSession, SessionProvider) é apenas para componentes cliente
O arquivo de configuração é tipicamente auth.ts na raiz do projeto

Relacionado

Prisma - Adaptador de banco de dados para sessões persistentes e armazenamento de usuários
Next.js Middleware - Padrões de proteção de rotas
Next.js Server Actions - Fluxos de entrada/saída no lado do servidor
TanStack Query - Busca de dados específicos do usuário após a autenticação

Receita

npm install next-auth@beta

// auth.ts (raiz do projeto)
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    GitHub({
      clientId: process.env.AUTH_GITHUB_ID!,
      clientSecret: process.env.AUTH_GITHUB_SECRET!,
    }),
    Google({
      clientId: process.env.AUTH_GOOGLE_ID!,
      clientSecret: process.env.AUTH_GOOGLE_SECRET!,
    }),
  ],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
 
export const { GET, POST } = handlers;

// .env.local
AUTH_SECRET=your-random-secret-at-least-32-chars
AUTH_GITHUB_ID=...
AUTH_GITHUB_SECRET=...
AUTH_GOOGLE_ID=...
AUTH_GOOGLE_SECRET=...

Quando usar isso: Você precisa de login OAuth (GitHub, Google, etc.), gerenciamento de sessão e proteção de rotas em uma aplicação Next.js App Router.

Exemplo de Trabalho

// app/components/AuthButtons.tsx
import { auth, signIn, signOut } from "@/auth";
 
export async function SignInButton() {
  const session = await auth();
 
  if (session?.user) {
    return (
      <div className="flex items-center gap-3">
        {session.user.image && (
          <img
            src={session.user.image}
            alt=""
            className="w-8 h-8 rounded-full"
          />
        )}
        <span className="text-sm">{session.user.name}</span>
        <form
          action={async () => {
            "use server";
            await signOut();
          }}
        >
          <button className="text-sm text-gray-500 hover:text-gray-700">
            Sair
          </button>
        </form>
      </div>
    );
  }
 
  return (
    <div className="flex gap-2">
      <form
        action={async () => {
          "use server";
          await signIn("github");
        }}
      >
        <button className="bg-gray-900 text-white px-4 py-2 rounded text-sm">
          Entrar com GitHub
        </button>
      </form>
      <form
        action={async () => {
          "use server";
          await signIn("google");
        }}
      >
        <button className="bg-blue-600 text-white px-4 py-2 rounded text-sm">
          Entrar com Google
        </button>
      </form>
    </div>
  );
}

// app/dashboard/page.tsx
import { auth } from "@/auth";
import { redirect } from "next/navigation";
 
export default async function DashboardPage() {
  const session = await auth();
 
  if (!session) {
    redirect("/api/auth/signin");
  }
 
  return (
    <div className="max-w-2xl mx-auto p-6">
      <h1 className="text-2xl font-bold">Dashboard</h1>
      <p className="mt-2">Bem-vindo, {session.user?.name}!</p>
      <pre className="mt-4 bg-gray-100 p-4 rounded text-sm">
        {JSON.stringify(session, null, 2)}
      </pre>
    </div>
  );
}

// middleware.ts
import { auth } from "./auth";
 
export default auth((req) => {
  const isLoggedIn = !!req.auth;
  const isProtected = req.nextUrl.pathname.startsWith("/dashboard");
 
  if (isProtected && !isLoggedIn) {
    return Response.redirect(new URL("/api/auth/signin", req.nextUrl));
  }
});
 
export const config = {
  matcher: ["/dashboard/:path*", "/settings/:path*"],
};

O que isso demonstra:

Configuração do Auth.js v5 com provedores GitHub e Google
Acesso à sessão em Server Components com auth()
Formulários de entrada/saída em Server Actions
Páginas protegidas com redirecionamento
Proteção de rotas baseada em middleware

Mergulho Profundo

Como Funciona

Auth.js v5 exporta auth(), signIn(), signOut() e handlers de uma única configuração
auth() retorna a sessão atual em Server Components, Server Actions, rotas de API e middleware
Sessões são baseadas em JWT por padrão (sem necessidade de banco de dados); adicione um adaptador de banco de dados para sessões persistentes
A exportação handlers fornece manipuladores de rota GET e POST para a rota catch-all /api/auth/[...nextauth]
Fluxo OAuth: o usuário clica em "entrar", redireciona para o provedor, o provedor redireciona de volta com um código, Auth.js troca o código por tokens e cria uma sessão
AUTH_SECRET é necessário em produção para assinar JWTs; gere com npx auth secret

Variações

Provedor de Credenciais (email/senha):

import Credentials from "next-auth/providers/credentials";
import { z } from "zod";
import bcrypt from "bcryptjs";
import { prisma } from "@/lib/prisma";
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    Credentials({
      credentials: {
        email: { label: "Email", type: "email" },
        password: { label: "Password", type: "password" },
      },
      authorize: async (credentials) => {
        const parsed = z
          .object({
            email: z.string().email(),
            password: z.string().min(8),
          })
          .safeParse(credentials);
 
        if (!parsed.success) return null;
 
        const user = await prisma.user.findUnique({
          where: { email: parsed.data.email },
        });
 
        if (!user || !user.password) return null;
 
        const valid = await bcrypt.compare(parsed.data.password, user.password);
        if (!valid) return null;
 
        return { id: String(user.id), name: user.name, email: user.email };
      },
    }),
  ],
});

Adaptador de banco de dados Prisma:

npm install @auth/prisma-adapter

import { PrismaAdapter } from "@auth/prisma-adapter";
import { prisma } from "@/lib/prisma";
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [GitHub, Google],
  session: { strategy: "database" }, // Use sessões de banco de dados em vez de JWT
});

Estendendo a sessão com campos personalizados:

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.role = user.role; // Adiciona role do usuário do banco de dados
      }
      return token;
    },
    async session({ session, token }) {
      session.user.id = token.sub!;
      session.user.role = token.role as string;
      return session;
    },
  },
});

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

Acesso à sessão no lado do cliente:

// app/providers.tsx
"use client";
import { SessionProvider } from "next-auth/react";
 
export function AuthProvider({ children }: { children: React.ReactNode }) {
  return <SessionProvider>{children}</SessionProvider>;
}
 
// app/components/ClientProfile.tsx
"use client";
import { useSession } from "next-auth/react";
 
export function ClientProfile() {
  const { data: session, status } = useSession();
 
  if (status === "loading") return <p>Carregando...</p>;
  if (!session) return <p>Não autenticado</p>;
 
  return <p>Autenticado como {session.user?.name}</p>;
}

Notas TypeScript

Estenda os tipos Session e JWT através de aumento de módulo em types/next-auth.d.ts
auth() retorna Session | null; sempre verifique se é nulo antes de acessar session.user
Tipos de perfil específicos do provedor estão disponíveis, mas raramente necessários
O tipo User pode ser estendido para campos de banco de dados personalizados

import type { Session } from "next-auth";
 
async function getUser(): Promise<Session["user"] | null> {
  const session = await auth();
  return session?.user ?? null;
}

Armadilhas

AUTH_SECRET ausente - O aplicativo trava em produção sem AUTH_SECRET. Correção: Gere-o com npx auth secret e adicione às suas variáveis de ambiente. Necessário para assinatura de JWT.
URL de callback incorreta - Provedores OAuth rejeitam redirecionamentos se a URL de callback não corresponder. Correção: Registre https://seudominio.com/api/auth/callback/github (e /google) nas configurações do desenvolvedor de cada provedor.
Sessão nula em componentes cliente - auth() só funciona no lado do servidor. Correção: Use SessionProvider e o hook useSession() para componentes cliente. Envolva seu layout com <SessionProvider>.
Middleware é executado em todas as requisições - Sem um matcher, o middleware de autenticação é executado em ativos estáticos, rotas de API, etc. Correção: Sempre configure config.matcher para limitar o middleware a caminhos protegidos.
Limitações do provedor Credentials - O provedor Credentials não suporta sessões de banco de dados prontas para uso (apenas JWT). Correção: Use a estratégia JWT com credenciais. Para sessões de banco de dados, use provedores OAuth com um adaptador de banco de dados.
Compatibilidade com o runtime Edge - Alguns adaptadores de banco de dados e bcrypt não funcionam no runtime Edge. Correção: Use bcryptjs em vez de bcrypt. Verifique a compatibilidade do adaptador com o Edge. Use runtime: "nodejs" no middleware, se necessário.
Migração de v4 para v5 - Auth.js v5 tem uma API significativamente diferente do NextAuth v4. Correção: Siga o guia de migração oficial. Mudanças importantes: NextAuth() exporta auth em vez de usar getServerSession(), e next-auth/react é apenas para componentes cliente.

Alternativas

Biblioteca	Melhor para	Contrapartida
Auth.js / NextAuth v5	Gerenciamento completo de OAuth + sessão para Next.js	Configuração complexa para fluxos personalizados
Clerk	Componentes de UI de autenticação prontos para uso	Serviço pago, dependência de fornecedor
Supabase Auth	Integração com o ecossistema Supabase	Vinculado ao Supabase
Lucia	Autenticação leve, DIY	Configuração mais manual, menos abstração
Kinde	Autenticação B2B com organizações	Serviço pago
JWT Personalizado	Controle total	Deve lidar com segurança, atualização, revogação você mesmo

FAQs

O que a função `auth()` retorna e onde posso chamá-la?

Retorna Session | null contendo informações do usuário e expiração
Pode ser chamada em Server Components, Server Actions, rotas de API e middleware
Não pode ser chamada em componentes cliente - use useSession() de next-auth/react em vez disso
Sempre verifique se é null antes de acessar session.user

Como funciona o fluxo OAuth com Auth.js v5 e Next.js?

O usuário clica em "entrar", a ação do formulário chama signIn("github")
Next.js redireciona para a página de autorização do provedor OAuth
O usuário concede permissão, o provedor redireciona de volta com um código
Auth.js troca o código por tokens e cria uma sessão JWT
O cookie de sessão é definido e as chamadas subsequentes a auth() retornam a sessão

Armadilha: Por que meu aplicativo trava em produção com "AUTH_SECRET is missing"?

AUTH_SECRET é necessário para assinar JWTs em produção
Gere-o com npx auth secret e adicione às suas variáveis de ambiente
Deve ter pelo menos 32 caracteres
Em desenvolvimento, Auth.js gera um segredo temporário automaticamente

Como protejo rotas com middleware?

// middleware.ts
import { auth } from "./auth";
 
export default auth((req) => {
  if (!req.auth && req.nextUrl.pathname.startsWith("/dashboard")) {
    return Response.redirect(new URL("/api/auth/signin", req.nextUrl));
  }
});
 
export const config = {
  matcher: ["/dashboard/:path*"],
};

Sempre defina config.matcher para limitar o middleware a caminhos protegidos.

Como acesso a sessão em um componente cliente?

Envolva seu layout com <SessionProvider> de next-auth/react
Use o hook useSession() em componentes cliente
useSession() retorna { data: session, status } onde status é "loading", "authenticated", ou "unauthenticated"

Como adiciono um provedor Credentials para login com email/senha?

Importe Credentials de next-auth/providers/credentials
Defina os campos credentials e uma função authorize
A função authorize valida as credenciais e retorna um objeto de usuário ou null
O provedor Credentials suporta apenas sessões JWT, não sessões de banco de dados

Como estendo a sessão com campos personalizados como `role`?

callbacks: {
  async jwt({ token, user }) {
    if (user) token.role = user.role;
    return token;
  },
  async session({ session, token }) {
    session.user.role = token.role as string;
    return session;
  },
}

Também estenda o tipo Session através de aumento de módulo em types/next-auth.d.ts.

Como faço o type-extend da interface Session em TypeScript?

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

Isso adiciona id e role a session.user em todo o seu aplicativo.

Armadilha: Por que `auth()` retorna null no meu componente cliente?

auth() é uma função apenas do servidor e não pode ser chamada em componentes cliente
Use <SessionProvider> e o hook useSession() para acesso à sessão no lado do cliente
Certifique-se de que SessionProvider envolva a árvore de componentes em seu layout

Como configuro um adaptador de banco de dados Prisma para sessões persistentes?

import { PrismaAdapter } from "@auth/prisma-adapter";
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  session: { strategy: "database" },
  providers: [GitHub, Google],
});

Instale @auth/prisma-adapter e defina session.strategy como "database".

Armadilha: Por que meu middleware é executado em todas as requisições, incluindo ativos estáticos?

Sem uma configuração matcher, o middleware é executado em todas as rotas, incluindo _next/static, imagens e rotas de API
Sempre configure config.matcher para limitá-lo a caminhos protegidos
Exemplo: matcher: ["/dashboard/:path*", "/settings/:path*"]

Quais são as principais diferenças entre NextAuth v4 e Auth.js v5?

v5 exporta auth() em vez de exigir getServerSession(authOptions)
v5 usa uma única chamada NextAuth() que retorna auth, signIn, signOut e handlers
next-auth/react (useSession, SessionProvider) é apenas para componentes cliente
O arquivo de configuração é tipicamente auth.ts na raiz do projeto

Relacionado

Prisma - Adaptador de banco de dados para sessões persistentes e armazenamento de usuários
Next.js Middleware - Padrões de proteção de rotas
Next.js Server Actions - Fluxos de entrada/saída no lado do servidor
TanStack Query - Busca de dados específicos do usuário após a autenticação

NextAuth.js / Auth.js v5 - Autenticação para Next.js App Router com provedores, sessões e middleware

Buscar na documentação

NextAuth.js / Auth.js v5 - Autenticação para Next.js App Router com provedores, sessões e middleware