Next.js Authentication: The Complete 2026 Guide

Where Auth Lives in Next.js App Router

Next.js 13+ separates your code into two runtimes: server and client. Auth decisions should happen on the server. If you're checking auth state in a client component to decide what to render, you're doing it in the wrong place — there will be a flash of unauthenticated content before the check resolves.

The right model:

• Middleware / proxy: handles route protection at the edge — before the page renders
• Server Components: access session data directly from the request
• Client Components: receive auth state as props from the server, or via a lightweight hook

This matters because it determines where tokens are stored and how they're validated.

Setup

Install the SDK:

npm install @monocloud/auth-nextjs

Create .env.local with your credentials from the MonoCloud dashboard:

MONOCLOUD_AUTH_TENANT_DOMAIN=https://<your-tenant-domain>
MONOCLOUD_AUTH_CLIENT_ID=<your-client-id>
MONOCLOUD_AUTH_CLIENT_SECRET=<your-client-secret>
MONOCLOUD_AUTH_SCOPES=openid profile email
MONOCLOUD_AUTH_APP_URL=http://localhost:3000
MONOCLOUD_AUTH_COOKIE_SECRET=<random-secret>

Generate a cookie secret with:

openssl rand -hex 32

One File, Full Auth

In Next.js 16+, authentication middleware uses a proxy-based approach. Create proxy.ts in your project root:

import { authMiddleware } from "@monocloud/auth-nextjs";

export default authMiddleware();

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)"],
};

This gives you the entire OpenID Connect flow — redirects, token exchange, cookie-based session storage, silent refresh. By default, every matched route requires authentication. Unauthenticated users are redirected to sign in.

To protect only specific routes (everything else passes through unauthenticated):

import { authMiddleware } from "@monocloud/auth-nextjs";

export default authMiddleware({
  protectedRoutes: ["/dashboard", "/settings", "/api/orders"],
});

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)"],
};

Note: If you need multiple configurations, custom routes, or dependency injection, you can create a MonoCloudNextClient instance manually. For standard setups, the direct authMiddleware() import above is all you need.

Protecting Pages

protectPage() is a HOC that wraps your Server Component. The user object is injected as a prop — you never need to call getSession() manually inside a protected page:

import { MonoCloudUser, protectPage } from "@monocloud/auth-nextjs";

type Props = { user: MonoCloudUser };

function DashboardPage({ user }: Props) {
  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

export default protectPage(DashboardPage);

Unauthenticated users are redirected to sign in. Your component code only runs for authenticated sessions.

To restrict to a specific group (RBAC):

export default protectPage(AdminPage, { groups: ["admin"] });

Users not in the admin group are shown an access denied message before your component renders.

Protecting API Routes

protectApi() wraps your route handler. The handler signature is (req, ctx) — to read the authenticated user inside, call getSession():

import { protectApi, getSession } from "@monocloud/auth-nextjs";
import { NextResponse } from "next/server";
import { db } from "@/lib/db";

export const GET = protectApi(async (req, ctx) => {
  const session = await getSession();
  const orders = await db.orders.findMany({
    where: { userId: session!.user.sub },
  });
  return NextResponse.json(orders);
});

Unauthenticated requests get a 401 before your handler runs. getSession() inside a protected handler is safe — the session is guaranteed to exist.

Server Actions

"use server";

import { protect, getSession } from "@monocloud/auth-nextjs";
import { db } from "@/lib/db";

export async function placeOrder(items: CartItem[]) {
  await protect(); // redirects if not authenticated

  const session = await getSession();
  const userId = session!.user.sub;

  return db.orders.create({
    data: { userId, items, status: "pending" },
  });
}

protect() guards the action — if the session is missing, the user is redirected to sign in and the action body never executes. Retrieve the user via getSession() when you need identity data inside the action.

Reading Auth State Server-Side

import { getSession } from "@monocloud/auth-nextjs";

export default async function HomePage() {
  const session = await getSession();

  if (!session) {
    return <p>You are not signed in.</p>;
  }

  return <p>Hello, {session.user.name}</p>;
}

Client Components

For client-side auth state, use useAuth() from the /client subpath:

"use client";

import { useAuth } from "@monocloud/auth-nextjs/client";

export function UserMenu() {
  const { user, isAuthenticated, isLoading } = useAuth();

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

  if (!isAuthenticated || !user) {
    return <a href="/api/auth/login">Sign in</a>;
  }

  return (
    <div className="flex items-center gap-2">
      <span className="text-sm">{user.name}</span>
      <a href="/api/auth/logout" className="text-sm text-gray-500">Sign out</a>
    </div>
  );
}

To protect a client component with a HOC:

"use client";

import { MonoCloudUser } from "@monocloud/auth-nextjs";
import { protectClientPage } from "@monocloud/auth-nextjs/client";

type Props = { user: MonoCloudUser };

const ProfilePage = ({ user }: Props) => (
  <div>
    <h2>{user.name}</h2>
    <p>{user.email}</p>
  </div>
);

export default protectClientPage(ProfilePage);

Note: protectClientPage() runs in the browser — use protectPage() (server) for anything security-sensitive.

Sign In and Sign Out

Use the <SignIn /> and <SignOut /> components provided by the SDK:

import { getSession } from "@monocloud/auth-nextjs";
import { SignIn, SignOut } from "@monocloud/auth-nextjs/components";

export async function Navbar() {
  const session = await getSession();

  return (
    <nav>
      {session ? (
        <SignOut>Sign out</SignOut>
      ) : (
        <SignIn>Sign in</SignIn>
      )}
    </nav>
  );
}

The SDK registers all required auth routes automatically. No route handler file needed.

What Not to Do

• Don't store tokens in localStorage. Any XSS on your domain exposes them. The SDK uses httpOnly cookies.
• Don't check auth in client components for security. Client-side auth checks are UI hints only. Use protectPage() or protectApi() for enforcement.
• Don't roll your own JWT validation. JWKS rotation, clock skew, audience verification, algorithm pinning — there are eight ways to get this wrong and you'll find most of them in production.

Next Steps

• Docs: MonoCloud Next.js SDK
• Working example: MonoGrub on GitHub
• Add RBAC: Pass groups: ["admin"] to protectPage() or protectApi()
• Profile management: MonoCloud Management SDK

Start Building for Free with MonoCloud

We built MonoCloud after learning for ourselves that authentication and user management are hard. But we knew that building an easy-to-use tool wasn't enough. Our platform isn't just about saving you a few days of coding. Instead, it's about adding the expertise you need to secure your software for the long term.

You can start building with MonoCloud today. Sign up now for your free account. Click here monocloud.com