DEV Community: MonoCloud

Next.js Authentication: The Complete 2026 Guide

Shivangi Tripathi — Fri, 12 Jun 2026 12:03:18 +0000

Most Next.js authentication tutorials teach you how to build the plumbing. This one skips that. You don't need to write session logic, token exchange, or JWT verification yourself — and you definitely shouldn't. You need to know where auth lives in a Next.js app, how the App Router changes things, and how to ship it fast without painting yourself into a corner.

A production Next.js app needs session management that survives page refreshes, protected routes that redirect unauthenticated users without flicker, API endpoints that reject requests without a valid token, Server Actions that verify identity before running any business logic, and a sign-in/sign-out flow that handles the OAuth/OIDC roundtrip.

Let's go through each one.

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

OAuth for SaaS: What Every Developer and Technical Leader Needs to Know

MonoCloud Admin — Mon, 23 Mar 2026 20:51:36 +0000

If you're building a SaaS product today, OAuth isn't optional — it's foundational. It's the protocol behind "Sign in with Google," third-party integrations, API access control, and the secure service-to-service communication that holds modern platforms together.

Yet OAuth remains widely misunderstood. Teams confuse it with authentication, misuse its flows, or bolt it on as an afterthought, only to face security gaps and painful refactors later.

This guide cuts through the confusion. It explains what OAuth actually does, why SaaS platforms need it, which flows matter for which use cases, and the mistakes that trip up even experienced teams.

Why SaaS Applications Can't Avoid OAuth

A modern SaaS platform is rarely a single application. It's typically a constellation of components — a web dashboard, a mobile app, public APIs, third-party integrations, and a cluster of internal microservices — all needing access to shared resources like user data, billing records, and analytics.

The challenge: how do you let all of these components access the right data, for the right users, without passing around passwords or hardcoding secrets?

OAuth solves this by issuing tokens that represent delegated permissions. Instead of sharing credentials, an application receives a short-lived token that grants specific, limited access. The user stays in control. The credentials stay safe.

The Four Roles in Every OAuth Flow

OAuth defines four participants. Understanding who does what is the first step to implementing it correctly.

Resource Owner — the user who owns the data. In a SaaS context, this is your customer granting permission for an app to access their account.

Client — the application requesting access. This could be your web frontend, a mobile app, a CLI tool, or a third-party integration built on your API.

Authorization Server — the system that authenticates users, enforces permissions, and issues tokens. This is the engine of the whole flow. It handles consent screens, validates credentials, and decides what access to grant.

Resource Server — the API that holds protected data. It receives requests, validates the attached token's signature, expiration, audience, and scopes, and then either allows or rejects the request.

In practice, many SaaS teams run the authorization server as a managed service and distribute resource servers across their API landscape.

Access Tokens: The Core Mechanism

At the heart of OAuth is a simple idea: instead of giving an application a user's password, you give it a token.

That token represents a specific set of permissions, is scoped to a specific API, and expires after a defined period. The API receiving the token validates it and grants access accordingly.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

This approach decouples authentication from authorization. The API doesn't need to know how the user signed in — it only needs to know that the token is valid and carries the right permissions.

Scopes: Fine-Grained Permission Control

Scopes define what a client application is allowed to do with a token.

A well-designed SaaS API uses granular scopes rather than broad, all-or-nothing permissions:

Scope	What It Allows
`read:products`	View the product catalog
`write:products`	Create or update products
`read:invoices`	View invoice data

When a token arrives at your API, the resource server checks whether its scopes match the operation being requested. A token with read:products can't update anything — the request gets rejected.

This model lets SaaS platforms implement nuanced permission systems across multiple APIs without reinventing access control for each one.

OAuth vs. API Keys vs. Session Cookies

OAuth isn't the only way to secure access. Here's how it compares to the other common approaches:

API keys are simple and useful for basic integrations, but they represent an application rather than a user, and offer no built-in permission model.

Session cookies work well for traditional web apps, but they're tied to browser sessions and don't translate to API-first architectures.

OAuth tokens are purpose-built for the kind of distributed, multi-client, API-driven systems that SaaS platforms actually are.

OAuth vs. OpenID Connect: Authorization vs. Authentication

One of the most common points of confusion: OAuth is not an authentication protocol. It's an authorization framework.

