Next.js Authentication

Overview

This skill provides comprehensive authentication patterns for Next.js 15+ applications using the App Router architecture and Auth.js 5. It covers the complete authentication lifecycle from initial setup to production-ready implementations with role-based access control.

Key capabilities include:

• Auth.js 5 setup with Next.js App Router

• Protected routes using Middleware

• Session management in Server Components

• Authentication checks in Server Actions

• OAuth provider integration (GitHub, Google, etc.)

• Role-based access control (RBAC)

• JWT and database session strategies

• Comprehensive testing patterns

When to Use

Use this skill when implementing authentication for Next.js 15+ with App Router:

• Setting up Auth.js 5 (NextAuth.js) from scratch

• Implementing protected routes with Middleware

• Handling authentication in Server Components

• Securing Server Actions with auth checks

• Configuring OAuth providers (Google, GitHub, Discord, etc.)

• Implementing role-based access control (RBAC)

• Managing sessions with JWT or database strategy

• Creating credential-based authentication

• Handling sign-in/sign-out flows

• Testing authentication flows

Instructions

1. Install Dependencies

Install Auth.js v5 (beta) for Next.js App Router:

npm install next-auth@beta

2. Configure Environment Variables

Create .env.local with required variables:

Required for Auth.js

AUTH_SECRET="your-secret-key-here" AUTH_URL="http://localhost:3000"

OAuth Providers (add as needed)

GITHUB_ID="your-github-client-id" GITHUB_SECRET="your-github-client-secret" GOOGLE_CLIENT_ID="your-google-client-id" GOOGLE_CLIENT_SECRET="your-google-client-secret"

Generate AUTH_SECRET with:

openssl rand -base64 32

3. Create Auth Configuration

Create auth.ts in the project root with providers and callbacks:

import NextAuth from "next-auth"; import GitHub from "next-auth/providers/github"; import Google from "next-auth/providers/google";

export const { handlers: { GET, POST }, auth, signIn, signOut, } = NextAuth({ providers: [ GitHub({ clientId: process.env.GITHUB_ID!, clientSecret: process.env.GITHUB_SECRET!, }), Google({ clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }), ], callbacks: { async jwt({ token, user }) { if (user) { token.id = user.id; } return token; }, async session({ session, token }) { if (token) { session.user.id = token.id as string; } return session; }, }, pages: { signIn: "/login", error: "/error", }, });

4. Create API Route Handler

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

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

5. Add Middleware for Route Protection

Create middleware.ts in the project root:

import { auth } from "@/auth"; import { NextResponse } from "next/server";

export default auth((req) => { const { nextUrl } = req; const isLoggedIn = !!req.auth; const isApiAuthRoute = nextUrl.pathname.startsWith("/api/auth"); const isPublicRoute = ["/", "/login", "/register"].includes(nextUrl.pathname); const isProtectedRoute = nextUrl.pathname.startsWith("/dashboard");

if (isApiAuthRoute) return NextResponse.next();

if (!isLoggedIn && isProtectedRoute) { return NextResponse.redirect(new URL("/login", nextUrl)); }

if (isLoggedIn && nextUrl.pathname === "/login") { return NextResponse.redirect(new URL("/dashboard", nextUrl)); }

return NextResponse.next(); });

export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico|.\.png$).)"], };

6. Access Session in Server Components

Use the auth() function to access session in Server Components:

import { auth } from "@/auth"; import { redirect } from "next/navigation";

export default async function DashboardPage() { const session = await auth();

if (!session) { redirect("/login"); }

return ( <div> <h1>Welcome, {session.user.name}</h1> </div> ); }

7. Secure Server Actions

Always verify authentication in Server Actions before mutations:

"use server";

import { auth } from "@/auth";

export async function createTodo(formData: FormData) { const session = await auth();

if (!session?.user) { throw new Error("Unauthorized"); }

// Proceed with protected action const title = formData.get("title") as string; await db.todo.create({ data: { title, userId: session.user.id }, }); }

8. Handle Sign-In/Sign-Out

Create a login page with server action:

// app/login/page.tsx import { signIn } from "@/auth"; import { redirect } from "next/navigation";

export default function LoginPage() { async function handleLogin(formData: FormData) { "use server";

const result = await signIn("credentials", {
  email: formData.get("email"),
  password: formData.get("password"),
  redirect: false,
});

if (result?.error) {
  return { error: "Invalid credentials" };
}

redirect("/dashboard");

}

return ( <form action={handleLogin}> <input name="email" type="email" placeholder="Email" required /> <input name="password" type="password" placeholder="Password" required /> <button type="submit">Sign In</button> </form> ); }

For client-side sign-out:

"use client";

import { signOut } from "next-auth/react";

export function SignOutButton() { return <button onClick={() => signOut()}>Sign Out</button>; }

9. Implement Role-Based Access

Check roles in Server Components:

import { auth } from "@/auth"; import { unauthorized } from "next/navigation";

export default async function AdminPage() { const session = await auth();

if (session?.user?.role !== "admin") { unauthorized(); }

return <AdminDashboard />; }

10. Extend TypeScript Types

Create types/next-auth.d.ts for type-safe sessions:

import { DefaultSession } from "next-auth";

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

interface User { role?: "user" | "admin"; } }

declare module "next-auth/jwt" { interface JWT { id?: string; role?: "user" | "admin"; } }

Examples

Example 1: Complete Protected Dashboard

