Nextjs-Auth0 v4.9 Authentication Tutorial: Secure User Management Made Simple

npm i @auth0/nextjs-auth0

AUTH0_DOMAIN=your-auth0-domain.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
AUTH0_SECRET=long-random-string   # use: openssl rand -hex 32
APP_BASE_URL=http://localhost:3000

openssl rand -hex 32

import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client();

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { auth0 } from "@/lib/auth0";

// 📋 List of routes that anyone can access without logging in
const PUBLIC_ROUTES = ["/api/public-blogs", "/home"];

/**
 * 🛡️ MIDDLEWARE FUNCTION - This runs before every page/API request
 * Think of it as a security guard that checks if users are allowed to enter
 */
export async function middleware(req: NextRequest) {
  // 📍 Get the path the user is trying to visit (e.g., "/dashboard", "/api/users")
  const { pathname } = req.nextUrl;

  // ✅ PUBLIC ROUTES - Let anyone through without checking login
  // If someone visits /home or /api/public-blogs, they don't need to be logged in
  if (PUBLIC_ROUTES.includes(pathname)) {
    return NextResponse.next(); // ➡️ Continue to the requested page
  }

  // 🔒 API ROUTE PROTECTION - Check login for all /api/* routes
  if (pathname.startsWith("/api")) {
    // 👤 Try to get the user's login session
    const session = await auth0.getSession(req);
    
    // ❌ No session found = user not logged in
    if (!session) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }
    
    // ✅ User is logged in, let them access the API
    return NextResponse.next();
  }

  // 🏠 PAGE PROTECTION - Handle all regular pages (not API routes)
  // Use Auth0's built-in middleware to check authentication
  return await auth0.middleware(req).catch(error => {
    // 🚨 Handle specific error: Invalid/corrupted login cookie
    if (error?.code === "ERR_JWE_INVALID") {
      // Clear the bad cookie and send unauthorized response
      const res = NextResponse.json({ error: "Unauthorized" }, { status: 401 });
      res.cookies.delete("__session"); // 🗑️ Remove corrupted session cookie
      return res;
    }
    
    // 🤷 For other errors, just continue (might be handled elsewhere)
    return NextResponse.next();
  });
}

/**
 * ⚙️ CONFIGURATION - Tell Next.js which routes this middleware should run on
 */
export const config = {
  matcher: [
    // 🎯 Run on ALL routes EXCEPT:
    // - Static files (_next/static/*)
    // - Images (_next/image/*)  
    // - favicon.ico, sitemap.xml, robots.txt
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    
    // 🔗 Also run on all /api routes
    "/api",
  ],
};

/* 
📚 HOW THIS WORKS:
1. User visits any page on your site
2. This middleware runs first (before the page loads)
3. It checks if the route is public → if yes, allow access
4. If it's an API route → check for valid login session
5. If it's a regular page → use Auth0 to handle authentication
6. If user isn't logged in → redirect to login or return error
7. If user is logged in → let them continue to their destination

🎯 RESULT: Only logged-in users can access protected pages and APIs!
*/

"use client"; // 🌐 This tells Next.js this component runs in the browser (client-side)

import { useUser } from "@auth0/nextjs-auth0";

/**
 * 🧭 NAVIGATION COMPONENT
 * Shows different content based on whether user is logged in or not
 * Think of it like a smart menu that changes based on who's visiting
 */
export default function Nav() {
  // 👤 Get the current user's information from Auth0
  // This hook automatically handles checking if someone is logged in
  const { user } = useUser();

  // ❌ USER NOT LOGGED IN - Show login button
  if (!user) {
    return <a href="/auth/login">Login</a>;
  }

  // ✅ USER IS LOGGED IN - Show welcome message and logout option
  return (
    <div>
      {/* 👋 Greet the user by name */}
      Welcome, {user.name}!
      
      {/* 🚪 Provide logout option */}
      <a href="/auth/logout">Logout</a>
    </div>
  );
}

/* 
📚 HOW THIS COMPONENT WORKS:

1. 🔍 CHECKS LOGIN STATUS
   - useUser() hook automatically checks if someone is logged in
   - Returns user data if logged in, or null/undefined if not

2. 🎭 SHOWS DIFFERENT CONTENT
   - Not logged in? → Shows "Login" link
   - Logged in? → Shows "Welcome [Name]" + "Logout" link

3. 🔗 USES AUTH0 ROUTES
   - /auth/login → Auth0's built-in login page
   - /auth/logout → Auth0's built-in logout functionality

4. ⚡ AUTOMATIC UPDATES
   - When user logs in/out, this component automatically re-renders
   - No manual refresh needed!

🎯 RESULT: A navigation that automatically adapts to user's login state
*/

import { auth0 } from "@/lib/auth0";

/**
 * 🖥️ SERVER-SIDE PAGE COMPONENT
 * This runs on the server BEFORE sending HTML to the browser
 * Perfect for getting user data securely without loading states
 */
export default async function Page() {
  // 👤 Get user session directly on the server
  // This happens during page generation, so user data is ready immediately
  const session = await auth0.getSession();

  return (
    <div>
      {/* 
        👋 Display user's name with safe access
        session?.user?.name uses "optional chaining" which means:
        - If session exists AND user exists AND name exists → show the name
        - If any part is missing → show nothing (no errors)
      */}
      Hello, {session?.user?.name}
    </div>
  );
}

/* 
📚 HOW THIS SERVER COMPONENT WORKS:

🔍 KEY DIFFERENCES FROM CLIENT COMPONENTS:
- ❌ No "use client" directive → runs on server
- ❌ No useUser() hook → not needed in server components  
- ❌ No loading states → data is ready when page loads
- ✅ Direct auth0.getSession() call → works on server

⚡ EXECUTION FLOW:
1. User visits this page
2. Next.js runs this function on the SERVER
3. auth0.getSession() checks for valid session
4. Component renders with user data (or without if not logged in)
5. Completed HTML is sent to browser
6. User sees the page instantly with their name

🛡️ SECURITY BENEFITS:
- Session checking happens server-side (more secure)
- No flash of "loading..." or wrong content
- User data is available immediately when page loads

⚠️ IMPORTANT NOTES:
- This only works in Server Components (no "use client")
- If you need interactivity, use the client component version instead
- The optional chaining (?.) prevents errors if user isn't logged in

🎯 RESULT: Instant personalized content without loading delays!
*/

👤 [User Browser]
     |
     | (1) Visit protected page or login
     v
🖥️ [Next.js App Server / Middleware]
     |
     | (2) Check for Auth0 session cookie
     |     - If no session, redirect to login
     v
🔐 [Auth0 Universal Login Page]
     |
     | (3) User login with credentials/social
     v
🛡️ [Auth0 Server]
     |
     | (4) Redirect back with auth code to Next.js callback route
     v
🔄 [Next.js Callback API Route]
     |
     | (5) Exchange auth code for tokens (id_token, access_token)
     |     Create secure session cookie with tokens
     v
🖥️ [Next.js App Server]
     |
     | (6) Serve requested page or API data using session info
     v
👤 [User Browser]
     |
     | (7) Client side React components use `useUser()` hook to access user data