OAuth answers the question: "What is this application allowed to do?"

Authentication — proving who the user is — is handled by OpenID Connect (OIDC), which is a layer built on top of OAuth.

	OAuth	OIDC
Purpose	Authorization	Authentication
Token	Access Token	ID Token
Answers	"What can this app do?"	"Who is this user?"

Most SaaS platforms need both. OIDC handles user login and identity. OAuth handles API access and delegated permissions. Together, they form the standard identity and authorization stack for modern applications.

Choosing the Right OAuth Flow

Different client types require different OAuth flows. The choice depends on where the client runs, whether it can securely store secrets, and whether a user is involved.

Authorization Code Flow

The gold standard for web applications. The client exchanges a short-lived authorization code for tokens on the backend, keeping tokens out of the browser entirely. Ideal for SaaS dashboards and server-rendered applications.

Authorization Code + PKCE

An extension of the authorization code flow designed for clients that can't keep secrets — like single-page apps and mobile apps. PKCE (Proof Key for Code Exchange) adds a cryptographic challenge that binds the authorization request to the token request, preventing interception attacks. This is now the recommended default for any public client.

Client Credentials

Used when no user is involved. The application authenticates with its own credentials and receives a token representing itself. This is the standard flow for service-to-service communication, background jobs, and internal platform APIs.

Device Authorization Flow

Designed for devices with limited input capabilities — smart TVs, IoT devices, CLI tools. The user completes authentication on a separate device by visiting a URL and entering a code.

Refresh Tokens

Not a standalone flow, but a critical companion to the others. Refresh tokens let applications obtain new access tokens without forcing the user to sign in again, enabling long-lived sessions while keeping access tokens short-lived.

Five Mistakes That Trip Up SaaS Teams

1. Building it all from scratch

Implementing an authorization server, token lifecycle management, scope enforcement, and OIDC compliance is a significant engineering investment — and a risky one if security isn't your team's core expertise. Managed identity platforms exist precisely to solve this problem reliably.

2. Overly broad scopes

A scope called admin that grants access to everything defeats the purpose of scoped authorization. Use granular scopes like read:products and write:orders. If a token is compromised, the blast radius stays contained.

3. Long-lived access tokens

Access tokens should expire in minutes, not hours or days. A typical lifetime is 5 to 60 minutes. Refresh tokens handle renewal. Short-lived tokens limit the damage window if one is leaked.

4. Missing audience restrictions

Tokens should specify which API they're intended for. Without audience validation, a token issued for your billing API could be replayed against your admin API. Always set and validate the aud claim.

5. Treating login as authorization

A successful user login doesn't mean every API should accept every request. APIs should still validate audience, scopes, and token type independently. Authentication tells you who someone is; authorization tells you what they're allowed to do.

Where to Go From Here

OAuth has become the standard authorization model for modern SaaS platforms. It gives teams a consistent, secure way to protect APIs, enable integrations, and manage access across users, applications, and services.

Getting it right means choosing the correct flows for your client types, designing granular scopes, keeping tokens short-lived, and validating them properly at every API boundary.

If you'd rather focus on building your product than managing OAuth infrastructure, MonoCloud provides a complete authentication and authorization platform built for SaaS — handling OAuth, OIDC, user management, and access control so your team doesn't have to build and maintain it from scratch.

Add Authentication to Next.js With One Line of Code

MonoCloud Admin — Tue, 17 Mar 2026 20:53:56 +0000

export default authMiddleware()

That’s it. One line in your middleware file and your Next.js app has authentication — sign-up, sign-in, sign-out, session management, and protected routes. No wrestling with JWTs, no hand-rolling session logic, no third-party cookie headaches. Just drop it in and move on.

We built MonoGrub, a sample food ordering app, to show what this looks like in a real project. It’s open source, runs locally in five minutes, and covers the auth patterns you’ll actually need in production. Let’s walk through what it does.

One Line, Full Auth

When you call authMiddleware(), MonoCloud handles the entire OpenID Connect flow behind the scenes — redirects, token exchange, cookie-based sessions, silent refresh. Your users get a polished sign-up and sign-in experience, and you don't write a single line of auth plumbing.

But the real power shows up when you need more control. Want to lock down your admin section to a specific group of users? Pass a config:

