User Authentication in Next.js

This tutorial part builds upon the Protected Routes part by adding complete email/password authentication with email verification functionality. You’ll implement sign up, sign in, email verification, and sign out features to create a full authentication flow.

Note

This is Part 3 in the Full-Stack Next.js Development with Nhost series. This part creates a production-ready authentication system with secure email verification and proper error handling using Next.js App Router.

Full-Stack Next.js Development with Nhost

1. Create Project

Set up your Nhost project

2. Protected Routes

Route protection basics

3. User Authentication

Current - Complete auth flow

4. GraphQL Operations

CRUD operations with GraphQL

5. File Uploads

File upload and management

Prerequisites

• Complete the Protected Routes part first
• The project from the previous part set up and running

Step-by-Step Guide

Create the Sign In Flow

In this step, we’ll create a complete sign-in flow using Next.js App Router patterns. We’ll build three key files: a server component for the main page that handles URL parameters, a client component for the interactive form, and server actions for secure authentication processing.

Page Component

The main sign-in page is a server component that handles URL parameters (like error messages) and renders the sign-in form. This component runs on the server and can access search parameters directly.

src/app/signin/page.tsx

import Link from "next/link";
import SignInForm from "./SignInForm";

export default async function SignIn({
  searchParams,
}: {
  searchParams: Promise<{ error?: string }>;
}) {
  // Extract error from URL parameters
  const params = await searchParams;
  const error = params?.error;

  return (
    <div>
      <h1>Sign In</h1>
      <SignInForm initialError={error} />

      <div className="auth-links">
        <p>
          Don't have an account? <Link href="/signup">Sign Up</Link>
        </p>
      </div>
    </div>
  );
}

Form Component

The sign-in form is a client component that handles user interactions, loading states, and form submissions. It communicates with server actions and provides real-time feedback to users.

src/app/signin/SignInForm.tsx

"use client";

import { useRouter } from "next/navigation";
import { useId, useState } from "react";
import { signIn } from "./actions";

interface SignInFormProps {
  initialError?: string;
}

