pn-auth-patterns

Auth patterns

When to use

• Implementing authentication or authorisation for the first time in a project
• Choosing between session-based, JWT, or third-party auth (Clerk, Supabase Auth, Auth0)
• Adding OAuth2 / social login flows
• Reviewing JWT expiry, refresh token rotation, or session invalidation
• Adding role-based or attribute-based access control (RBAC/ABAC)

Library decision matrix

NextAuth.js v5 (Auth.js)

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Credentials from "next-auth/providers/credentials";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    GitHub({ clientId: process.env.AUTH_GITHUB_ID!, clientSecret: process.env.AUTH_GITHUB_SECRET! }),
    Credentials({
      credentials: { email: {}, password: {} },
      async authorize({ email, password }) {
        const user = await verifyCredentials(email as string, password as string);
        return user ?? null; // null triggers "Invalid credentials" error
      },
    }),
  ],
  session: { strategy: "jwt" },
  callbacks: {
    async jwt({ token, user }) {
      if (user) token.role = user.role; // attach custom claims
      return token;
    },
    async session({ session, token }) {
      session.user.role = token.role as string;
      return session;
    },
  },
});

// Route handler: app/api/auth/[...nextauth]/route.ts
export { handlers as GET, handlers as POST } from "@/auth";

// Protect a server component
import { auth } from "@/auth";
import { redirect } from "next/navigation";

export default async function ProtectedPage() {
  const session = await auth();
  if (!session) redirect("/login");
  return <div>Welcome, {session.user?.name}</div>;
}