Learning Objectives

Understand session management in Supabase
Implement route protection with middleware
Handle session refresh and expiration
Create protected layouts and components
Implement proper logout flow

1. Session Management Overview

Understanding how Supabase handles authentication sessions is crucial for building secure applications. The following diagram illustrates the complete session flow from login through protected resource access.

How Supabase Sessions Work

User Login → Supabase Auth → Access Token + Refresh Token
                                   ↓
                            Stored in Cookies
                                   ↓
                        Request → Middleware
                                   ↓
                      Verify Token → Refresh if needed
                                   ↓
                          Access Protected Resource

Token Types

Supabase uses two types of tokens to manage authentication. The access token is short-lived for security, while the refresh token allows obtaining new access tokens without re-authentication.

Token	Purpose	Lifetime
Access Token	Authenticate requests	1 hour (default)
Refresh Token	Get new access token	1 week (default)

2. Middleware Configuration

Next.js middleware runs before every request, making it the ideal place to check authentication status and protect routes. The middleware intercepts requests, validates sessions, and redirects users as needed.

Complete Middleware Setup

This middleware configuration handles three key responsibilities: refreshing expired sessions automatically, redirecting unauthenticated users away from protected routes, and preventing authenticated users from accessing auth pages like login.

// middleware.ts
import { type NextRequest, NextResponse } from "next/server";
import { createServerClient } from "@supabase/ssr";

// Define route access patterns
const publicRoutes = ["/", "/about", "/pricing", "/contact"];
const authRoutes = [
  "/login",
  "/register",
  "/forgot-password",
  "/reset-password",
];
const protectedRoutes = [
  "/dashboard",
  "/profile",
  "/settings",
  "/wallet",
  "/transactions",
];

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Create response to modify
  let response = NextResponse.next({
    request,
  });

  // Create Supabase client
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll();
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value }) =>
            request.cookies.set(name, value)
          );
          response = NextResponse.next({
            request,
          });
          cookiesToSet.forEach(({ name, value, options }) =>
            response.cookies.set(name, value, options)
          );
        },
      },
    }
  );

  // IMPORTANT: This refreshes the session if needed
  // Do not remove this line - it handles token refresh
  const {
    data: { user },
    error,
  } = await supabase.auth.getUser();

  // Check if current path requires protection
  const isProtectedRoute = protectedRoutes.some((route) =>
    pathname.startsWith(route)
  );
  const isAuthRoute = authRoutes.some((route) => pathname.startsWith(route));

  // Redirect unauthenticated users from protected routes
  if (isProtectedRoute && (!user || error)) {
    const loginUrl = new URL("/login", request.url);
    loginUrl.searchParams.set("next", pathname);
    return NextResponse.redirect(loginUrl);
  }

  // Redirect authenticated users from auth routes to dashboard
  if (isAuthRoute && user && !error) {
    return NextResponse.redirect(new URL("/dashboard", request.url));
  }

  return response;
}

