Next.js Authentication Patterns

Next.js Authentication Patterns

Implement authentication with session handling, middleware guards, and Auth.js integration

When to Use

• Protecting pages and API routes from unauthenticated access
• Implementing login, logout, and session refresh flows
• Reading the current user in Server Components and Route Handlers
• Setting up role-based access control (RBAC) at the middleware level
• Integrating OAuth providers (Google, GitHub) or credential-based auth

Instructions

1. Use Auth.js (formerly NextAuth.js) v5 for a batteries-included auth layer — it handles OAuth, JWTs, sessions, and CSRF.
2. Create auth.ts at the project root to configure providers, callbacks, and session strategy.
3. Protect routes in middleware.ts using the Auth.js auth export — redirect unauthenticated users before the page renders.
4. Access the session in Server Components with auth() — never trust client-supplied user data.
5. Access the session in Client Components with useSession() from next-auth/react — wrap the app in <SessionProvider> in a Client Component layout wrapper.
6. Use signIn() and signOut() from next-auth/react in Client Components, or call them from Server Actions for progressive enhancement.
7. Validate authorization (role checks) in Route Handlers and Server Actions — middleware only covers page routes by default.
8. Store sensitive user attributes (roles, permissions) in the JWT callback and expose them through the session callback — never rely solely on client state.

// auth.ts — Auth.js v5 configuration
import NextAuth from 'next-auth';
import GitHub from 'next-auth/providers/github';

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [GitHub],
  callbacks: {
    async jwt({ token, user }) {
      if (user) token.role = user.role; // persist role in JWT
      return token;
    },
    async session({ session, token }) {
      session.user.role = token.role as string; // expose in session
      return session;
    },
  },
});

// middleware.ts — route protection
export { auth as middleware } from '@/auth';

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

// app/dashboard/page.tsx — server-side session access
import { auth } from '@/auth';
import { redirect } from 'next/navigation';

export default async function DashboardPage() {
  const session = await auth();
  if (!session) redirect('/login');
  if (session.user.role !== 'admin') redirect('/unauthorized');
  return <Dashboard user={session.user} />;
}

Details

Auth.js v5 is designed for the App Router and provides auth() as both a middleware function and a server-side session accessor. The same function works in middleware, Server Components, Route Handlers, and Server Actions.

Session strategies: Auth.js supports JWT sessions (stateless, stored in cookies) and database sessions (stateful, stored in your database). JWT is simpler to deploy; database sessions allow true session revocation. Use database sessions when you need to invalidate sessions on logout or role changes.

Middleware guard scope: The Auth.js middleware auth export only protects routes matched by config.matcher. API Route Handlers and Server Actions are not automatically protected — always call auth() and check the session inside them independently.

Role-based access: Store roles in the JWT payload via the jwt callback. The JWT is signed and cannot be tampered with client-side. Read session.user.role in Server Components to make authorization decisions. Never read roles from URL parameters or request bodies for authorization.

OAuth callback URL: OAuth providers require registering the callback URL: https://yourdomain.com/api/auth/callback/github. In development, use http://localhost:3000/api/auth/callback/github. Auth.js handles the callback route via the handlers export mounted at app/api/auth/[...nextauth]/route.ts.

PKCE and security: Auth.js automatically uses PKCE for OAuth flows and includes CSRF protection for credential login. Do not re-implement these manually.

Source

https://nextjs.org/docs/app/building-your-application/authentication

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.