Input: User needs a dashboard accessible only to authenticated users

Implementation:

// app/dashboard/page.tsx import { auth } from "@/auth"; import { redirect } from "next/navigation"; import { getUserTodos } from "@/app/lib/data";

export default async function DashboardPage() { const session = await auth();

if (!session?.user?.id) { redirect("/login"); }

const todos = await getUserTodos(session.user.id);

return ( <main> <h1>Welcome, {session.user.name}</h1> <p>Email: {session.user.email}</p> <TodoList todos={todos} /> </main> ); }

Output: Dashboard renders only for authenticated users, with their specific data.

Example 2: Role-Based Admin Panel

Input: Admin panel should be accessible only to users with "admin" role

Implementation:

// app/admin/page.tsx import { auth } from "@/auth"; import { unauthorized } from "next/navigation";

export default async function AdminPage() { const session = await auth();

if (session?.user?.role !== "admin") { unauthorized(); }

return ( <main> <h1>Admin Panel</h1> <p>Welcome, administrator {session.user.name}</p> </main> ); }

Output: Only admin users see the panel; others get 401 error.

Example 3: Secure Server Action with Form

Input: Form submission should only work for authenticated users

Implementation:

// app/components/create-todo-form.tsx "use server";

import { auth } from "@/auth"; import { revalidatePath } from "next/cache";

export async function createTodo(formData: FormData) { const session = await auth();

if (!session?.user?.id) { throw new Error("Unauthorized"); }

const title = formData.get("title") as string;

await db.todo.create({ data: { title, userId: session.user.id, }, });

revalidatePath("/dashboard"); }

// Usage in component export function CreateTodoForm() { return ( <form action={createTodo}> <input name="title" placeholder="New todo..." required /> <button type="submit">Add Todo</button> </form> ); }

Output: Todo created only for authenticated user; unauthorized requests throw error.

Example 4: OAuth Sign-In Button

Input: User should be able to sign in with GitHub

Implementation:

// components/auth/sign-in-button.tsx "use client";

import { signIn, signOut, useSession } from "next-auth/react";

export function AuthButton() { const { data: session, status } = useSession();

if (status === "loading") { return <button disabled>Loading...</button>; }

if (session) { return ( <button onClick={() => signOut()}> Sign out {session.user?.name} </button> ); }

return ( <button onClick={() => signIn("github")}> Sign in with GitHub </button> ); }

Output: Button shows "Sign in with GitHub" for unauthenticated users, "Sign out {name}" for authenticated users.

Example 5: Credentials Provider Login

Input: Implement email/password login

Implementation:

// auth.ts import Credentials from "next-auth/providers/credentials"; import bcrypt from "bcryptjs";

export const { handlers, auth, signIn, signOut } = NextAuth({ providers: [ Credentials({ name: "credentials", credentials: { email: { label: "Email", type: "email" }, password: { label: "Password", type: "password" }, }, async authorize(credentials) { if (!credentials?.email || !credentials?.password) { return null; }

    const user = await db.user.findUnique({
      where: { email: credentials.email },
    });

    if (!user || !user.password) {
      return null;
    }

    const isValid = await bcrypt.compare(
      credentials.password,
      user.password
    );

    return isValid
      ? { id: user.id, email: user.email, name: user.name }
      : null;
  },
}),

], });

Output: Users can authenticate with email/password against your database.

Best Practices

• Use Server Components by default - Access session directly without client-side JavaScript

• Minimize Client Components - Only use useSession() for reactive session updates

• Cache session checks - Use React's cache() for repeated lookups in the same render

• Middleware for optimistic checks - Redirect quickly, but always re-verify in Server Actions

• Treat Server Actions like API endpoints - Always authenticate before mutations

• Never hardcode secrets - Use environment variables for all credentials

• Implement proper error handling - Return appropriate HTTP status codes

• Use TypeScript type extensions - Extend NextAuth types for custom fields

• Separate auth logic - Create a DAL (Data Access Layer) for consistent checks

• Test authentication flows - Mock auth() function in unit tests

Constraints and Warnings

Critical Limitations

• Middleware runs on Edge runtime - Cannot use Node.js APIs like database drivers

• Server Components cannot set cookies - Use Server Actions for cookie operations

• Session callback timing - Only called on session creation/access, not every request

Common Mistakes

// ❌ WRONG: Setting cookies in Server Component export default async function Page() { cookies().set("key", "value"); // Won't work }

// ✅ CORRECT: Use Server Action async function setCookieAction() { "use server"; cookies().set("key", "value"); }

// ❌ WRONG: Database queries in Middleware export default auth(async (req) => { const user = await db.user.findUnique(); // Won't work in Edge });

// ✅ CORRECT: Use only Edge-compatible APIs export default auth(async (req) => { const session = req.auth; // This works });

Security Considerations

• Always verify authentication in Server Actions - middleware alone is not enough

• Use unauthorized() for unauthenticated access, redirect() for other cases

• Store sensitive tokens in httpOnly cookies

• Validate all user input before processing

• Use HTTPS in production

• Set appropriate cookie sameSite attributes

References

• references/authjs-setup.md - Complete Auth.js 5 setup guide with Prisma/Drizzle adapters

• references/oauth-providers.md - Provider-specific configurations (GitHub, Google, Discord, Auth0, etc.)

• references/database-adapter.md - Database session management with Prisma, Drizzle, and custom adapters

• references/testing-patterns.md - Testing authentication flows with Vitest and Playwright