Stop 12 · AuthenticationTopics · 6/10

NextAuth

In short

Writing OAuth, sessions and CSRF protection yourself takes weeks. NextAuth (now called Auth.js) gives a Next.js app all of it in a few files, using providers you plug in.

A complete authentication library for Next.js (now Auth.js) supporting OAuth providers, credentials, JWT and database sessions with minimal setup.

The jaadu plugs differently shaped chargers into one universal travel adapter.

Think of it like this

A universal travel adapter

One adapter, and your charger fits sockets in any country. Auth.js is that adapter: Google, GitHub, Discord or email login all plug into the same session and the same auth() call in your app.

Watch it happen

What auth() does on a protected page

Browser

Dashboard

Auth.js

GET /dashboard + cookie

1/5The browser asks for the page and sends the authjs session cookie.

The big ideas

What you need to know

One config file

auth.ts lists your providers and exports handlers, auth, signIn and signOut. Everything else imports from there.

Sessions in cookies

By default the session is an encrypted JWT stored in an HttpOnly cookie. Add a database adapter for database sessions.

AUTH_SECRET is required

It encrypts the session cookie. Generate it with npx auth secret and never commit it.

auth() works everywhere server-side

Call it in Server Components, route handlers, server actions and the proxy file to get the current session.

See it in code

Walk through the code

tsx

1// auth.ts2import NextAuth from "next-auth";3import GitHub from "next-auth/providers/github";4export const { handlers, auth, signIn, signOut } = NextAuth({ providers: [GitHub] });5 6// app/api/auth/[...nextauth]/route.ts7import { handlers } from "@/auth";8export const { GET, POST } = handlers;9 10// app/dashboard/page.tsx11import { auth } from "@/auth";12export default async function Dashboard() {13  const session = await auth();14  if (!session) return <p>Please log in</p>;15  return <p>Hi {session.user?.name}</p>;16}

1/3auth.ts sets up Auth.js with GitHub and exports four helpers you import everywhere.

That's a full GitHub login. Auth.js reads AUTH_GITHUB_ID, AUTH_GITHUB_SECRET and AUTH_SECRET from your env file automatically.

Save yourself the pain

Common mistakes

Oops

Following a v4 tutorial with getServerSession and authOptions on a v5 project.

Do this instead

v5 uses a single auth() function. Check which version you installed before copying code.

Oops

Hiding a page only with useSession on the client.

Do this instead

Check auth() on the server too, so the protected data never gets sent to a logged-out user.

Your mission

Add login to your Next.js portfolio

~35 min

Quick check

Where does Auth.js keep the session by default when you don't add a database adapter?

Go deeper

1Add NextAuth to a Next.js project with one OAuth provider (Google or GitHub).
2Learn the difference between JWT sessions and database sessions in NextAuth's config.
3Protect a route using NextAuth's session data in middleware or a server component.