export const config = {
  matcher: [
    /*
     * Match all request paths except for:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     * - public folder files
     * - API routes that don't need auth
     */
    "/((?!_next/static|_next/image|favicon.ico|api/public|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

3. Protected Server Components

Server components can verify authentication before rendering content. This section shows how to create reusable helper functions that ensure users are authenticated and have valid profiles.

Using requireAuth Helper

These helper functions use React's cache to deduplicate auth requests within a single render pass. This prevents multiple database queries when several components need user data.

// lib/auth/server.ts
import { createClient } from "@/lib/supabase/server";
import { redirect } from "next/navigation";
import { cache } from "react";

// Cache the user lookup for the request lifecycle
export const getUser = cache(async () => {
  const supabase = await createClient();
  const {
    data: { user },
    error,
  } = await supabase.auth.getUser();

  if (error) {
    console.error("Error fetching user:", error.message);
    return null;
  }

  return user;
});

// Get user profile from database
export const getUserProfile = cache(async () => {
  const user = await getUser();
  if (!user) return null;

  const supabase = await createClient();
  const { data: profile } = await supabase
    .from("users")
    .select("*, wallets(*)")
    .eq("auth_id", user.id)
    .single();

  return profile;
});

// Require authentication - redirect if not logged in
export async function requireAuth() {
  const user = await getUser();

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

  return user;
}

// Require profile - ensures user has a profile
export async function requireProfile() {
  const profile = await getUserProfile();

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

  return profile;
}

Protected Page Example

This example demonstrates how to use the requireProfile helper in a dashboard page. The helper automatically redirects unauthenticated users to login, ensuring the page content only renders for valid users.

// app/(dashboard)/page.tsx
import { requireProfile } from '@/lib/auth/server'
import { createClient } from '@/lib/supabase/server'
import { WalletCard } from '@/components/dashboard/WalletCard'
import { RecentTransactions } from '@/components/dashboard/RecentTransactions'

export default async function DashboardPage() {
  // This will redirect to /login if not authenticated
  const profile = await requireProfile()

  const supabase = await createClient()

  // Fetch additional data
  const { data: transactions } = await supabase
    .from('transactions')
    .select('*, product:products(*)')
    .eq('user_id', profile.id)
    .order('created_at', { ascending: false })
    .limit(5)

  return (
    <div className="space-y-6">
      <h1 className="text-2xl font-bold">
        Welcome back, {profile.full_name}!
      </h1>

      <WalletCard wallet={profile.wallets?.[0]} />

      <RecentTransactions transactions={transactions || []} />
    </div>
  )
}

4. Protected Client Components

Client components need access to authentication state for UI decisions like showing user menus or login buttons. The AuthContext provides this state throughout your application.

Auth Context Provider

This context provider manages client-side authentication state, including the current user, session, and profile data. It also listens for auth state changes to keep the UI synchronized with the actual auth status.

// contexts/AuthContext.tsx
'use client'

import {
  createContext,
  useContext,
  useEffect,
  useState,
  useCallback,
} from 'react'
import { createClient } from '@/lib/supabase/client'
import { useRouter } from 'next/navigation'
import type { User, Session } from '@supabase/supabase-js'

interface Profile {
  id: string
  full_name: string
  email: string
  phone: string | null
  avatar_url: string | null
}

interface AuthContextType {
  user: User | null
  session: Session | null
  profile: Profile | null
  loading: boolean
  signOut: () => Promise<void>
  refreshProfile: () => Promise<void>
}

const AuthContext = createContext<AuthContextType | undefined>(undefined)

export function AuthProvider({
  children,
  initialSession,
}: {
  children: React.ReactNode
  initialSession?: Session | null
}) {
  const [session, setSession] = useState<Session | null>(initialSession ?? null)
  const [user, setUser] = useState<User | null>(initialSession?.user ?? null)
  const [profile, setProfile] = useState<Profile | null>(null)
  const [loading, setLoading] = useState(!initialSession)

  const router = useRouter()
  const supabase = createClient()

  // Fetch user profile
  const fetchProfile = useCallback(async (userId: string) => {
    const { data } = await supabase
      .from('users')
      .select('id, full_name, email, phone, avatar_url')
      .eq('auth_id', userId)
      .single()

    setProfile(data)
  }, [supabase])

  // Refresh profile
  const refreshProfile = useCallback(async () => {
    if (user) {
      await fetchProfile(user.id)
    }
  }, [user, fetchProfile])

  // Sign out
  const signOut = useCallback(async () => {
    await supabase.auth.signOut()
    setUser(null)
    setSession(null)
    setProfile(null)
    router.push('/login')
    router.refresh()
  }, [supabase, router])

  // Initialize auth state
  useEffect(() => {
    const initializeAuth = async () => {
      if (!initialSession) {
        const { data: { session } } = await supabase.auth.getSession()
        setSession(session)
        setUser(session?.user ?? null)

        if (session?.user) {
          await fetchProfile(session.user.id)
        }
      } else if (initialSession.user) {
        await fetchProfile(initialSession.user.id)
      }

      setLoading(false)
    }

    initializeAuth()
  }, [supabase, initialSession, fetchProfile])

  // Listen for auth changes
  useEffect(() => {
    const { data: { subscription } } = supabase.auth.onAuthStateChange(
      async (event, session) => {
        console.log('Auth event:', event)

        setSession(session)
        setUser(session?.user ?? null)

        if (session?.user) {
          await fetchProfile(session.user.id)
        } else {
          setProfile(null)
        }

        // Handle specific events
        if (event === 'SIGNED_OUT') {
          router.push('/login')
          router.refresh()
        } else if (event === 'SIGNED_IN') {
          router.refresh()
        } else if (event === 'TOKEN_REFRESHED') {
          console.log('Token refreshed')
        }
      }
    )

    return () => {
      subscription.unsubscribe()
    }
  }, [supabase, router, fetchProfile])

  return (
    <AuthContext.Provider
      value={{
        user,
        session,
        profile,
        loading,
        signOut,
        refreshProfile,
      }}
    >
      {children}
    </AuthContext.Provider>
  )
}

export function useAuth() {
  const context = useContext(AuthContext)

  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider')
  }

  return context
}

Using Auth Context

This UserMenu component demonstrates how to consume the auth context. It displays different content based on authentication state and provides navigation to profile settings and a sign-out option.

// components/layout/UserMenu.tsx
'use client'

import { useAuth } from '@/contexts/AuthContext'
import { Menu, Transition } from '@headlessui/react'
import Link from 'next/link'

export function UserMenu() {
  const { user, profile, loading, signOut } = useAuth()

  if (loading) {
    return <div className="w-8 h-8 bg-gray-200 rounded-full animate-pulse" />
  }

  if (!user || !profile) {
    return (
      <Link href="/login" className="text-sm font-medium text-gray-600">
        Sign In
      </Link>
    )
  }

  const initials = profile.full_name
    .split(' ')
    .map((n) => n[0])
    .join('')
    .toUpperCase()

  return (
    <Menu as="div" className="relative">
      <Menu.Button className="flex items-center gap-2 p-1 rounded-lg hover:bg-gray-100">
        <div className="w-8 h-8 bg-primary text-white rounded-full flex items-center justify-center text-sm font-medium">
          {profile.avatar_url ? (
            <img
              src={profile.avatar_url}
              alt={profile.full_name}
              className="w-full h-full rounded-full object-cover"
            />
          ) : (
            initials
          )}
        </div>
        <span className="hidden md:block text-sm font-medium">
          {profile.full_name}
        </span>
      </Menu.Button>

      <Transition
        enter="transition ease-out duration-100"
        enterFrom="transform opacity-0 scale-95"
        enterTo="transform opacity-100 scale-100"
        leave="transition ease-in duration-75"
        leaveFrom="transform opacity-100 scale-100"
        leaveTo="transform opacity-0 scale-95"
      >
        <Menu.Items className="absolute right-0 mt-2 w-48 bg-white rounded-lg shadow-lg ring-1 ring-black/5">
          <div className="p-1">
            <Menu.Item>
              {({ active }) => (
                <Link
                  href="/dashboard/profile"
                  className={`block px-4 py-2 text-sm rounded-md ${
                    active ? 'bg-gray-100' : ''
                  }`}
                >
                  Profile
                </Link>
              )}
            </Menu.Item>
            <Menu.Item>
              {({ active }) => (
                <Link
                  href="/dashboard/settings"
                  className={`block px-4 py-2 text-sm rounded-md ${
                    active ? 'bg-gray-100' : ''
                  }`}
                >
                  Settings
                </Link>
              )}
            </Menu.Item>
            <hr className="my-1" />
            <Menu.Item>
              {({ active }) => (
                <button
                  onClick={signOut}
                  className={`block w-full text-left px-4 py-2 text-sm text-red-600 rounded-md ${
                    active ? 'bg-red-50' : ''
                  }`}
                >
                  Sign Out
                </button>
              )}
            </Menu.Item>
          </div>
        </Menu.Items>
      </Transition>
    </Menu>
  )
}

5. Session Refresh Handling

Sessions need to be refreshed periodically to maintain security while providing a smooth user experience. This section covers how to initialize the auth provider with server-side session data and handle expiration.

Auto Refresh on App Load

The root layout fetches the initial session on the server and passes it to the AuthProvider. This ensures the client starts with the correct authentication state without an additional round trip.

// app/layout.tsx
import { createClient } from '@/lib/supabase/server'
import { AuthProvider } from '@/contexts/AuthContext'

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const supabase = await createClient()
  const { data: { session } } = await supabase.auth.getSession()

  return (
    <html lang="en">
      <body>
        <AuthProvider initialSession={session}>
          {children}
        </AuthProvider>
      </body>
    </html>
  )
}