export default function SignInForm({ initialError }: SignInFormProps) {
  const [error, setError] = useState<string | undefined>(initialError);
  const [isLoading, setIsLoading] = useState(false);
  const router = useRouter();

  const emailId = useId();
  const passwordId = useId();

  const handleSubmit = async (formData: FormData) => {
    setIsLoading(true);
    setError(undefined);

    try {
      const result = await signIn(formData);

      if (result.redirect) {
        router.push(result.redirect);
      } else if (result.error) {
        setError(result.error);
      }
    } catch (err: unknown) {
      setError(
        err instanceof Error ? err.message : "An error occurred during sign in",
      );
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <form action={handleSubmit} className="auth-form">
      <div className="auth-form-field">
        <label htmlFor={emailId}>Email</label>
        <input
          id={emailId}
          name="email"
          type="email"
          required
          className="auth-input"
        />
      </div>

      <div className="auth-form-field">
        <label htmlFor={passwordId}>Password</label>
        <input
          id={passwordId}
          name="password"
          type="password"
          required
          className="auth-input"
        />
      </div>

      {error && <div className="auth-error">{error}</div>}

      <button
        type="submit"
        disabled={isLoading}
        className="auth-button secondary"
      >
        {isLoading ? "Signing In..." : "Sign In"}
      </button>
    </form>
  );
}

Server Actions

Server actions handle the authentication logic securely on the server side. They validate form data, communicate with Nhost, and return appropriate responses for success or error states.

src/app/signin/actions.ts

"use server";

import type { ErrorResponse } from "@nhost/nhost-js/auth";
import type { FetchError } from "@nhost/nhost-js/fetch";
import { createNhostClient } from "../../lib/nhost/server";

export async function signIn(formData: FormData) {
  const email = formData.get("email") as string;
  const password = formData.get("password") as string;

  if (!email || !password) {
    return {
      error: "Email and password are required",
    };
  }

  try {
    const nhost = await createNhostClient();

    const response = await nhost.auth.signInEmailPassword({
      email,
      password,
    });

    if (response.body?.session) {
      return { redirect: "/profile" };
    } else {
      return {
        error: "Failed to sign in. Please check your credentials.",
      };
    }
  } catch (err) {
    const error = err as FetchError<ErrorResponse>;
    return {
      error: `An error occurred during sign in: ${error.message}`,
    };
  }
}

Create the Sign Up Flow

In this step, we’ll build the user registration system with email verification support. The sign-up flow includes handling both the registration form and the email verification success state, all using Next.js server and client components.

Page Component

The sign-up page is a server component that manages different states: showing the registration form or displaying the email verification success message. It handles URL parameters to determine which state to render.

src/app/signup/page.tsx

import Link from "next/link";
import SignUpForm from "./SignUpForm";

export default async function SignUp({
  searchParams,
}: {
  searchParams: Promise<{
    error?: string;
    verify?: string;
    email?: string;
  }>;
}) {
  // Extract parameters from URL
  const params = await searchParams;
  const error = params?.error;
  const verificationSent = params?.verify === "success";
  const email = params?.email;

  if (verificationSent) {
    return (
      <div>
        <h1>Check Your Email</h1>
        <div className="success-message">
          <p>
            We've sent a verification link to <strong>{email}</strong>
          </p>
          <p>
            Please check your email and click the verification link to activate
            your account.
          </p>
        </div>
        <p>
          <Link href="/signin">Back to Sign In</Link>
        </p>
      </div>
    );
  }

  return (
    <div>
      <h1>Sign Up</h1>
      <SignUpForm initialError={error} />

      <div className="auth-links">
        <p>
          Already have an account? <Link href="/signin">Sign In</Link>
        </p>
      </div>
    </div>
  );
}

Form Component

The registration form is a client component that collects user information (display name, email, password) and handles form validation, loading states, and error feedback during the sign-up process.

src/app/signup/SignUpForm.tsx

"use client";

import { generatePKCEPair } from "@nhost/nhost-js/auth";
import { useRouter } from "next/navigation";
import { useId, useState } from "react";
import { signUp } from "./actions";

interface SignUpFormProps {
  initialError?: string;
}

export default function SignUpForm({ initialError }: SignUpFormProps) {
  const [error, setError] = useState<string | undefined>(initialError);
  const [isLoading, setIsLoading] = useState(false);
  const router = useRouter();

  const displayNameId = useId();
  const emailId = useId();
  const passwordId = useId();

  const handleSubmit = async (formData: FormData) => {
    setIsLoading(true);
    setError(undefined);

    try {
      // Generate PKCE pair and store verifier for email verification
      const { verifier, challenge } = await generatePKCEPair();
      document.cookie = `nhost_pkce_verifier=${verifier}; path=/; SameSite=Lax; max-age=3600`;

      // Pass the challenge to the server action
      formData.set("codeChallenge", challenge);

      const result = await signUp(formData);

      if (result.redirect) {
        router.push(result.redirect);
      } else if (result.error) {
        setError(result.error);
      }
    } catch (err: unknown) {
      setError(
        err instanceof Error ? err.message : "An error occurred during sign up",
      );
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <form action={handleSubmit} className="auth-form">
      <div className="auth-form-field">
        <label htmlFor={displayNameId}>Display Name</label>
        <input
          id={displayNameId}
          name="displayName"
          type="text"
          required
          className="auth-input"
        />
      </div>

      <div className="auth-form-field">
        <label htmlFor={emailId}>Email</label>
        <input
          id={emailId}
          name="email"
          type="email"
          required
          className="auth-input"
        />
      </div>

      <div className="auth-form-field">
        <label htmlFor={passwordId}>Password</label>
        <input
          id={passwordId}
          name="password"
          type="password"
          required
          minLength={8}
          className="auth-input"
        />
        <small className="help-text">Minimum 8 characters</small>
      </div>

      {error && <div className="auth-error">{error}</div>}

      <button
        type="submit"
        disabled={isLoading}
        className="auth-button primary"
      >
        {isLoading ? "Creating Account..." : "Sign Up"}
      </button>
    </form>
  );
}

Server Actions

Server actions handle user registration with Nhost, including setting up email verification. They process form data, create user accounts, and coordinate the email verification flow by setting the appropriate redirect URLs.

src/app/signup/actions.ts

"use server";

import type { ErrorResponse } from "@nhost/nhost-js/auth";
import type { FetchError } from "@nhost/nhost-js/fetch";
import { createNhostClient } from "../../lib/nhost/server";

export async function signUp(formData: FormData) {
  const email = formData.get("email") as string;
  const password = formData.get("password") as string;
  const displayName = formData.get("displayName") as string;
  const codeChallenge = formData.get("codeChallenge") as string;

  if (!email || !password || !displayName) {
    return {
      error: "All fields are required",
    };
  }

  try {
    const nhost = await createNhostClient();

    const response = await nhost.auth.signUpEmailPassword({
      email,
      password,
      options: {
        displayName,
        redirectTo: `${process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000"}/verify`,
      },
      codeChallenge,
    });

    if (response.body?.session) {
      // Successfully signed up and automatically signed in
      return { redirect: "/profile" };
    } else {
      // Verification email sent
      return {
        redirect: `/signup?verify=success&email=${encodeURIComponent(email)}`,
      };
    }
  } catch (err) {
    const error = err as FetchError<ErrorResponse>;
    return {
      error: `An error occurred during sign up: ${error.message}`,
    };
  }
}

Create the Email Verification System

In this step, we’ll implement email verification using PKCE. When users click the verification link in their email, a Route Handler extracts the authorization code and exchanges it for a session using the PKCE verifier stored in a cookie during sign-up. On success it redirects to the profile page; on failure it redirects to an error page.

Verify Route Handler

The verification endpoint is a Route Handler that exchanges the authorization code for a session using PKCE. It reads the code verifier from a cookie (set during sign-up), performs the token exchange server-side, and redirects to the profile page on success. We use a Route Handler instead of a Server Component because cookies can only be modified in a Server Action or Route Handler.

src/app/verify/route.ts

import { cookies } from "next/headers";
import { type NextRequest, NextResponse } from "next/server";
import { createNhostClient } from "../../lib/nhost/server";

const PKCE_VERIFIER_KEY = "nhost_pkce_verifier";

export async function GET(request: NextRequest) {
  const code = request.nextUrl.searchParams.get("code");
  const errorUrl = new URL("/verify/error", request.url);

  if (!code) {
    errorUrl.searchParams.set("message", "No authorization code found in URL");
    return NextResponse.redirect(errorUrl);
  }

  const cookieStore = await cookies();
  const codeVerifier = cookieStore.get(PKCE_VERIFIER_KEY)?.value;

  if (!codeVerifier) {
    errorUrl.searchParams.set(
      "message",
      "No PKCE verifier found. The sign-in must be initiated from the same browser.",
    );
    return NextResponse.redirect(errorUrl);
  }

  // Remove the PKCE verifier cookie
  cookieStore.delete(PKCE_VERIFIER_KEY);

  try {
    const nhost = await createNhostClient();
    await nhost.auth.tokenExchange({ code, codeVerifier });
  } catch (err) {
    errorUrl.searchParams.set(
      "message",
      `Verification failed: ${(err as Error).message}`,
    );
    return NextResponse.redirect(errorUrl);
  }

  return NextResponse.redirect(new URL("/profile", request.url));
}

Error Page

The verification error page is a server component that displays helpful error messages and debugging information when email verification fails. It shows the specific error message and any URL parameters that might help diagnose the issue.

src/app/verify/error/page.tsx

import Link from "next/link";

export default async function VerifyError({
  searchParams,
}: {
  searchParams: Promise<Record<string, string>>;
}) {
  const params = await searchParams;
  const message = params?.message || "Unknown verification error";

  // Filter out the message to show other URL parameters
  const urlParams = Object.entries(params).filter(([key]) => key !== "message");

  return (
    <div>
      <h1>Email Verification</h1>

      <div className="page-center">
        <p className="verification-status error">Verification failed</p>
        <p className="margin-bottom">{message}</p>

        {urlParams.length > 0 && (
          <div className="debug-panel">
            <p className="debug-title">URL Parameters:</p>
            {urlParams.map(([key, value]) => (
              <div key={key} className="debug-item">
                <span className="debug-key">{key}:</span>{" "}
                <span className="debug-value">{value}</span>
              </div>
            ))}
          </div>
        )}

        <Link href="/signin" className="auth-button secondary">
          Back to Sign In
        </Link>
      </div>
    </div>
  );
}

Caution

Important Configuration Required: Before testing email verification, you must configure your Nhost project’s authentication settings:

1. Go to your Nhost project dashboard
2. Navigate to Settings → Authentication
3. Add your local development URL (e.g., http://localhost:3000) to the Allowed Redirect URLs field
4. Ensure your production domain is also added when deploying

Without this configuration, you’ll receive a redirectTo not allowed error when users attempt to sign up or verify their email addresses.

Create the Sign Out System

In this step, we’ll implement user sign-out functionality using Next.js patterns. We’ll create a client component for the sign-out button and a server action to handle the actual sign-out process securely on the server side.

Sign Out Button

The sign-out button is a client component that provides an interactive button for users to sign out. It handles the user interaction and calls the server action, then manages navigation and component refresh after sign-out.

src/components/SignOutButton.tsx

"use client";

import { useRouter } from "next/navigation";
import { signOut } from "../lib/nhost/actions";

export default function SignOutButton() {
  const router = useRouter();

  const handleSignOut = async () => {
    try {
      await signOut();
      router.push("/");
      router.refresh(); // Refresh to update server components
    } catch (err) {
      console.error("Error signing out:", err);
    }
  };

  return (
    <button
      type="button"
      onClick={handleSignOut}
      className="nav-link nav-button"
    >
      Sign Out
    </button>
  );
}

Server Action

The sign-out server action handles the authentication logic securely on the server side. It retrieves the current session, calls Nhost’s sign-out method with the refresh token, and redirects the user to the home page after successful sign-out.

src/lib/nhost/actions.ts

"use server";

import { redirect } from "next/navigation";
import { createNhostClient } from "./server";

export async function signOut() {
  try {
    const nhost = await createNhostClient();
    const session = nhost.getUserSession();

    if (session) {
      await nhost.auth.signOut({
        refreshToken: session.refreshToken,
      });
    }
  } catch (err) {
    console.error("Error signing out:", err);
    throw err;
  }

  redirect("/");
}

Update Navigation Component

In this step, we’ll update the server-side navigation component that shows different links based on the user’s authentication state. The navigation will display “Sign In” and “Sign Up” links for unauthenticated users, and “Profile” and “Sign Out” for authenticated users.

src/components/Navigation.tsx

import Link from "next/link";
import { createNhostClient } from "../lib/nhost/server";
import SignOutButton from "./SignOutButton";

export default async function Navigation() {
  const nhost = await createNhostClient();
  const session = nhost.getUserSession();

  return (
    <nav className="navigation">
      <div className="nav-container">
        <Link href="/" className="nav-logo">
          Nhost Next.js Demo
        </Link>

        <div className="nav-links">
          <Link href="/" className="nav-link">
            Home
          </Link>

          {session ? (
            <>
              <Link href="/profile" className="nav-link">
                Profile
              </Link>
              <SignOutButton />
            </>
          ) : (
            <>
              <Link href="/signin" className="nav-link">
                Sign In
              </Link>
              <Link href="/signup" className="nav-link">
                Sign Up
              </Link>
            </>
          )}
        </div>
      </div>
    </nav>
  );
}

Update Public Routes in Proxy

In this step, we’ll configure the proxy to allow access to authentication-related routes without requiring authentication. This ensures that users can access sign-in, sign-up, and email verification pages even when not logged in.

src/proxy.ts

import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";
import { handleNhostProxy } from "./lib/nhost/server";

// Define public routes that don't require authentication
const publicRoutes = ["/", "/signin", "/signup", "/verify", "/verify/error"];

export async function proxy(request: NextRequest) {
  // Create a response that we'll modify as needed
  const response = NextResponse.next();

  // Get the current path
  const path = request.nextUrl.pathname;

  // Check if this is a public route or a public asset
  const isPublicRoute = publicRoutes.some(
    (route) => path === route || path.startsWith(`${route}/`),
  );

  // Handle Nhost authentication and token refresh
  // Always call this to ensure session is up-to-date
  // even for public routes, so that session changes are detected
  const session = await handleNhostProxy(request, response);

  // If it's a public route, allow access without checking auth
  if (isPublicRoute) {
    return response;
  }

  // If no session and not a public route, redirect to signin
  if (!session) {
    const homeUrl = new URL("/", request.url);
    return NextResponse.redirect(homeUrl);
  }

  // Session exists, allow access to protected route
  return response;
}

// Define which routes this proxy should run on
export const config = {
  matcher: [
    /*
     * Match all request paths except:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     * - public files (public directory)
     */
    "/((?!_next/static|_next/image|favicon.ico|public).*)",
  ],
};

Run and Test the Application

Start your Next.js development server and test the complete authentication flow to ensure everything works properly.

npm run dev

Things to try out:

1. Email Verification Flow: Try signing up with a new email address. Check your email for the verification link and click it. The verification page will exchange the authorization code for a session using PKCE and redirect you to your profile.
2. Sign In/Out Flow: Try signing out and then signing back in with the same credentials using the server actions.
3. Server-Side Navigation: Notice how navigation links change based on authentication state - the navigation component is rendered server-side and shows different content based on the session.
4. Route Protection: Try accessing protected routes while logged out to see the proxy-based protection in action.
5. Cross-Tab Consistency: Open multiple tabs and test signing out from one tab. Unlike client-side React apps, you’ll need to refresh or navigate to see changes in other tabs due to server-side rendering.

Key Features Demonstrated

Server Components & Actions

Full authentication flow using Next.js App Router with server components and server actions for secure, server-side processing.

PKCE Verification

Server-side /verify page that exchanges authorization codes for sessions using PKCE, with the verifier stored in a cookie and the token exchange performed entirely on the server.

Client/Server Separation

Clear separation between server components for rendering and client components for interactivity, following Next.js best practices.

Error Handling

Comprehensive error handling with URL-based error states and dedicated error pages for different failure scenarios.

Session Management

Server-side session handling with sign out functionality using server actions and proper state management.