Implement robust authentication in Next.js using proxy patterns for JWT validation, role-based access control, and edge-aware session handling.
Why Proxy for Auth
Authentication logic traditionally lives in individual page components or API route handlers. This approach leads to duplicated code, inconsistent enforcement, and the risk of accidentally exposing protected pages. In current Next.js projects, proxy-based request handling provides a cleaner centralized place for authentication checks before route rendering continues.
Proxy executes early in the request lifecycle and still works well with edge-aware authentication flows. This guide covers production patterns for proxy-based authentication, aligned with our server optimization best practices.
Basic Auth Proxy
JWT Token Validation
// proxy.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { jwtVerify } from "jose";
const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!);
const publicPaths = ["/", "/login", "/register", "/forgot-password", "/api/auth"];
const apiPaths = ["/api/"];
export async function proxy(request: NextRequest) {
const { pathname } = request.nextUrl;
// Allow public paths
if (publicPaths.some((path) => pathname === path || pathname.startsWith(path + "/"))) {
return NextResponse.next();
}
// Allow static assets
if (pathname.startsWith("/_next/") || pathname.includes(".")) {
return NextResponse.next();
}
const token = request.cookies.get("auth-token")?.value;
if (!token) {
if (apiPaths.some((path) => pathname.startsWith(path))) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
return NextResponse.redirect(new URL("/login", request.url));
}
try {
const { payload } = await jwtVerify(token, JWT_SECRET);
const response = NextResponse.next();
response.headers.set("x-user-id", String(payload.sub));
response.headers.set("x-user-role", String(payload.role));
return response;
} catch {
// Token expired or invalid
const response = apiPaths.some((path) => pathname.startsWith(path))
? NextResponse.json({ error: "Token expired" }, { status: 401 })
: NextResponse.redirect(new URL("/login", request.url));
response.cookies.delete("auth-token");
return response;
}
}
export const config = {
matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
Role-Based Access Control
Multi-Level Authorization
// lib/auth-proxy.ts
interface RouteConfig {
path: string;
roles: string[];
methods?: string[];
}
const protectedRoutes: RouteConfig[] = [
{ path: "/admin", roles: ["admin"] },
{ path: "/admin/users", roles: ["admin"] },
{ path: "/dashboard", roles: ["admin", "manager", "user"] },
{ path: "/settings", roles: ["admin", "manager"] },
{ path: "/api/admin", roles: ["admin"], methods: ["GET", "POST", "PUT", "DELETE"] },
{ path: "/api/reports", roles: ["admin", "manager"], methods: ["GET"] },
];
export function checkRouteAccess(
pathname: string,
method: string,
userRole: string
): { allowed: boolean; reason?: string } {
const matchedRoute = protectedRoutes.find(
(route) => pathname === route.path || pathname.startsWith(route.path + "/")
);
if (!matchedRoute) {
return { allowed: true };
}
if (!matchedRoute.roles.includes(userRole)) {
return {
allowed: false,
reason: `Role '${userRole}' cannot access ${pathname}`,
};
}
if (matchedRoute.methods && !matchedRoute.methods.includes(method)) {
return {
allowed: false,
reason: `Method ${method} not allowed for role '${userRole}' on ${pathname}`,
};
}
return { allowed: true };
}
Integrating RBAC into Proxy
// proxy.ts (updated with RBAC)
import { checkRouteAccess } from "./lib/auth-proxy";
export async function proxy(request: NextRequest) {
// ... token validation from above ...
try {
const { payload } = await jwtVerify(token, JWT_SECRET);
const userRole = String(payload.role);
const { pathname } = request.nextUrl;
const access = checkRouteAccess(pathname, request.method, userRole);
if (!access.allowed) {
if (pathname.startsWith("/api/")) {
return NextResponse.json(
{ error: "Forbidden", message: access.reason },
{ status: 403 }
);
}
return NextResponse.redirect(new URL("/unauthorized", request.url));
}
const response = NextResponse.next();
response.headers.set("x-user-id", String(payload.sub));
response.headers.set("x-user-role", userRole);
return response;
} catch {
// ... error handling ...
}
}
Session Management
Sliding Session with Token Refresh
// lib/session.ts
import { SignJWT, jwtVerify } from "jose";
const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!);
const TOKEN_LIFETIME = 60 * 60; // 1 hour
const REFRESH_THRESHOLD = 15 * 60; // Refresh when less than 15 min remaining
export async function createToken(user: {
id: string;
email: string;
role: string;
}): Promise<string> {
return new SignJWT({
sub: user.id,
email: user.email,
role: user.role,
})
.setProtectedHeader({ alg: "HS256" })
.setIssuedAt()
.setExpirationTime(`${TOKEN_LIFETIME}s`)
.sign(JWT_SECRET);
}
export async function shouldRefreshToken(token: string): Promise<boolean> {
try {
const { payload } = await jwtVerify(token, JWT_SECRET);
const exp = payload.exp || 0;
const now = Math.floor(Date.now() / 1000);
return exp - now < REFRESH_THRESHOLD;
} catch {
return false;
}
}
export async function refreshToken(token: string): Promise<string | null> {
try {
const { payload } = await jwtVerify(token, JWT_SECRET);
return createToken({
id: String(payload.sub),
email: String(payload.email),
role: String(payload.role),
});
} catch {
return null;
}
}
Auto-Refresh in Proxy
// In proxy.ts, after successful token validation:
const needsRefresh = await shouldRefreshToken(token);
if (needsRefresh) {
const newToken = await refreshToken(token);
if (newToken) {
const response = NextResponse.next();
response.cookies.set("auth-token", newToken, {
httpOnly: true,
secure: true,
sameSite: "lax",
maxAge: TOKEN_LIFETIME,
path: "/",
});
response.headers.set("x-user-id", String(payload.sub));
response.headers.set("x-user-role", String(payload.role));
return response;
}
}
This pattern silently extends active sessions without requiring the user to re-authenticate, while expired sessions redirect to login.
CSRF Protection
For applications using cookie-based sessions, add CSRF protection in middleware:
function validateCSRF(request: NextRequest): boolean {
if (["GET", "HEAD", "OPTIONS"].includes(request.method)) {
return true; // Safe methods don't need CSRF protection
}
const csrfToken = request.headers.get("x-csrf-token");
const csrfCookie = request.cookies.get("csrf-token")?.value;
if (!csrfToken || !csrfCookie) return false;
return csrfToken === csrfCookie;
}
Rate Limiting by Auth Status
Apply different rate limits for authenticated and anonymous users:
// lib/rate-limiter.ts
const rateLimits = new Map<string, { count: number; resetAt: number }>();
export function checkRateLimit(
identifier: string,
limit: number,
windowMs: number
): { allowed: boolean; remaining: number; resetAt: number } {
const now = Date.now();
const entry = rateLimits.get(identifier);
if (!entry || now > entry.resetAt) {
rateLimits.set(identifier, { count: 1, resetAt: now + windowMs });
return { allowed: true, remaining: limit - 1, resetAt: now + windowMs };
}
if (entry.count >= limit) {
return { allowed: false, remaining: 0, resetAt: entry.resetAt };
}
entry.count++;
return { allowed: true, remaining: limit - entry.count, resetAt: entry.resetAt };
}
// In middleware:
const isAuthenticated = !!payload;
const identifier = isAuthenticated ? `user:${payload.sub}` : `ip:${request.ip}`;
const limit = isAuthenticated ? 1000 : 100; // per minute
const { allowed, remaining } = checkRateLimit(identifier, limit, 60000);
if (!allowed) {
return NextResponse.json({ error: "Rate limit exceeded" }, {
status: 429,
headers: { "X-RateLimit-Remaining": String(remaining) },
});
}
Testing Proxy Logic
import { describe, it, expect } from "vitest";
import { checkRouteAccess } from "./lib/auth-proxy";
describe("Route Access Control", () => {
it("blocks non-admin from admin routes", () => {
const result = checkRouteAccess("/admin/users", "GET", "user");
expect(result.allowed).toBe(false);
});
it("allows admin to access admin routes", () => {
const result = checkRouteAccess("/admin/users", "GET", "admin");
expect(result.allowed).toBe(true);
});
it("allows all authenticated users to access dashboard", () => {
const result = checkRouteAccess("/dashboard", "GET", "user");
expect(result.allowed).toBe(true);
});
it("blocks unauthorized API methods", () => {
const result = checkRouteAccess("/api/reports", "DELETE", "manager");
expect(result.allowed).toBe(false);
});
});
Best Practices
- Always use
httpOnlyandsecureflags on auth cookies - Set
sameSite: "lax"or"strict"to prevent CSRF via cookies - Keep JWT payloads small - only include essential claims (user ID, role)
- Use short token lifetimes (1 hour) with sliding refresh
- Log failed authentication attempts for security monitoring
- Handle token refresh transparently - users should never see auth interruptions
- Combine middleware auth with infrastructure-level security for defense in depth
Proxy-based authentication provides a clean separation of concerns, consistent enforcement across all routes, and the performance benefits of early request handling.
Frequently asked questions
Why put authentication in Next.js proxy instead of every page and API route?
Authentication checks scattered across page components and API route handlers lead to duplicated code, inconsistent enforcement and a risk of accidentally exposing a protected page. A proxy.ts file gives Next.js one central place to check each request before route rendering continues. Proxy runs early in the request lifecycle and works with edge-aware authentication flows, so every route is held to the same rules.
How do I verify a JWT in a Next.js proxy.ts file?
Read the token from a cookie such as auth-token and verify it with jwtVerify from the jose library, using a secret loaded from the JWT_SECRET environment variable. On success the proxy calls NextResponse.next() and sets x-user-id and x-user-role headers from the token payload. A missing token gets a 401 JSON error on API paths and a redirect to /login on pages. Expired or invalid tokens get the same responses, and the auth-token cookie is deleted.
Which requests should a Next.js authentication proxy let through without a token?
Public pages and static assets. The example keeps a publicPaths list (/, /login, /register, /forgot-password and /api/auth) and passes those requests straight on with NextResponse.next(). Anything under /_next/ or any path containing a dot is treated as a static asset and skipped as well. The matcher config also excludes _next/static, _next/image and favicon.ico, so the proxy never runs for them.
How do I add role-based access control to Next.js proxy authentication?
Define a list of protected routes, each with a path, the roles allowed and optionally the HTTP methods allowed, then check the role from the verified JWT against it. In the example, a checkRouteAccess(pathname, method, userRole) function finds the matching route and returns whether access is allowed, with a reason when it is not. Denied API requests get a 403 Forbidden JSON response and denied page requests redirect to /unauthorized. Routes that match no entry are allowed.
How do I implement sliding sessions with JWT refresh in Next.js?
Issue short-lived tokens and reissue them in the proxy when they are close to expiring. The example signs HS256 tokens with SignJWT for a 1-hour lifetime and refreshes any token with less than 15 minutes remaining. The proxy sets the new token as the auth-token cookie on the response, with httpOnly, secure, sameSite lax and a maxAge equal to the token lifetime. Active sessions extend silently, while expired sessions still redirect to login.
What security settings should Next.js authentication cookies and JWTs use?
Auth cookies should carry the httpOnly and secure flags, with sameSite set to lax or strict to limit CSRF through cookies. Keep the JWT payload small, with only the claims that matter, such as user ID and role. Use short token lifetimes of about 1 hour with sliding refresh, so users never see an auth interruption. Failed authentication attempts should be logged for security monitoring.
How do I add CSRF protection to a Next.js app that uses cookie sessions?
Compare a CSRF token sent in a request header with the same token stored in a cookie. The example validateCSRF function lets GET, HEAD and OPTIONS through as safe methods. Every other method needs an x-csrf-token header that matches the csrf-token cookie, and the request fails the check if either value is missing or the two differ.
How do I rate limit logged-in and anonymous users differently in Next.js?
Choose the rate-limit key and limit based on whether the request carries a valid token. In the example, authenticated users are keyed by user ID with a limit of 1000 requests per minute, and anonymous visitors are keyed by IP address with 100 per minute. A checkRateLimit function counts requests per key in a 60000 ms window held in a Map. Once the limit is reached, the proxy returns a 429 response with an X-RateLimit-Remaining header.
Read how we handle it in Cloud & Server Management.
Related Articles
The Real Cost of a Next.js Outage - Beyond the Downtime Bill
A Next.js outage costs far more than lost sales for the hour it happens. Here is the full picture - trust, SEO, support load, churn - and how to stop paying it.
Next.jsHow We Run Next.js at Scale on K3s with Zero Downtime
A production-grade guide to running Next.js on K3s with zero downtime - container registry, CI/CD pipelines, rolling updates, Cloudflare CDN and Tunnel, Prometheus monitoring, and automated cache purging.
Next.jsNext.js Edge Functions for Global Performance
Leverage Next.js Edge Runtime and middleware for sub-50ms global response times with geo-routing, A/B testing, and personalized content delivery.