Handle Session Expiry

This custom hook monitors session validity and redirects users to login when their session expires. It checks the session periodically and when the browser tab becomes visible after being in the background.

// hooks/useSessionExpiry.ts
"use client";

import { useEffect, useCallback } from "react";
import { createClient } from "@/lib/supabase/client";
import { useRouter } from "next/navigation";

export function useSessionExpiry() {
  const router = useRouter();
  const supabase = createClient();

  const checkSession = useCallback(async () => {
    const {
      data: { session },
      error,
    } = await supabase.auth.getSession();

    if (error || !session) {
      // Session expired or invalid
      router.push("/login?expired=true");
      router.refresh();
    }
  }, [supabase, router]);

  useEffect(() => {
    // Check session on mount
    checkSession();

    // Check session periodically (every 5 minutes)
    const interval = setInterval(checkSession, 5 * 60 * 1000);

    // Check session when tab becomes visible
    const handleVisibilityChange = () => {
      if (document.visibilityState === "visible") {
        checkSession();
      }
    };

    document.addEventListener("visibilitychange", handleVisibilityChange);

    return () => {
      clearInterval(interval);
      document.removeEventListener("visibilitychange", handleVisibilityChange);
    };
  }, [checkSession]);
}

Session Expiry Notice

When users are redirected due to session expiry, we should inform them why. This component checks for the expired parameter in the URL and displays an appropriate message.