export default authMiddleware({
  protectedRoutes: [
    { routes: ["/admin"], groups: ["admin"] }
  ],
});

That’s role-based access control, declared at the middleware layer, with zero custom logic in your page components. Add more routes, more groups, more rules — it’s all configuration, not code. By default, unauthorized users get a 403. Want something friendlier? Add an onGroupAccessDenied handler to redirect them wherever you like — MonoGrub sends them to a custom access-denied page.

Protecting Routes, APIs and UI

Authentication tells you who someone is. But most apps need to go further — you need to control what they can do. MonoGrub demonstrates this across every layer of a Next.js app.

Server Actions — Every sensitive operation in MonoGrub starts with a call to protect(). This validates the user's session server-side before any business logic runs. If the session is expired or invalid, the user is redirected to the sign-in page. No ambiguity, no race conditions.

API Routes — MonoGrub’s API endpoints use a protectApi() helper that gates access by auth status or group membership. The user's identity comes from the server-side session — not from anything the client submits — which eliminates an entire class of spoofing vulnerabilities.

Pages — For pages that require authentication, MonoGrub wraps them with protectPage(). If an unauthenticated user tries to access a protected page, they're automatically redirected to sign in — no manual checks or redirect logic needed in your component.

UI Components — Not everything needs a full page redirect. MonoGrub uses the client-side <Protected> component to conditionally render UI based on auth status. For example, the "Place Order" button is wrapped in <Protected> with a fallback that prompts the user to sign in. Authenticated users see the button; everyone else sees a sign-in prompt — no useEffect, no loading flicker, no auth state wiring.

The pattern is consistent: declare your access rules up front, and let MonoCloud enforce them. Your application code stays focused on what it’s actually supposed to do.

Profile Management, Without a User Table

Once your users are signed in, they’ll want to manage their accounts. MonoGrub handles profile updates — name changes, password resets — entirely through MonoCloud’s Management SDK. There’s no custom user table to maintain, no password hashing to get right, no “forgot password” flow to build from scratch.

Updating a user’s name is a single SDK call. Changing a password is another. After any update, we refresh the session so the UI stays in sync.

This is the kind of feature that’s easy to underestimate. It’s not glamorous, but building it from scratch is months of work you’ll never get back. With MonoCloud, it’s already done.

What MonoGrub Covers

To recap, here’s what you’ll find in the sample app:

Sign-up, sign-in, sign-out powered by MonoCloud’s OIDC flow
Route protection via middleware — both auth-required and role-required
Admin dashboard gated by group membership
Profile management using the Management SDK (name updates, password changes)
Protected API routes with server-side identity verification
Role-based UI — the navbar adapts based on the user’s group membership

Get It Running

Clone the repo, create a free MonoCloud account, add your credentials, and start the dev server:

git clone https://github.com/monocloud/monogrub-nextjs-demo.git
cd monogrub-nextjs-demo
npm install

Create a .env.local file in the project root with your MonoCloud credentials:

MONOCLOUD_AUTH_TENANT_DOMAIN=<your-tenant-domain>
MONOCLOUD_AUTH_CLIENT_ID=<your-client-id>
MONOCLOUD_AUTH_CLIENT_SECRET=<your-client-secret>
MONOCLOUD_AUTH_SCOPES=openid profile email groups
MONOCLOUD_AUTH_APP_URL=http://localhost:3000
MONOCLOUD_AUTH_COOKIE_SECRET=<your-cookie-secret>
MONOCLOUD_AUTH_REFETCH_USER_INFO=true
MONOCLOUD_AUTH_REFETCH_STRICT_PROFILE_SYNC=true
MONOCLOUD_API_KEY=<your-monocloud-api-key>

Then fire it up:

npm run dev

Open http://localhost:3000, and you’ve got a fully authenticated app running locally.

Ship Auth, Don’t Build It

Every hour you spend building authentication is an hour you’re not spending on your product. MonoCloud gives you production-grade auth with minimal integration effort — start with one line of middleware, and scale up to protected routes, RBAC, and user management as you need them.

Explore the source, adapt the patterns, and ship.

Want to dig deeper? Start with the MonoCloud Docs, explore the Management SDK, or clone MonoGrub and start hacking.