// app/(auth)/login/page.tsx
import { Suspense } from 'react'
import { LoginForm } from './login-form'
import { SessionExpiredNotice } from './session-expired-notice'

export default function LoginPage() {
  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="max-w-md w-full space-y-8">
        <Suspense fallback={null}>
          <SessionExpiredNotice />
        </Suspense>
        <LoginForm />
      </div>
    </div>
  )
}

// session-expired-notice.tsx
'use client'

import { useSearchParams } from 'next/navigation'
import { Alert } from '@/components/ui/Alert'

export function SessionExpiredNotice() {
  const searchParams = useSearchParams()
  const expired = searchParams.get('expired')

  if (expired !== 'true') return null

  return (
    <Alert variant="warning">
      Your session has expired. Please sign in again.
    </Alert>
  )
}

6. Protected Layout Pattern

Dashboard layouts typically need to verify authentication and fetch user data before rendering. This pattern ensures consistent protection across all child pages while avoiding redundant auth checks.

The following layout verifies authentication, fetches the user profile, and includes a client-side component for handling session refresh events.

// app/(dashboard)/layout.tsx
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
import { Sidebar } from '@/components/layout/Sidebar'
import { Header } from '@/components/layout/Header'
import { SessionRefresh } from '@/components/auth/SessionRefresh'

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const supabase = await createClient()
  const { data: { user }, error } = await supabase.auth.getUser()

  // Redirect if not authenticated
  if (!user || error) {
    redirect('/login')
  }

  // Fetch user profile
  const { data: profile } = await supabase
    .from('users')
    .select('*, wallets(*)')
    .eq('auth_id', user.id)
    .single()

  // Redirect if profile doesn't exist (edge case)
  if (!profile) {
    redirect('/onboarding')
  }

  return (
    <div className="min-h-screen bg-gray-50">
      {/* Client component to handle session refresh */}
      <SessionRefresh />

      <Sidebar user={profile} />

      <div className="lg:pl-64">
        <Header user={profile} />
        <main className="p-6">
          {children}
        </main>
      </div>
    </div>
  )
}

Session Refresh Component

This client component listens for auth state changes and handles navigation when users sign out or their tokens are refreshed. It renders nothing visually but provides essential functionality.

// components/auth/SessionRefresh.tsx
"use client";

import { useEffect } from "react";
import { createClient } from "@/lib/supabase/client";
import { useRouter } from "next/navigation";

export function SessionRefresh() {
  const router = useRouter();
  const supabase = createClient();

  useEffect(() => {
    const {
      data: { subscription },
    } = supabase.auth.onAuthStateChange((event, session) => {
      if (event === "TOKEN_REFRESHED") {
        // Session refreshed successfully
        console.log("Session refreshed");
      } else if (event === "SIGNED_OUT") {
        // User signed out
        router.push("/login");
        router.refresh();
      }
    });

    return () => {
      subscription.unsubscribe();
    };
  }, [supabase, router]);

  return null; // This component renders nothing
}

7. Sign Out Flow

Signing out requires clearing the session on both client and server, invalidating cached data, and redirecting users to an appropriate page. The server action approach ensures proper cleanup.

Server Action

This server action handles sign out by calling Supabase's signOut method, revalidating all cached paths to clear any user-specific data, and redirecting to the login page.

// app/actions/auth.ts
"use server";

import { createClient } from "@/lib/supabase/server";
import { redirect } from "next/navigation";
import { revalidatePath } from "next/cache";

export async function signOut() {
  const supabase = await createClient();

  const { error } = await supabase.auth.signOut();

  if (error) {
    console.error("Error signing out:", error.message);
    // Continue anyway - clear client-side session
  }

  // Clear all cached data
  revalidatePath("/", "layout");

  redirect("/login");
}

Sign Out Button

This client component provides a sign-out button that calls the server action. It includes loading state to prevent double-clicks and provide user feedback during the sign-out process.

// components/auth/SignOutButton.tsx
'use client'

import { useState } from 'react'
import { signOut } from '@/app/actions/auth'
import { Button } from '@/components/ui/Button'

export function SignOutButton() {
  const [loading, setLoading] = useState(false)

  const handleSignOut = async () => {
    setLoading(true)
    try {
      await signOut()
    } catch (error) {
      console.error('Sign out error:', error)
      setLoading(false)
    }
  }

  return (
    <Button
      variant="ghost"
      onClick={handleSignOut}
      loading={loading}
      className="text-red-600 hover:bg-red-50"
    >
      Sign Out
    </Button>
  )
}

8. Role-Based Access Control

Some applications require different access levels for different users. This section shows how to implement role-based access control by checking user roles stored in the database.

Check User Role

This helper function verifies that the current user has one of the allowed roles before granting access to a page or feature. It redirects unauthorized users to an error page.

// lib/auth/roles.ts
import { createClient } from "@/lib/supabase/server";
import { redirect } from "next/navigation";

type UserRole = "user" | "admin" | "super_admin";

export async function requireRole(allowedRoles: UserRole[]) {
  const supabase = await createClient();
  const {
    data: { user },
  } = await supabase.auth.getUser();

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

  const { data: profile } = await supabase
    .from("users")
    .select("role")
    .eq("auth_id", user.id)
    .single();

  if (!profile || !allowedRoles.includes(profile.role as UserRole)) {
    redirect("/unauthorized");
  }

  return { user, role: profile.role as UserRole };
}

Admin-Only Page

This example shows how to create a page that only admin users can access. The requireRole helper handles authentication and authorization before any page content renders.

// app/admin/page.tsx
import { requireRole } from '@/lib/auth/roles'

export default async function AdminPage() {
  // Only allow admin and super_admin
  await requireRole(['admin', 'super_admin'])

  return (
    <div>
      <h1>Admin Dashboard</h1>
      {/* Admin content */}
    </div>
  )
}

9. Onboarding Flow

New users may need to complete their profile before accessing the main application. This pattern checks onboarding status in middleware and redirects incomplete users to the onboarding flow.

Check Onboarding Status

The following middleware addition checks if authenticated users have completed onboarding before allowing access to protected routes.

// middleware.ts (updated)
// Add to existing middleware

// Check if user needs onboarding
if (user && isProtectedRoute && pathname !== "/onboarding") {
  // Check if profile is complete
  const supabaseWithCookies = createServerClient(/* ... */);
  const { data: profile } = await supabaseWithCookies
    .from("users")
    .select("is_onboarded")
    .eq("auth_id", user.id)
    .single();

  if (profile && !profile.is_onboarded) {
    return NextResponse.redirect(new URL("/onboarding", request.url));
  }
}

Onboarding Page

This page component checks authentication and onboarding status, redirecting users who have already completed onboarding to the dashboard.

// app/onboarding/page.tsx
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
import { OnboardingForm } from './onboarding-form'

export default async function OnboardingPage() {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    redirect('/login')
  }

  // Check if already onboarded
  const { data: profile } = await supabase
    .from('users')
    .select('is_onboarded')
    .eq('auth_id', user.id)
    .single()

  if (profile?.is_onboarded) {
    redirect('/dashboard')
  }

  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="max-w-md w-full">
        <h1 className="text-2xl font-bold mb-6">Complete Your Profile</h1>
        <OnboardingForm />
      </div>
    </div>
  )
}

10. Security Best Practices

Following security best practices is essential for protecting user data and preventing unauthorized access. These guidelines help ensure your authentication implementation is robust.

1. Always Verify on Server

Client-side auth checks can be bypassed, so always verify authentication on the server before rendering sensitive content or performing actions.

// GOOD: Verify on server
export default async function ProtectedPage() {
  const {
    data: { user },
  } = await supabase.auth.getUser();
  if (!user) redirect("/login");
}

// BAD: Only check on client
("use client");
export default function ProtectedPage() {
  const { user } = useAuth();
  if (!user) return null; // Can be bypassed
}

2. Use getUser(), Not getSession()

The getUser() method validates the JWT token with Supabase, while getSession() only reads the local session without validation. Always use getUser() for security-critical checks.

// GOOD: getUser() validates the JWT
const {
  data: { user },
} = await supabase.auth.getUser();

// LESS SECURE: getSession() doesn't validate
const {
  data: { session },
} = await supabase.auth.getSession();

3. Handle All Auth Events

Properly handling all authentication events ensures your application stays in sync with the actual auth state and can respond appropriately to changes.

supabase.auth.onAuthStateChange((event, session) => {
  switch (event) {
    case "SIGNED_IN":
    case "SIGNED_OUT":
    case "TOKEN_REFRESHED":
    case "USER_UPDATED":
    case "PASSWORD_RECOVERY":
    // Handle each appropriately
  }
});

4. Secure Cookie Settings

Supabase configures cookies with secure defaults. Understanding these settings helps you maintain security when customizing your implementation.

// Cookies are set by Supabase with these defaults:
// - HttpOnly: true (not accessible via JavaScript)
// - Secure: true in production (HTTPS only)
// - SameSite: Lax (CSRF protection)

Additional Resources

Next Lesson: Password Reset Flow